Macros are more and more used within SAP ECTR projects to enhance SAP ECTR with customer-specific requirements.
Purpose of this articel is to get a better understanding of macros in general, show the possibilites with macros and give some practical examples.

Table of Contents

Theory

Introduction of some basic terms

The following section contains a description of basic terms for the sake of clarity.

1. Smartlists (Persistent lists)
2. Object lists (Temporary lists, related to an SAP ECTR session)
3. Container (Enhancement options via SmartContainer)
4. Functions (Functions which can be executed in SAP ECTR, called FNC or OMF)

Origin and Technology

Originally, macros had been designed to perform queries in a generic manner and to replace the query folders. For this purpose, Smartlists were introduced.
A Smartlist represents specific search queries. These search queries are persistently present in ECTR. An example is a search for material attributes which then not represent the matching materials but the linked documents to those materials (see https://wiki.scn.sap.com/wiki/x/MwBuGg).

Installation and Editor

The relevant configuration for using macros in SAP ECTR is included in the basic BC Sets (Backend) and the basic DType configuration (Frontend) in the standard installation of SAP ECTR.
The macros can be used with a standard installation of SAP ECTR

Macros are represented in SAP ECTR in the following way:

For the creation of a new macro, proceed as follows:

Right-click a folder and select New → Document (choose the mentioned DType group and DType):

After a macro has been created, right-click the macro to use the specific functions in the context menu:

Basics

There are three basic technologies with respect to the ECTR-specific functions within the macros.

KeyList

• KEYLIST_FROM_REFOBJ - creates a KeyList for a referenced object (example: DIR for smart container) 
• KEYLIST_FROM_CONTEXT creates a KeyList for objects in a window (example: selected object in the Desktop window)
• KEYLIST_FROM_SET - creates KeyList on the basis of an ObjectSet
• KEYLIST_FROM_OBJECTLIST - creates a KeyList on the basis of an existing object list

ObjectSet

• CREATE_SET: Creates a set in SAP containing the objects in a keylist.
• TRANSFORM_SET: Transforms an existing set by applying certain rules:
  • "doc_to_latest“ returns the latest version
  • "doc_to_released“ returns "released" documents
  • "doc_to_mat“ returns linked materials
  • "mat_to_doc“ returns linked documents

Usage of macros in SAP ECTR

Macros in SAP ECTR can be used to implement the following enhancements to build up customer-specific enhancements.

Smartlists as persistent search queries. Using the macro (local file or document with macro file).

SmartContainers as containers under a reference object. The determination of the container content is defined via macro (local file)

Functions using the macro (local file or document with macro file) integrated in a generic SAP ECTR function.

• fnc.execute.macro(<SAP-KEY>)
• fnc.execute.macro(<file.txt>)

Practice

To work practically with macros in different application scenarios, there are several examples which explain how to work with macros.
The macros from the examples (section "Macro") can be entered into the Editor by copy&paste.

Example 1 - Simple Search

Example 1.1 - Search for document type

Use Case:

• Search for document type "PIC"
• Output as objectlist

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1: Define PARAMETER MAP
P_docSearch = PARAMETER_MAP( "doc_fields" )
P_docSearch.DOCUMENTTYPE = "PIC"

// Step 2: Define SEARCH
SET_docSearch = SEARCH( "doc", P_docSearch )

// Step 3: Create KEYLIST from SET
KL_docSearch = KEYLIST_FROM_SET( SET_docSearch )

// Step 4 : Output KEYLIST as OBJECTLIST
WRITE_OBJECTLIST( KL_docSearch, "MACRO 1.1: Document Search type PIC" )

Example 1.2 - Search for document type and description

Use Case:

• Search for document type "PIC"
• Dialog for user to insert the description as additional search criteria
• Output as objectlist

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1      : get user input
V_user_input = ASK_USER( "Description", "Please insert the document description" )

// Step 2      : define PARAMETER MAP
P_docSearch = PARAMETER_MAP( "doc_fields" )
P_docSearch.DOCUMENTTYPE = "PIC"
P_docSearch.DESCRIPTION = V_user_input

// Step 3      : define SEARCH
SET_docSearch = SEARCH( "doc", P_docSearch )

// Step 4      : create KEYLIST
KL_docSearch = KEYLIST_FROM_SET( SET_docSearch )

// Step 5      : output KEYLIST as objectlist
WRITE_OBJECTLIST( KL_docSearch, "MACRO 1.2: Document Search type PIC and description" )

Example 1.3 - Search for document type, description and environment variable

Use Case:

• Search for document type "PIC"
• Dialog for user to insert the description as additional search criteria
• Add search criteria username from environment variable
• Output as objectlist

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1      : get user input
V_user_input = ASK_USER( "Description", "Please insert the document description" )

// Step 2      : read user name
V_user_name = READ_ENVVAR( "PLM_USER" )

// Step 3      : define PARAMETER MAP
P_docSearch = PARAMETER_MAP( "doc_fields" )
P_docSearch.DOCUMENTTYPE = "PIC"
P_docSearch.DESCRIPTION = V_user_input
P_docSearch.USERNAME = V_user_name

// Step 5      : define SEARCH
SET_docSearch = SEARCH( "doc", P_docSearch )

// Step 6      : create KEYLIST from SET
KL_docSearch = KEYLIST_FROM_SET( SET_docSearch )

// Step 7      : output KEYLIST as objectlist
WRITE_OBJECTLIST( KL_docSearch, "MACRO 1.3: Document Search type PIC, description and actual User" )

Example 2 - Search with masks

Example 2.1 - Search for documents via mask (output objectlist)

Use Case:

• Search for documents using the standard search mask
• Output as objectlist

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1      : get input from mask
P_docSearch = GET_MASK_INPUT( "STANDARD_DOC", "Standard Document", "DOC", "TEST" )

// Step 3      : define SEARCH
SET_docSearch = SEARCH( "doc", P_docSearch )

// Step 4      : create KEYLIST from SET
KL_docSearch = KEYLIST_FROM_SET( SET_docSearch )

// Step 5      : output KEYLIST as objectlist
WRITE_OBJECTLIST( KL_docSearch, "MACRO 2.1: Document search via  mask" )

Example 2.2 - Search for documents via mask (output smartlist)

Use Case:

• Search for documents using the standard search mask
• Output as smartlist

Usage:

• The macro can be used in a smartlist

Macro:

// Step 1      : get mask input as PARAMETER MAP
P_docSearch = GET_MASK_INPUT( "STANDARD_DOC", "Standard Document", "DOC", "TEST" )

// Step 2      : define SEARCH
SET_docSearch = SEARCH( "doc", P_docSearch )

// Step 3      : create KEYLIST from SET
KL_docSearch = KEYLIST_FROM_SET( SET_docSearch )

// Step 4      : output KEYLIST as smartlist
WRITE_RESULTLIST( KL_docSearch )

Example 3 - Simple Referenced Objects

Example 3.1 - Select document(s)

Use Case:

• Get selected document(s) from SAP ECTR Desktop window as input
• Output as objectlist

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1      : Get selected document
KL_docs = KEYLIST_FROM_CONTEXT( "ctx_desk", "selected", "doc" )

// Step 2      : Output KEYLIST as objectlist
WRITE_OBJECTLIST( KL_docs, "MACRO 3.1: Selected document(s)" )

Example 3.2 - Select document and explode structure

Use Case:

• Get selected document from SAP ECTR Desktop window as input
• Get all documents from the document structure of the selected document
• Output as objectlist

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1      : Get selected document
KL_docs = KEYLIST_FROM_CONTEXT( "ctx_desk", "selected", "doc" )

// Step 2      : Create a SET from the selected document
SET_docs = CREATE_SET( KL_docs )

// Step 3      : Define transformation - get all structure documents to selected document
SET_structure = TRANSFORM_SET( SET_docs, "expand_structure" )

// Step 4      : Create KEYLIST from SET
KL_structure = KEYLIST_FROM_SET( SET_structure )

// Step 5      : Output KEYLIST as objectlist
WRITE_OBJECTLIST( KL_structure, "MACRO 3.2: All documents from document structure of selected document" )

Example 4 - Advanced Referenced Objects

Example 4.1 - Select document, explode structure and filter

Use Case:

• Get selected document(s) from SAP ECTR Desktop window as input
• Get all documents from the document structure of the selected document
• Filter for released documents
• Output as objectlist

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1      : Get selected document
KL_docs = KEYLIST_FROM_CONTEXT( "ctx_desk", "selected", "doc" )

// Step 2      : Create a SET
SET_docs = CREATE_SET( KL_docs )

// Step 3      : Define transformation - get all structure documents to selected document
SET_structure = TRANSFORM_SET( SET_docs, "expand_structure" )

// Step 4      : Define PARAMETER_MAP for FILTER function
P_statusFilter = PARAMETER_MAP( "doc_filter_fields" )
P_statusFilter.DOKST = "FR"

// Step 5      : FILTER transformed SET for released documents
SET_released = FILTER( SET_structure, "doc", P_statusFilter)

// Step 6      : Create KEYLISTS from SET
KL_released = KEYLIST_FROM_SET( SET_released )

// Step 7      : Output KEYLISTS as objectlists
WRITE_OBJECTLIST( KL_released, "MACRO 4.1: All released documents from document structure of selected document" )

Example 4.2 - Select document, explode structure, filter and use SAP ECTR function

Use Case:

• Get selected document(s) from SAP ECTR Desktop window as input
• Get all documents from the document structure of the selected document
• Filter for released documents
• Filter for unreleased documents
• Open unreleased documents in "Change Status" dialog

Usage:

• The macro can be used as function (FNC) using fnc.execute.macro(<SAP-KEY>).

Macro:

// Step 1      : Get selected document
KL_docs = KEYLIST_FROM_CONTEXT( "ctx_desk", "selected", "doc" )

// Step 2      : Create a SET
SET_docs = CREATE_SET( KL_docs )

// Step 3      : Define transformation - get all structure documents to selected document
SET_structure = TRANSFORM_SET( SET_docs, "expand_structure" )

// Step 4      : Define PARAMETER MAP for FILTER function
P_statusFilter = PARAMETER_MAP( "doc_filter_fields" )
P_statusFilter.DOKST = "FR"

// Step 5      : FILTER transformed SET for released documents
SET_released = FILTER( SET_structure, "doc", P_statusFilter)

// Step 6      : Determine all unreleased documents
SET_unreleased = OPERATION_SET( "complement", SET_structure, SET_released )

// Step 7      : Create KEYLISTS from SET
KL_unreleased = KEYLIST_FROM_SET( SET_unreleased )

// Step 8      : Open "Change Status" dialog with all unrelased documents
CALL_OMF( "fnc.doc.status.change", KL_unreleased )

Example 5 - SmartContainer

Example 5.1 - SmartContainer for explode structure and filter

Use Case:

• Get referenced document as input (document above the container)
• Get all documents from the document structure of the referenced document
• Filter for released documents
• Output as resultlist

Usage:

• The macro can be used as SmartContainer
• Example:
  • Macro as local file "releasedComponents.txt" in ...\customize\scripts\macros\...
  • SmartContainer definition in ...\customize\config\default.txt
    plm.smart.container.MACRO_51.name = released Components
    plm.smart.container.MACRO_51.macro = releasedComponents.txt
    plm.smart.container.MACRO_51.icon = {0}/sap/done
  • SmartConatiner usage in ...\applications\ugs\customize\config\default.txt (Example for Enhancement of NX 3D-Model Containers)
    plm.om.DOC.containers.UGM = MASTERMODEL;OLINKS;VERSIONS;SOURCEDOC;ORIGINALS;COMPS;WLINKS;WHEREUSED;CLASSES;SMART_CONT(MACRO_51)

Macro:

// Step 1      : Get referenced document
KL_doc = KEYLIST_FROM_REFOBJ( )

// Step 2      : Create a SET
SET_doc = CREATE_SET( KL_doc )

// Step 3      : Define transformation - get all structure documents to the referenced document
SET_structure = TRANSFORM_SET( SET_doc, "expand_structure" )

// Step 4      : Define PARAMETER MAP for FILTER function
P_statusFilter = PARAMETER_MAP( "doc_filter_fields" )
P_statusFilter.DOKST = "FR"

// Step 5      : FILTER transformed SET for released documents
SET_released = FILTER( SET_structure, "doc", P_statusFilter)

// Step 6      : Create KEYLIST from SET
KL_released = KEYLIST_FROM_SET( SET_released )

// Step 7      : Output KEYLISTS as resultlist
WRITE_RESULTLIST( KL_released )

Tips & Tricks

Testing via "WRITE-OBJECTLIST"

For macros, which are to be used for Smartlists or SmartContainers, it is advisable at first to test them in such a way that the results are output in an objectlist.

Testing via KEYLIST_FROM_CONTEXT

For macros, which are to be used for SmartContainers, it is advisable to test them at first in such a way that the reference object can be selected in the Desktop window.

Having tested them sucessfully, KEYLIST_FROM_CONTEXT can be replaced by KEYLIST_FROM_REFOBJ.

SAP-KEY for fnc.execute.macro(<SAP-KEY>)

When adding a macro that was created as a document with a macro file, the SAP-KEY must be specified as a parameter (fnc.execute.macro (<SAP-KEY>).

This SAP KEY can be displayed as an attribute on the DIR and copied by copy&paste.