How to configure the distribution of SAP ECTR configurations via SAP system

Since SAP ECTR 5.1.11.0 it is possible to distribute the Configurations of a SAP ECTR via SAP System.

0 Use Case

Optimize the distribution of SAP ECTR configuration changes for users and administrators

1 Distribute configuration via SAP system

The SAP Engineering Control Center configuration can be distributed via the SAP backend system. To do this, the SAP Engineering Control Center configuration is stored using a document info record (ECTR_CONF_<major>.<Minor>.<Incremental> - AUX - 000) whose original is a ZIP archive.

  The configuration distribution via the SAP system requires the document type "AUX". Make sure that this exists in the SAP system.  This can not be changed in any configuration. The document type "AUX" can be activated using a BC Set supplied. For more information on BC Sets, see the Operations Guide.

Naming of the DIR

Please note that the document info record created follows the naming rules of SAP Engineering Control Center.

Thus, a DIR created in a SAP Engineering Control Center for SAP S/4HANA contains the version number 5.X.

1.1 Read configuration from the SAP system

When starting SAP Engineering Control Center and logging on to the SAP system, ECTR checks whether a newer, released configuration than the local configuration exists in the SAP system.
If so, the newer configuration is checked out and unpacked to the local configuration directory.
Since a user with a SAP Engineering Control Center installation can log on to different SAP systems, of which all contain a different configuration document, the configuration directory is SAP system-dependent:

• • %PLM_SAPCONFIG_BASEDIR%\%PLM_INSTID%\%PLM_SYSTEM%_%PLM_CLIENT%_%PLM_USER 
  • After logging on to the SAP system, the internal environment variable PLM_INSTDIR_CONF is switched to the SAP system-dependent configuration directory

If an administrator has made changes to his local configuration, he will be asked if he wants to keep his local configuration or get the latest version from the SAP system before overwriting the configuration.

Document version

If a non-admin user logs on to SAP Engineering Control Center, the currently valid released version of the configuration document is always used.
If no valid released version already exists, the last version of the configuration document is used. Administrators always get the last version of the configuration document.
However, the behavior for administrators can be changed by using the preference variable from the file SAPLogon.txt.

1.2 Write configuration to the SAP system 

The admin function Administrator→System Setup → Transfer ... (fnc.configuration.upload) is used to upload the configuration.

The function checks whether the local configuration has been changed since the start of SAP Engineering Control Center session.
If this is the case, SAP Engineering Control Center must first be restarted before the configuration can be uploaded.
This is to prevent an untested configuration from being uploaded. Then it is checked whether the last version of the configuration document has been released in the SAP system.
If this is the case, the administrator is asked if a new version should be created or if the upload of the configuration should be aborted.
The following folders from the directory tree of PLM_INSTDIR_CONF will then packed into a ZIP archive:

• • customize

  • templates

Except for these files:

• • *.pdb
  • __sap.dir
  • conf.di
  • originalfiles.json

The last version of the configuration document will be checked in. Finally, the uploaded configuration is checked for changes that are relevant for the backend logic.
If this is the case, the user is asked if they should be activated in the backend.

2 Configuration

2.1 Activation using the installer of SAP Engineering Control Center

For this function, the add-on backendConfig was created which can be selected in the SAP ECTR installer.
This add-on contains the file backendConfig.bat, which is located under addons\backendConfig\basis\config.
The file is called and executed by the basis\config\plm_initialize.bat.
With this file, the following settings are made:

1. The activation of the function via "PLM_USE_SAPCONFIG"
2. The configuration of the path "%LOCALAPPDATA%\SAP\ECTR\conf" as a storage location of the configuration via "PLM_SAPCONFIG_BASEDIR"
3. Activation of a Java classloader for custom Java classes under "PLM_SAPCONFIG_BASEDIR".

The settings can be changed by the customer in customize\config\plm_initialize.bat.

2.2 .configignore - Customer-specific rules to define, which files are to be uploaded

From version 5.1.11.1 it is possible with the help of .configignore files to extend and overwrite the rules, which define the files and folders that are to be uploaded. The use of these files is explained below using an example.

Example request:

In the directory customize\config\, all files ending in "basic.txt" except for the file "menu_suppress_GuiCmds-basic.txt" should be ignored.

Solution option 1:

Create the file .configignore in the directory customize\config (tip: enter .configignore. as file name in the Windows Explorer)

# ignore each file ending with basic.txt in this directory
/*basic.txt
# but menu_suppress_GuiCmds-basic.txt
!/menu_suppress_GuiCmds-basic.txt

Solution option 2:

Create the file .configignore in the root directory (tip: enter .configignore. as a file name in the Windows Explorer)

# ignore each file ending with basic.txt in /customize/config directory
/customize/config/*basic.txt
# but menu_suppress_GuiCmds-basic.txt
!/customize/config/menu_suppress_GuiCmds-basic.txt

General information about the .configignore files

• The rules delivered with SAP Engineering Control Center can be found in the file \basis\aux-files\config-exclude.
• The rules within a file are processed from top to bottom. It is therefore only possible to overwrite rules that are above the rule.
• In .configignore files you can overwrite the rules of all .configignore files of the directories.
• A .configignore file can only affect files that are in the same directory or in a subdirectory. A .configignore file is only processed if it is in a directory that itself has not already been ignored by a rule.

Information about the syntax of the .configignore files

• Lines starting with a hashtag (#) are comments and are ignored during processing. With rules beginning with an exclamation mark (!), files can be included again that were previously ignored. The asterisk (*) represents any string, but only within a directory.
• A double asterisk (**) represents any string across multiple directories. Paths starting with a slash will be evaluated relatively to the directory where the .configignore file is located.

2.2 plm_initialize.bat

The environment variable PLM_USE_SAPCONFIG controls the activation of the function and its setting also defines whether after the logon the internal environment variable PLM_INSTDIR_CONF is switched over to the SAP system-dependent configuration directory. 

...
 
REM ---------------------------------------------------------------------------
REM The ECTR configuration can also be stored in the SAP system using a
REM special system document. In this case, the local configuration will be
REM checked against the configuration stored in SAP and, if needed, updated.
REM You can specify the base directory for the local copy of the configuration,
REM ECTR will add additional directories to allow for different SAP systems.
REM If there is nothing in the specfied directory, ECTR will use the data
REM in the local installation.

REM   set PLM_USE_SAPCONFIG=True
REM   set PLM_SAPCONFIG_BASEDIR=%LOCALAPPDATA%\SAP\ECTR\conf

...

2.3 SAPlogon.txt

Optionally, the document version to be used at startup can be forwarded.
This preference is only read for administrators.
The options are:

• latest - the most recent version (by default or admins)
• latest_released - the last released version
• released_today - the currently valid released version (by default for non-admins)
• XX - a fixed version number (e.g. 01)

This must be set in the file SAPLogon.txt:

...
# -----------------------------------------------------------------------------
# 1.5    Sap Configuration Settings
# 
# As part of the Function for distributing ECTR Configurations via SAP System
# The Administrator can use an Option for selecting the Version of the Configuration
# that he will use.
#    sap.logon.configuration.document.version = latest | latest_released | released_today | XX
...

2.4 dtype.xml

The configuration document required a DType, which has the primary_workstation_application as "zip" so that the tracking of changes works.

This DType configuration can only be used to change the appearance (icons...) and the workstation application for the ZIP - file. Other settings like "document type" will not be considered. 
For instance:

<!--   ECNFG Configuration DType    -->
<!-- ============================================================================================================================================================ -->

      <DType type="master"
            identifier="ECNFG"
            include_template="DEFLT"
            application_type="ZIP"
            group="OTHER"
            >
<!-- ============================================================================================================================================================ -->
           
         <description language="DE" text="ECTR Konfiguration"/>
         <description language="EN" text="ECTR Configuration"/>
         
         <icon>                <icondef icon_position="1" icon_group="default" use_status_color="yes"
                                        icon_identifier="{0}/sap/file_icons_dyn/file_zip"/>                                   
                               <icondef icon_position="2" icon_group="default" use_status_color="no"
                                        icon_identifier="flag/flag_version_$(HER)$(HNV)$(HRV)"/>
                               <icondef icon_position="3" icon_group="default" use_status_color="no"
                                        icon_identifier="flag/flag_primaryfiles_moe$(MOE)_moc$(MOC)_iu$(IN_USE_BY_OTHER)_ium$(MOC_BY_OTHER)"/>
                               <icondef icon_position="3" icon_group="released" use_status_color="no"
                                        icon_identifier="flag/doc_is_released"/>
                               <icondef icon_position="3" icon_group="blocked" use_status_color="no"
                                        icon_identifier="flag/doc_is_blocked"/>
                               <icondef icon_position="3" icon_group="inchange" use_status_color="no"
                                        icon_identifier="flag/doc_is_in_change"/>
                               <icondef icon_position="3" icon_group="archived" use_status_color="no"
                                        icon_identifier="flag/doc_is_archived"/>
         </icon>

         <program_options      show_for_create="no"
                               has_primary_application="yes"
                               dirty_flag="no"
                               attempt_status_change_on_checkin="no"
                               function_group="ECNFG">

                <new_version
                               status_list="FR"
                               ignore_wsappl_list="ZIP"
							   rename_master_original="no"
                               ignore_nm_dtype_list="DRWK;DRAW" />

         </program_options>                      

                               
         <document_create      change_to_after_create_status="AC"/>
        
         <primary_application  primary_workstation_application="ZIP"/>
      </DType>

2.5 menu.guidef

• In order to enable an admin to overwrite his local configuration with the selected one by right-clicking on a configuration document, the omf fnc.configuration.use must be entered in the menu.guidef.
• In addition, an OMF can be entered to compare the configurations (see Compare Configurations)
• Finally, the OmfConfigurationUpload should be configured in the admin menu

...     
# --------------------------------------------------------------------------------------
# 2.5.2.14  (CNF) ECTR Configuration Document

+  om.popup.menu.DOC.ECNFG              = fnc.doc.status.change
                                        = fnc.configuration.use
                                        = fnc.configuration.compare
                                        = ? CLPBRD_REFRESH_DOC
...

# *****************************************************************************
# 3.  Administrator menu function definition
# *****************************************************************************
+  om.options.menu                = mnu.flyout.utils
                                  ...
                                  = mnu.flyout.setup
                                        ...
                                        = fnc.configuration.upload
                                        ...
...

2.5.1 Compare Configurations

The Function of Compare Configurations needs an external Comparing Tool like WinMerge.
How this Tool will be called has to be set in the default.txt with the preference plm.omf.ConfigurationCompare.cmd.

# ----------------------------------------------------------------------------
# 2.1.1 Compare Configuration

# The Function of comparing configuration needs an external tool.
# This tool has to be set with the preference plm.omf.ConfigurationCompare.cmd.
# <desc1> and <desc2> Description of the configuration (for example, the SAP key of the configuration document)
# <path1> and <path2> The absolute path to the folders being compared (for example, C: \ path \ to \ configuration \)
# Example for WinMerge
# plm.omf.ConfigurationCompare.cmd = "C:\\Program Files (x86)\\WinMerge\\WinMergeU.exe" /r /e /x /u /dl "<desc1>" /dr "<desc2>" <path1> <path2>
# Example for BeyondCompare
# plm.omf.ConfigurationCompare.cmd = "C:\\Program Files (x86)\\Beyond Compare 4\\BCompare.exe" <path1> <path2>

2.6 SmartList: Configuration documents

The following macro can be used to create a SmartList with all configuration documents:

# SAP ECTR MACRO
# Created at  : 06.02.2017
# Created with: SAP ECTR 5.1.6.0
# Use Case    : Macro for Smartlist
#               Search for ECTR configuration documents
#               Output as result list (Smartlist)
 
# define Parameter Map
P_docSearch = PARAMETER_MAP( "doc_fields" )
P_docSearch.DOCUMENTTYPE = "AUX"
P_docSearch.DTYPE = "ECNFG"
 
# define SEARCH
SET_docSearch = SEARCH( "doc", P_docSearch )
 
# create KEYLIST from SET
KL_docSearch = KEYLIST_FROM_SET( SET_docSearch )
 
# output KEYLIST as RESULTLIST (Smartlist)
WRITE_RESULTLIST( KL_docSearch )

Export and import of configuration documents (since 5.2.6.0 / 1.1.6.0)

With the functions Export configuration document from SAP system and Import configuration document into SAP system, it is possible to transfer configuration documents from one SAP system to another.

Export

With the function fnc.configuration.export, a configuration document can be exported.  

After executing the function on the configuration document, a dialog opens. The export directory is shown.

After confirming the dialog, the configuration is stored to the predefined path.

Import

With the function fnc.configuration.import, a configuration document can be imported.  

After executing the function, a dialog opens, displaying all the configurations that can be imported. In order to import a configuration, it needs to be selected in the dialog and confirmed with clicking OK. Afterwards, the configuration document is imported to the SAP system.

3 Boundary conditions

As the configuration from the SAP system can only be used after the logon, not all "configuration files" or all files of the customize directory can benefit from this type of distribution.

• plm_initialize.bat
• saplogon.txt
• Basically all files that are required before logging on to the SAP system.

Add-Ons

Folders that exist in the installation under %PLM_INSTDIR%\addons must not be renamed afterwards. This can lead to a misbehavior in the backend configuration. 

Subdirectories "customize" and "templates" of addons will be distributed like all other configuration.

Post-installation of add-ons and integrations

If add-ons or integrations are installed into an existing SAP ECTR installation, it is mandatory to adjust and upload the BackendConfig directory as well. If this is not done, it can lead to a misbehavior in the backend configuration.

Support for CAD interfaces

Here you can find the CAD interfaces for ECTR which already support the backend-configuration.

• SAP ECTR Interface to PTC Creo Parametric, Patch 23 and newer
  Note: How to support the distribution of SAP ECTR configurations via SAP system

Icons

It is not possible to overwrite icons that are stored in ...\customize\basis\images.jar.

In order to use customer-specific or modified icons, the icons stored in  ...customize\classes\images.jar need to be named unambiguously and must not have the identical name as the icons that are stored in ...\basis\classes\images.jar.