Customizing MFT resource monitor 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, you 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.
The variables that are used for substitution are only available for positive trigger conditions. Only match and fileSize trigger conditions cause variables to be substituted. If a noMatch condition is used, and there are substitution variable names in the task definition, the task is not called, and the monitor raises a return code of 110 and error message BFGDM0060E.
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 MQ message properties read by MFT from messages on source queues and Monitoring a queue and using variable substitution.
outputN.log
):BFGDM0113W: Trigger failure for <monitor name> for reason BFGDM0060E: A monitor task could
not complete as a variable substitution <variable name> was not present.If moderate or verbose resource monitor logging is enabled for the monitor, the monitor writes the following message to the resource monitor event log of the agent (resmoneventN.log):BFGDM0060E: A monitor task could not complete as a variable substitution
<variable name> was not present.
See Logging MFT resource monitors for more information on resource monitor logging.
${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 directory
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. |
If the monitored resource is a trigger file
Variable | Description |
---|---|
contentSource | The complete path name of the source file. |
contentDestination | The complete path name of the destination file. |
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.
- 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 (/) on UNIX platforms or backward slash character(\) on Windows platforms, 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.
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
.