Connxio Macro Language
Connxio Macro Language (CxMaL) is a domain-specific language designed for accessing and manipulating data within integrations running on the Connxio platform.
At various stages through Connxio you can use CxMaL to access metadata and message content to enrich everything from URL's to file names and logging options.
Quick reference
Macro | Description | Variable value | Usage |
---|---|---|---|
filename | Replaced with the name of the file if available, if not then defaults to empty string. Does not include the extension. | myfilename.txt | http://www.myapi.com/{filename} becomes http://www.myapi.com/myfilename |
guid | Replaced with totally random GUID | 4ec6cc49-6d66-4a2a-b0ac-c5ab942cbdab | http://www.myapi.com/{guid} becomes http://www.myapi.com/4ec6cc49-6d66-4a2a-b0ac-c5ab942cbdab |
interchange | Replaced with the interchange id that is either generated as a guid when the message hits Connxio or specified by the customer on entry | myid-1 | http://www.myapi.com/{interchange} becomes http://www.myapi.com/myid-1 |
file | Searches the file for the hierarchy specified after the "file:" keyword e.g. {file:rootNode.secondsNode.thirdNode} . This works for JSON and XML. In json you can also specify arrays using the bracket syntax like this; {file:rootNode.array[0].node} | See example json and xml above | JSON: http://www.myapi.com/{file:node1.array[1].element2} becomes http://www.myapi.com/Value2 XML: http://www.myapi.com/{file:note.heading} becomes http://www.myapi.com/integration |
metadata | Accesses metadata, which is essentially a JSON object which can be accessed in the same way as JSON files as described above e.g. {metadata:rootNode.secondNode.thirdNode} . | See Metadata structure here | http://www.myapi.com/{metadata:InboundFileName} becomes http://www.myapi.com/filename |
statusevent | Accesses statusevent, which is essentially a JSON object which can be accessed in the same way as JSON files as described above e.g. {statusevent:rootNode.secondNode.thirdNode} . | See Statusevent structure here | http://www.myapi.com/error?code={statusevent:error.errorcode} becomes http://www.myapi.com/error?code=551 |
datacollection | Access the data collection key/value set. This set is populated by the datacollection transformation. Use the key set in the configured data collection to select the corresponding value. If the value is JSON parsable you can add the "#json" suffix to target JSON nodes. | Key is "mykey" and value is the example JSON file above. | http://www.myapi.com/{datacollection#json:mykey.node1.array[1].element1} becomes http://www.myapi.com/value1 |
userdefinedproperties | Access the user-defined properties key/value set. This set is populated from within code mapping. Use the key set from within the code mapping to select the corresponding value. If the value is JSON parsable you can add the "#json" suffix to target JSON nodes. | Key is "mykey" and value is the example JSON file above. | http://www.myapi.com/{userdefinedproperties#json:mykey.node1.array[1].element1} becomes http://www.myapi.com/value1 |
date | Replaced with the current UTC datetime. This macro also support several methods: SetCstZone(string cstZone) AddSeconds(int secondsToAdd) AddMinutes(int minutesToAdd) AddHours(int houresToAdd) AddDays(int daysToAdd) AddMonths(monthsToAdd) AddYears(int yearsToAdd). Tips: Use the date pipe in order to format the output date. | 2022-06-10T08:24:35.2408329Z | http://www.myapi.com/getbydate?date={date.SetCstZone(Central Europe Standard Time).AddDays(1)} becomes http://www.myapi.com/getbydate?date=2022-06-11T10:33:19.6029842 |
Pipes
The pipes are used to perform some kind of action based on the output of the macro statement, like formatting or error handling. To use a pipe operator, add an '|' after the macro statement followed by the desired pipe action.
Pipe | Description | Usage |
---|---|---|
date | Formats the value output from the macro statement as a date. The date pipe accepts standard and custom date and time formats strings | Macro output value: 2022-06-11T12:15:55.9695313 pipe | date: dd.MM.yyyy HH.mm.ss becomes 11.06.2022 12.15.55 |
string | Formats sting values. Supported operator are: toLower toUpper | Macro output value: My Output String pipe | string: toUpper becomes MY OUTPUT STRING |
array | Array opperations. Supported methods are: contains notContains | file:myArray | array: contains(5) becomes true or false |
error | Used as a kind of error handling when using CxMaL. If a macro statement would fail for some reason the CxMaL default behaviour is to leave the statement untouched in the output. By using the error pipe you are enabled to control the outcome of a replacement failure. | | error: ignore : Ignores the macro statement and leaves it untouched. | error: remove : Removes the failing macro statement. | error: terminate : Terminates the integration process. | error: fallback My value will yield the result My value if the macro statement fails. |
Use cases
CxMaL can be used in various ways to simulate orchestration or to dynamically change endpoints or addresses. Following is a list of where CxMaL can be used:
Inbound adapters
REST Fetch
You can use CxMaL on the inbound REST adapter URL field like shown below.
However, since most of the macros don't make sense so early in the pipeline, only metadata actually works. An example can be seen above.
Data collection
Data collection supports all forms of CxMaL. Below you can see a pretty complex example that calculates the route based on the file and the InterchangeId.
Logging
You can use CxMaL to change the log events to use custom values. The following fields support CxMaL:
- The webhook URL
- Transaction Tag
Outbound adapters
Azure Storage
Blob and azure file outbound adapters support CxMaL on the outbound blob and file name:
REST Push
This functions the same way as the outbound REST adapter, but on outbound you have access to all file and data-collection variables as well.
SFTP Push
CxMaL can be used on the output file name like this: