Skip to main content

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​

MacroDescriptionVariable valueUsage
filenameReplaced with the name of the file if available, if not then defaults to empty string. Does not include the extension.myfilename.txthttp://www.myapi.com/{filename}
becomes http://www.myapi.com/myfilename
guidReplaced with totally random GUID4ec6cc49-6d66-4a2a-b0ac-c5ab942cbdabhttp://www.myapi.com/{guid}
becomes http://www.myapi.com/4ec6cc49-6d66-4a2a-b0ac-c5ab942cbdab
interchangeReplaced with the interchange id that is either generated as a guid when the message hits Connxio or specified by the customer on entrymyid-1http://www.myapi.com/{interchange}
becomes http://www.myapi.com/myid-1
fileSearches 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 aboveJSON: 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
metadataAccesses 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 herehttp://www.myapi.com/{metadata:InboundFileName}
becomes http://www.myapi.com/filename
statuseventAccesses 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 herehttp://www.myapi.com/error?code={statusevent:error.errorcode}
becomes http://www.myapi.com/error?code=551
datacollectionAccess 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
userdefinedpropertiesAccess 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
dateReplaced 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.2408329Zhttp://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.

PipeDescriptionUsage
dateFormats the value output from the macro statement as a date. The date pipe accepts standard and custom date and time formats stringsMacro output value: 2022-06-11T12:15:55.9695313
pipe | date: dd.MM.yyyy HH.mm.ss
becomes 11.06.2022 12.15.55
stringFormats sting values. Supported methods are:
toLower
toUpper		Macro output value: My Output String
pipe | string: toUpper
becomes MY OUTPUT STRING
arrayArray opperations. Supported methods are:
contains
notContains		 file:myArray | array: contains(5) becomes true or false

Error handling with pipes​

These pipes can be used to handle errors that could occur during macro execution. Only the first valid error handling pipe is executed during an error. All other pipes gets skipped if an error handling pipe gets triggered.

PipeDescriptionUsage
errorA generic error handling pipe that handles all errors during macro execution. This pipe is only triggered if an error occured. | 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.
nullOnly handles errors specifically related to null references. Other errors will not trigger this pipe. | null: ignore: Ignores the macro statement and leaves it untouched.
| null: remove: Removes the failing macro statement.
| null: terminate: Terminates the integration process.
| null: fallback My value will yield the result My value if the macro statement results in a null error.

Pipe chaining​

The following example uses three pipes. These pipes are executed in order, depending on the result of the macro.

{file:myVariable | null: fallback myDefaultValue | error: terminate | string: toUpper}

  • If myVariable resolved to null, then the null pipe would trigger. The final result would become myDefaultvalue.

  • If there was an error reading the file, then the null pipe would not trigger. The next pipe here is the error pipe, which would then trigger and cause that specifig message in the integration to stop.

  • If no error occured, then the value in myVariable would be retrieved. The last pipe would then trigger and execute the string: toUpper method on the macro result.

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.

img

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.

img

Logging​

You can use CxMaL to change the log events to use custom values. The following fields support CxMaL:

  • The webhook URL
  • Transaction Tag

img

Outbound adapters​

Azure Storage​

Blob and azure file outbound adapters support CxMaL on the outbound blob and file name:

img

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:

img