Customizing MFT tasks with variable substitution
When the trigger conditions of an active resource monitor are satisfied, the defined task is called. In addition to calling the transfer or command task with the same destination agent or the same destination file name every time, we can also modify the task definition at run time. You do this by inserting variable names into the task definition XML. When the monitor determines that the trigger conditions are satisfied, and that the task definition contains variable names, it substitutes the variable names with the variable values, and then calls the task.
If the monitored resource is a queue
The value of any IBM MQ message property in the first message to be read from the monitored queue can be substituted in the task XML definition.
User-defined message properties are prefixed with usr. but do not include this prefix in the variable name. Variable names must be preceded by a dollar sign ($) character and enclosed in braces {}. For example, ${destFileName} is replaced with the value of the usr.destFileName message property of the first message to be read from the source queue. For more information, see IBM MQ message properties read by MFT from messages on source queues and Monitor a queue and using variable substitution.
The following table shows which substitution variables are provided by default. For example, ${AGENTNAME} is replaced with the name of the resource monitor agent.| Variable | Description |
|---|---|
| AGENTNAME | The name of the resource monitor agent. |
| QUEUENAME | The name of the queue that is being monitored. |
| ENCODING | The character encoding of the first message on the queue or the first message in a group. |
| MESSAGEID | The IBM MQ message ID of the first message on the queue or the first message in the group. |
| GROUPID | The IBM MQ group ID of the group or the message ID if only a single message is found. This variable is only set if you are monitoring for complete groups. |
| CurrentTimeStamp | A time stamp based on the local time that the monitor triggered at. The time stamp value is unique for the agent. |
| CurrentTimeStampUTC | A time stamp based on the time, in the UTC time zone, that the monitor triggered at. The time stamp value is unique for the agent. |
If the monitored resource is a file
The following table shows the set of variable names that can be substituted in the task XML definition.| Variable | Description |
|---|---|
| FilePath | The complete path name of the trigger file. |
| FileName | The file name part of the trigger. |
| LastModifiedTime | The time that the trigger file was last modified. This time is expressed as the local time of the time zone that the agent is running in and is formatted as an ISO 8601 time. |
| LastModifiedDate | The date that the trigger file was last modified. This date is expressed as the local date of the time zone that the agent is running in and is formatted as an ISO 8601 date. |
| LastModifiedTimeUTC | The time that the trigger file was last modified. This time is expressed as the local time converted to the UTC time zone and is formatted as an ISO 8601 time |
| LastModifiedDateUTC | The date that the trigger file was last modified. This date is expressed as the local date converted to the UTC time zone and is formatted as an ISO 8601 date. |
| AgentName | The name of the resource monitor agent. |
| CurrentTimeStamp | A time stamp that is based on the local time that the monitor triggered at. The time stamp value is unique for the agent. |
| CurrentTimeStampUTC | A time stamp that is based on the time in the UTC time zone that the monitor triggered at. The time stamp value is unique for the agent. |
Variable names must be preceded by a dollar sign ($) character and enclosed in braces, {}. For example, ${FilePath} is replaced with the fully qualified file path of the matching trigger file.
There are two special keywords that can be applied to variable names to provide further refinement. These are:
- token
- The token index to substitute (starting at 1 from the left and starting at -1 from the right)
- separator
- A single character to tokenize the variable value. The default is the forward slash character (/), but the separator can be any valid character that can appear in the variable value.
If the separator keyword is specified in a variable name, the variable value is split into tokens according to the separator character.
The value that is assigned to the token keyword is used as an index to select which token to use to replace the variable name. The token index is relative to the first character in the variable, and starts at 1. If the token keyword is not specified, the entire variable is inserted.
Variable names are not case-sensitive.
Any values that are substituted into an agent name in the message XML are treated in a not case-sensitive way. All Managed File Transfer Agent names are uppercase. If the value Paris is substituted into an agent attribute in the message XML, this value is interpreted as a reference to the agent PARIS.