Skip to main content

Variable Replacement

At various stages through ConnXio (CX) you can use the variable replacement functionality to access metadata and message content to enrich everything from URL's to file names and logging options. This page details where and how to use variable replacement.

Query language​

Variable replacement uses a simple query language to function. The following table contains all available keywords (more may be added later):

Example JSON file:

{ 
    "node1": 
    { 
        "array": 
        [ 
            {"element1": "Value1"},
            {"element2": "Value2"}
        ],
        "parentElement": "ParentValue"
    } 
}

Example XML file:

<note>
    <to>You</to>
    <from>Me</from>
    <heading>Integration</heading>
    <body>Use ConnXio!</body>
</note>

Metadata is explained here but for reference we have copied the structure here:

public class MetaData
{
    public string InterchangeId { get; set; }
    public string InboundFileName { get; set; } = "filename";
    public string OutboundFileName { get; set; }
    public DateTime Started { get; set; }
    public Dictionary<string, string> DataCollection { get; set; }
    public Dictionary<string, string> UserDefinedProperties { get; set; }
    public string ConfigCorrelationId { get; set; }
    public string TransformationBlobName { get; set; }
    public string OutboundBlobName { get; set; }
    public string InboundAdapter { get; set; }
    public string InboundEndpoint { get; set; }
    public string OutboundAdapter { get; set; }
    public string OutboundEndpoint { get; set; }
    public string TransactionType { get; set; }
    public int ManualResendCount { get; set; }
}

Quick reference​

KeywordDescriptionVariable 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 CX 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 abovehttp://www.myapi.com/{metadata:InboundFileName}
becomes http://www.myapi.com/filename
datacollection, datacollection#jsonAccess 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, userdefinedproperties#jsonAccess 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.

KeywordDescriptionUsage
dateFormats the value output from the macro statement as a date. The date pipe accepts all 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 operator are:
toLower
toUpper		Macro output value: My Output String
pipe | string: toUpper
becomes MY OUTPUT STRING
errorUsed as a kind of error handling when using variable replacement. If a macro statement would fail for some reason the variable replacement default behaver 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: fallbackTo fallback to a deafult value when a macro fails, use fallback as a secondary keyword in combination with the error keyword.| error: fallback My default value will yield the result My default value if the macro statement fails.

Use cases​

Variable replacement can be used in various ways to simulate orchestration or to dynamically change endpoints or addresses. Following is a list of where variable replacement can be used:

Inbound adapters​

REST Fetch​

You can use variable replacement on the inbound REST adapter URL field like shown below.

img

However, since most of the variables 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 variable replacement. Below you can see a pretty complex example that calculates the route based on the file and the InterchangeId.

img

Logging​

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

  • The webhook URL
  • Transaction Tag

img

Outbound adapters​

Azure Storage​

Blob and azure file outbound adapters support variable replacement 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​

Variable replacement can be used on the output file name like this:

img