Customizing 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 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 WebSphere® 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 WebSphere MQ message properties read from messages on source queues and Monitoring a queue and using variable substitution.

The following substitution variables are provided by default:
Variable Description
AGENTNAME The name of the resource monitor agent.
QUEUENAME The name of the queue being monitored.
ENCODING The character encoding of the first message on the queue or the first message in a group.
MESSAGEID The WebSphere MQ message ID of the first message on the queue or the first message in the group.
GROUPID The WebSphere 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.
For example, ${AGENTNAME} is replaced with the name of the resource monitor agent.

If the monitored resource is a file

The set of variable names that can be substituted in the task XML definition is as follows:

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 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 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 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 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.

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 - token index to substitute (starting at 1 from the left and starting at -1 from the right)
  • separator - 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 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.

Backslash characters in file paths are replaced with forward slashes in the message XML regardless of operating system.

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 WebSphere MQ File Transfer Edition 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.

The following example explains the various behaviors:

Assuming the file path to the matching trigger file is c:/MONITOR/REPORTS/Paris/Report2009.doc, the variables are substituted as follows:
Variable specification After variable substitution
${FilePath} c:/MONITOR/REPORTS/Paris/Report2009.doc
${FilePath{token=1}{separator=.}} c:/MONITOR/REPORTS/Paris/Report2009
${FilePath{token=2}{separator=.}} doc
${FilePath{token=3}} REPORTS
You can also specify a negative token index to select tokens relative to the last character of the variable. For example, by using the same variable value:
Variable specification After variable substitution
${FilePath} c:/MONITOR/REPORTS/Paris/Report2009.doc
${FilePath{token=-2}{separator=.}} c:/MONITOR/REPORTS/Paris/Report2009
${FilePath{token=-2}{separator=/}} Paris
${FilePath{token=-4}} MONITOR

The variables 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 103 and error message BFGDM0060E.

Example

The following example task definition XML uses the monitor agent name as the source agent for the transfer, uses the penultimate directory name in the file path as the destination agent name for the transfer, and renames the transferred file to be the root of the trigger file name with an extension of .rpt.
<?xml version="1.0" encoding="UTF-8" ?>
<request version="4.00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
   <managedTransfer>
     <originator>
       <hostName>reportserver.com</hostName>
       <userID>USER1</userID>
     </originator>
     <sourceAgent agent="${AgentName}" QMgr="QM1" />
     <destinationAgent agent="${FilePath{token=-2}}" QMgr="QMD" />
     <transferSet>
       <item mode="binary" checksumMethod="MD5">
         <source recursive="false" disposition="leave">
           <file>c:/incoming/reports/summary/report.doc</file>
         </source>
         <destination type="file" exist="overwrite">
           <file>/reports/${FileName{token=1}{separator=.}}.rpt</file>
         </destination>
       </item>
     </transferSet>
   </managedTransfer>
</request>
This results in the task XML being transformed to:
<?xml version="1.0" encoding="UTF-8" ?>
<request version="4.00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
   <managedTransfer>
     <originator>
       <hostName>reportserver.com</hostName>
       <userID>USER1</userID>
     </originator>
     <sourceAgent agent="AGENT1" QMgr="QM1" />
     <destinationAgent agent="Paris" QMgr="QMD" />
     <transferSet>
       <item mode="binary" checksumMethod="MD5">
         <source recursive="false" disposition="leave">
           <file>c:/incoming/reports/summary/report.doc</file>
         </source>
         <destination type="file" exist="overwrite">
           <file>/reports/Report2009.rpt</file>
         </destination>
       </item>
     </transferSet>
   </managedTransfer>
</request>
The variable ${FilePath{token=-2}} in the <destinationAgent> element's agent attribute is replaced with the value Paris. This value is treated in a not case-sensitive way and interpreted as a reference to the agent PARIS.

Information Information

Feedback

Timestamp icon Last updated: Tuesday, 30 January 2018
http://www.ibm.com/support/knowledgecenter/SSEP7X_7.0.4/com.ibm.wmqfte.doc/variable_substitution.htm