Macros
Macros are name/value pairs that allows variability and change. The names used in the integration design artifacts are expanded to string values through configuration input parameters at runtime. This is a great way to provide dynamic, non-code modifications as input parameters.
Using symbolic, non-cryptic names help downstream users, who may have little insight to the design of any given integration, to understand their use. Macro names are case-sensitive and cannot contain spaces, but the values can represent any string of characters including spaces. They are referenced in an integration artifact using the $(MACRONAME) convention.
Common uses include, but are not limited to:
• Recurring modifications such as 90-day password updates. Make sure to use encrypted macro values to protect sensitive metadata such as passwords.
• Porting from one environment to another to accommodate the following:
• Server, database, and user name differences
• Life-cycle promotion Dev-Test-Production
• Path and file name changes
• Dynamically call different transformation maps within a process workflow.
• Debug switch to turn on specific steps or actions during test runs and turn off during production runs.
• Accessing system environment variable values by wrapping them with dollar sign parenthesis syntax: $(PATH)
Macros can be concatenated by referencing them in combination within the artifact:
$(MACRO_PATH)$(MACRO_FILENAME)
The following image shows a map with two macros that represent the path and file name, which is used to establish the connection to a file.
Tip... Use the Description text box in the Macro Definition to provide information to users without access to the design tools.
The path and file names are referenced in the integration artifacts and their values are passed to the engine through a runtime configuration artifact or as parameters according to the interface being used:
• Studio IDE Preferences: You can have more than one macro definition file but only one file is active at a time for any given workspace.
• Runtime Engine: Through the command line using:
• Macro value option:
"-D "<macro name>=<macro value>""
Macro definition file option:
"-mf <path to the macro definition file>"
• Add to the engine's cosmos.ini file:
[UserInfo]
macrofile=C:\directory\macrofilename.json
• Integration Manager: Macro names and values are stored and can be used at different levels depending on user access controls and permissions. The inheritance order is:
a. Global
b. User
c. Template
d. Configuration
Macros can also be defined dynamically using the scripting language. There are several functions that allows you to manage the macros in scripts and are commonly used with the file management functions when reading or writing temporary files.
Macros can be used for more elaborate purposes such as injecting dynamic values into conditional scripts. For example, if you want to change the value of an If-Then-Else condition through a macro value, use the following:
If MacroExpand("$(DEBUG)") == "true" Then
LogMessage("INFO", FileRead("$(PATH)$(FILE)"))
End If
Because they are often used for paths, you must know the operating system in which the integration will be run. If design and runtime is Windows, then you can use slashes as part of the macro value. In the example, "$(PATH)" is defined as "C:\directory\" and "$(FILE)" is defined as "filename.txt". Thus, "$(PATH)$(FILE)" expands to "C:\directory\filename.txt" and include the slashes.
Note: Macros can be dynamically created, defined, and accessed using the EZscript language. However, these macros are not exposed through the runtime configuration file and must be managed completely within the scripts where they are used.
For detailed information on using macros, see Managing Macro Sets and Macros.
Last modified date: 10/22/2024