MFT monitor request message formats

Resource monitors are created when a suitable XML message arrives at an agent's command queue, typically as a result of a user issuing the fteCreateMonitor command or using the IBM MQ Explorer interface.

The monitor XML must conform to the Monitor.xsd schema using the <monitor> element as the root element.

Monitor messages can have one of the following root elements:

<monitor> - for creating and starting a new resource monitor
<deleteMonitor> - for stopping and deleting an existing monitor

There is no command message for the fteListMonitors command because the command directly retrieves matching monitor definitions from the SYSTEM.FTE topic.

Schema

The following schema describes which elements are valid in a monitor request XML message.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            targetNamespace="http://www.ibm.com/xmlns/wmqfte/7.0.1/MonitorDefinition" 			
            xmlns="http://www.ibm.com/xmlns/wmqfte/7.0.1/MonitorDefinition">  	

<xsd:include schemaLocation="FileTransfer.xsd" /> 

    <xsd:element name="monitor"> 		
        <xsd:complexType> 			
            <xsd:sequence> 				
                <xsd:element name="name"             type="monitorNameType"	
                             minOccurs="1"           maxOccurs="1" /> 				
                <xsd:element name="description"      type="xsd:string" 
                             minOccurs="0"           maxOccurs="1" /> 				
                <xsd:element name="pollInterval"     type="pollIntervalType" 
                             minOccurs="1"           maxOccurs="1" default="10" /> 				
                <xsd:element name="batch"            type="batchType" 
                             minOccurs="0"           maxOccurs="1" /> 				
                <xsd:element name="agent"            type="agentNameType"
                             minOccurs="1"           maxOccurs="1" /> 				
                <xsd:element name="resources"        type="monitorResourcesType" 
                             minOccurs="0"           maxOccurs="1" /> 				                
                <xsd:element name="triggerMatch"     type="triggerMatchType" 
                             maxOccurs="1"           minOccurs="1" /> 				
                <xsd:element name="reply"            type="replyType" 
                             maxOccurs="1"           minOccurs="0" /> 				
                <xsd:element name="tasks"            type="monitorTasksType" 
                             maxOccurs="1"           minOccurs="1" /> 	            
                <xsd:element name="originator"       type="origRequestType" 
                             maxOccurs="1"           minOccurs="1"/>
                <xsd:element name="job"              type="jobType" 
                             maxOccurs="1"           minOccurs="0"/>             	
                <xsd:element name="defaultVariables" type="defaultVariablesType" 
                             maxOccurs="1"           minOccurs="0"/> 			
            </xsd:sequence> 			
            <xsd:attribute name="version" type="versionType" use="required" /> 		
        </xsd:complexType> 	
    </xsd:element> 	 	

    <xsd:element name="deleteMonitor"> 		
        <xsd:complexType> 			
            <xsd:sequence> 				
                <xsd:element name="name"       type="monitorNameType" 
                             minOccurs="1"     maxOccurs="1" /> 	            
                <xsd:element name="originator" type="origRequestType" 
                             maxOccurs="1"     minOccurs="1"/> 				
                <xsd:element name="reply"      type="replyType"      
                             maxOccurs="1"     minOccurs="0" /> 			
            </xsd:sequence> 			
            <xsd:attribute name="version" type="versionType" use="required" /> 		
        </xsd:complexType> 	
    </xsd:element> 	 	

    <xsd:complexType name="transferRequestType"> 		
        <xsd:choice> 			
            <xsd:element name="managedTransfer" type="managedTransferType" /> 			
            <xsd:element name="managedCall"     type="managedCallType" /> 		
        </xsd:choice> 		
        <xsd:attribute name="version" type="versionType" /> 	
    </xsd:complexType> 	 	

    <xsd:complexType name="monitorResourcesType"> 		
        <xsd:choice> 		    
            <xsd:sequence> 			    
                <xsd:element name="directory" type="monitoredDirectoryType" 				    
                             minOccurs="1"    maxOccurs="unbounded" /> 		    
            </xsd:sequence> 		    
            <xsd:element name="queue" type="monitoredQueueType"/> 		
        </xsd:choice> 
    	</xsd:complexType> 	 	

    <xsd:complexType name="monitoredDirectoryType"> 		
        <xsd:simpleContent> 			
            <xsd:extension base="xsd:string"> 				
                <xsd:attribute name="recursionLevel" type="xsd:nonNegativeInteger" /> 				
                <xsd:attribute name="id" type="resourceIdAttrType" /> 			
            </xsd:extension> 		
        </xsd:simpleContent> 	
    </xsd:complexType>  	

    <xsd:complexType name="monitoredQueueType"> 		
        <xsd:simpleContent> 			
            <xsd:extension base="xsd:string"> 				
                <xsd:attribute name="id" type="resourceIdAttrType" /> 			
            </xsd:extension> 		
        </xsd:simpleContent> 	
    </xsd:complexType>  	

    <xsd:complexType name="triggerMatchType"> 		
        <xsd:sequence> 			
            <xsd:element name="conditions" type="conditionsType" 				
                         minOccurs="1"     maxOccurs="1" /> 		
        </xsd:sequence> 
    </xsd:complexType> 	  	 

    <xsd:complexType name="conditionsType"> 		
        <xsd:choice minOccurs="1"> 			
            <xsd:element name="allOf"     type="listPredicateType" 				
                         minOccurs="1"    maxOccurs="1" /> 			
            <xsd:element name="anyOf"     type="listPredicateType" 				
                         minOccurs="1"    maxOccurs="1" /> 			
            <xsd:element name="condition" type="conditionType" 				
                         minOccurs="1"    maxOccurs="1" /> 		
        </xsd:choice> 
    </xsd:complexType>

    <xsd:complexType name="listPredicateType">
        <xsd:choice>
            <xsd:element name="condition" type="conditionType" 				
                         minOccurs="1"    maxOccurs="unbounded" /> 		
        </xsd:choice> 
    </xsd:complexType> 	 	

    <xsd:complexType name="conditionType"> 		
        <xsd:sequence> 			
            <xsd:element name="name"     type="conditionNameType" 				
                         minOccurs="0"   maxOccurs="1" /> 			
            <xsd:element name="resource" type="resourceIdType" 				
                         minOccurs="0"   maxOccurs="1" /> 			
            <xsd:choice minOccurs="1"> 				
                <xsd:element name="fileMatch"       type="fileMatchConditionType" 					
                             minOccurs="1"          maxOccurs="1" /> 				
                <xsd:element name="fileNoMatch"     type="fileNoMatchConditionType" 					
                             minOccurs="1"          maxOccurs="1" />					 				
                <xsd:element name="fileSize"        type="fileSizeConditionType" 					
                             minOccurs="1"          maxOccurs="1" /> 				
                <xsd:element name="queueNotEmpty"   type="queueNotEmptyConditionType" 					
                             minOccurs="1"          maxOccurs="1" /> 				
                <xsd:element name="completeGroups"  type="completeGroupsConditionType" 					
                             minOccurs="1"          maxOccurs="1" /> 				
                <xsd:element name="fileSizeSame"    type="fileSizeSameType" 				
                             minOccurs="1"          maxOccurs="1"/> 			
            </xsd:choice> 		
        </xsd:sequence> 	
    </xsd:complexType> 

    <xsd:complexType name="fileMatchConditionType"> 		
        <xsd:sequence> 			
            <xsd:element name="pattern" type="conditionPatternType" 		    
                         minOccurs="0"  default="*.*" /> 			
            <xsd:element name="exclude" type="conditionPatternType" 
                         minOccurs="0"  maxOccurs="1"/> 		
        </xsd:sequence> 	
    </xsd:complexType> 	 		

    <xsd:complexType name="fileNoMatchConditionType"> 		
        <xsd:sequence> 			
            <xsd:element name="pattern" type="conditionPatternType" 				
                         minOccurs="0"  default="*.*" /> 			
            <xsd:element name="exclude" type="conditionPatternType" 
                         minOccurs="0"  maxOccurs="1"/>				 		
        </xsd:sequence> 	
    </xsd:complexType>		 
	 	
    <xsd:complexType name="fileSizeConditionType"> 		
        <xsd:sequence> 			
            <xsd:element name="compare" type="sizeCompareType" 				
                         minOccurs="1"  default="0" /> 			
            <xsd:element name="pattern" type="conditionPatternType" 				
                         minOccurs="0"  default="*.*" /> 			
            <xsd:element name="exclude" type="conditionPatternType" 
                         minOccurs="0"  maxOccurs="1"/> 		
        </xsd:sequence> 	
    </xsd:complexType> 	 	

    <xsd:complexType name="sizeCompareType"> 		
        <xsd:simpleContent> 			
            <xsd:extension base="xsd:int"> 				
                <xsd:attribute name="operator" type="sizeOperatorType"  use="required" /> 				
                <xsd:attribute name="units"    type="fileSizeUnitsType" use="required" /> 			
            </xsd:extension> 		
        </xsd:simpleContent> 	
    </xsd:complexType>            

    <xsd:simpleType name="sizeOperatorType"> 		
        <xsd:restriction base="xsd:string"> 			
            <xsd:enumeration value=">=" /> 		
        </xsd:restriction> 	
    </xsd:simpleType> 	 

    <xsd:simpleType name="fileSizeUnitsType"> 		
        <xsd:restriction base="xsd:string"> 			
            <xsd:pattern value="[bB]|[kK][bB]|[mM][bB]|[gG][bB]" /> 		
        </xsd:restriction> 	
    </xsd:simpleType> 	 	

    <xsd:complexType name="conditionPatternType"> 		
        <xsd:simpleContent> 			
            <xsd:extension base="xsd:string"> 				
                <xsd:attribute name="type"    type="patternTypeAttributeType" 
                               use="optional" default="wildcard"/> 			
            </xsd:extension> 		
        </xsd:simpleContent>		 	
    </xsd:complexType>  	 	

    <xsd:simpleType name="patternTypeAttributeType"> 		
        <xsd:restriction base="xsd:token"> 			
            <xsd:enumeration value="regex" /> 			
            <xsd:enumeration value="wildcard" /> 		
        </xsd:restriction> 	
    </xsd:simpleType> 	 	

    <xsd:complexType name="conditionNameType"> 		
        <xsd:simpleContent> 			
            <xsd:extension base="xsd:string" /> 		
        </xsd:simpleContent> 	
    </xsd:complexType>  	

    <xsd:complexType name="queueNotEmptyConditionType"/> 	 	
	
    <xsd:complexType name="completeGroupsConditionType"/> 	 	
    
    <xsd:complexType name="fileSizeSameType"> 		
        <xsd:sequence> 			
            <xsd:element name="pattern" type="conditionPatternType" 
                         minOccurs="1"  maxOccurs="1"/> 			
            <xsd:element name="exclude" type="conditionPatternType" 
                         minOccurs="0"  maxOccurs="1"/> 		
        </xsd:sequence> 		
        <xsd:attribute name="polls" type="positiveIntegerType" use="required" /> 
    </xsd:complexType> 	 

    <xsd:complexType name="pollIntervalType"> 		
        <xsd:simpleContent> 			
            <xsd:extension base="xsd:int"> 				
                <xsd:attribute name="units"    type="timeUnitsType" 
                               use="optional"  default="minutes" /> 			
             </xsd:extension> 		
        </xsd:simpleContent> 	
    </xsd:complexType> 	 	

    <xsd:complexType name="batchType"> 		
        <xsd:attribute name="maxSize" type="positiveIntegerType" use="required"/> 	
    </xsd:complexType> 	 	

    <xsd:simpleType name="timeUnitsType"> 		
        <xsd:restriction base="xsd:token"> 			
            <xsd:enumeration value="seconds" /> 			
            <xsd:enumeration value="minutes" /> 			
            <xsd:enumeration value="hours" /> 			
            <xsd:enumeration value="days" /> 			
            <xsd:enumeration value="weeks" /> 			
            <xsd:enumeration value="months" /> 			
            <xsd:enumeration value="years" /> 		
        </xsd:restriction> 	
    </xsd:simpleType> 	 	

    <xsd:complexType name="monitorTasksType"> 		
        <xsd:sequence> 			
            <xsd:element name="task"   type="monitorTaskType" 				
                         minOccurs="1" maxOccurs="1" /> 		
        </xsd:sequence> 	
    </xsd:complexType> 	 	

    <xsd:complexType name="monitorTaskType"> 		
        <xsd:sequence> 			
            <xsd:element name="name"        type="monitorTaskNameType" 				
                         minOccurs="1"      maxOccurs="1" /> 			
            <xsd:element name="description" type="xsd:string" 				
                         minOccurs="0"      maxOccurs="1" /> 			
            <xsd:element name="transfer"    type="transferTaskType" 				
                         minOccurs="0"      maxOccurs="1" /> 		
        </xsd:sequence> 	
    </xsd:complexType> 	 

    <xsd:complexType name="transferTaskType"> 		
        <xsd:sequence> 			
            <xsd:element name="request"  type="transferRequestType" 				
                         minOccurs="1"   maxOccurs="1" /> 		
        </xsd:sequence> 	
    </xsd:complexType>  

    <xsd:complexType name="resourceIdType"> 		
        <xsd:attribute name="id" type="xsd:string" use="optional" /> 	
    </xsd:complexType> 	

    <xsd:simpleType name="resourceIdAttrType"> 		
        <xsd:restriction base="xsd:string"></xsd:restriction> 	
    </xsd:simpleType>  	 	

    <xsd:simpleType name="monitorNameType"> 		
        <xsd:restriction base="xsd:string"> 			
            <xsd:pattern value="[^%\*]+" /> 		
        </xsd:restriction> 	
    </xsd:simpleType>      	 

    <xsd:simpleType name="agentNameType"> 		
        <xsd:restriction base="xsd:string"> 			
            <xsd:pattern value="[.%_0-9A-Z]*" /> 		
        </xsd:restriction> 	
    </xsd:simpleType>  	 	

    <xsd:simpleType name="monitorTaskNameType"> 		
        <xsd:restriction base="xsd:string"> 			
            <xsd:pattern value=".*" /> 		
        </xsd:restriction> 	
    </xsd:simpleType> 	 	

    <xsd:complexType name="defaultVariablesType">         
        <xsd:sequence>                 
            <xsd:element name="variable"       type="variableType" 
                         maxOccurs="unbounded" minOccurs="1" />         
        </xsd:sequence>     
    </xsd:complexType>          
    
    <xsd:complexType name="variableType">                 
        <xsd:simpleContent>                 
            <xsd:extension base="xsd:string">                         
                <xsd:attribute name="key" type="xsd:string" use="required" />                 
            </xsd:extension>         
        </xsd:simpleContent>     
    </xsd:complexType>

</xsd:schema>

Understanding the create monitor message

The elements and attributes used in create monitor messages are described:

Element descriptions

<monitor>

Group element containing all the elements required to cancel a file transfer in progress.

Attribute	Description
version	Specifies the version of this element as supplied by Managed File Transfer.

<name>

The name of the monitor, unique within the monitor's agent.

<description>

Description of the monitor (not currently used).

<pollInterval>

The time interval between each check of the resource against the trigger condition.

Attribute	Description
units	Specifies the time units for the poll interval. Valid values are: seconds minutes hours days weeks months years

Attribute

Description

units

Specifies the time units for the poll interval. Valid values are:

seconds
minutes
hours
days
weeks
months
years

<agent>

Name of the agent the monitor is associated with.

<resources>

Group element that contains the elements specifying the resources to monitor.

<directory>

Fully qualified path specifying the directory on the monitor's agent machine to monitor.

Attribute	Description
recursionLevel	The number of subdirectories to monitor in addition to the specified directory.
id	Unique identifier for the resource.

<queue>

Queue name specifying the queue to monitor on the monitoring agent's queue manager.

<triggerMatch>

Group element that contains the elements specifying the trigger conditions to compare with the monitored resource.

<conditions>

Group element that contains the elements specifying the type of condition to compare with the monitored resource.

<allOf>

Predicate that specifies that all contained conditions must be satisfied.

<anyOf>

Predicate that specifies that any contained conditions must be satisfied.

<condition>

Defines a comparison condition that will contribute to the overall monitor trigger condition.

<name>

Name of the condition.

<resource>

Identifies the resource definition to compare the condition against.

Attribute	Description
id	Unique identifier for the resource.

If the resource that is being monitored is a directory, one of the following three elements must be specified in the condition:

fileMatch
fileNoMatch
fileSize

If the resource that is being monitored is a queue, one of the following two elements must be specified in the condition:

queueNotEmpty
completeGroups

<fileMatch>

Group element for a file name match condition.

<pattern>

Specifies a file name match pattern. Files on the resource must match the pattern in order to satisfy the condition. The default pattern is * (any file will match).

<fileNoMatch>

Group element for an inverse file name match condition.

<pattern>

Specifies an inverse file name match pattern. If no files on the monitored resource match, the condition is satisfied. The default pattern is * (the absence of any file will match).

<fileSize>

Group element for a file size comparison.

<compare>

Specifies a file size comparison. The value must be a non-negative integer.

Attribute	Description
operator	Comparison operator to use. Only >=' is supported.
units	Specifies file size units, which can be one of: B - bytes KB - kilobytes MB - megabytes GB - gigabytes The units value is case insensitive, so mb' works as well as MB'.

Attribute

Description

operator

Comparison operator to use. Only >=' is supported.

units

Specifies file size units, which can be one of:

B - bytes
KB - kilobytes
MB - megabytes
GB - gigabytes

The units value is case insensitive, so mb' works as well as MB'.

<pattern>

File name pattern to match. Default is * (any file will match).

<queueNotEmpty>

This can only be specified if the resource is a queue. Specifies that there must be a message on the queue for the monitor to be triggered.

<completeGroups>

This can only be specified if the resource is a queue. Specifies that there must be a complete group of messages present on the queue for the monitor to be triggered. A single transfer task is executed for each complete group on the queue.

<reply>

Optional element that is used to specify reply queue for asynchronous requests.

Attribute	Description
QMGR	Queue manager name.

<tasks>

Group element to contain elements which specify the tasks to invoke when the monitor trigger conditions are satisfied.

<task>

Group element which defines an individual task that the monitor will invoke when the trigger conditions are satisfied. Currently only one task can be specified.

<name>

Name of the task. Accepts any alphanumeric characters.

<description>

Description of the task. Any text value is allowed.

<transfer>

Group element that defines a transfer task.

<request>

Group element that defines the type of task. This must contain one of the following elements which are inherited from the FileTransfer.xsd schema definition:

managedTransfer
managedCall

Attribute	Description
version	Version of the request as provided by Managed File Transfer. This is in the form n.mm where n is the major release version and mm is the minor version. For example 1.00.

<originator>

Group element that contains the elements specifying the originator of the request.

<hostName>

The host name of the system where the source file is located.

<userID>

The user ID that originated the file transfer.

<mqmdUserID>

Optional. The IBM MQ user ID that was supplied in the message descriptor (MQMD).

<job>

Group element containing job information.

<jobName>

Specifies logical job identifier.

<defaultVariables>

Group element containing one or more variable elements. These variables are used in variable substitution when monitoring a queue. For more information about variable substitution, see Customizing MFT tasks with variable substitution.

<variable>

Element containing the value associated with the key given by the key attribute.

Attribute	Description
key	The name of the default variable.

Understanding the delete monitor message

The elements and attributes used in delete monitor messages are described:

Element descriptions

<deleteMonitor>

Group element containing all the elements required to stop and delete a monitor.

Attribute	Description
version	Specifies the version of this element as supplied by Managed File Transfer.

<name>

Name of monitor to delete.

<originator>

Group element that contains the elements specifying the originator of the request.

<hostName>

The host name of the system where the source file is located.

<userID>

The user ID that originated the file transfer.

<mqmdUserID>

Optional. The IBM MQ user ID that was supplied in the message descriptor (MQMD).

<reply>

Specifies the name of the temporary reply queue generated for the request. The name of the queue is as defined by the key dynamicQueuePrefix in the command.properties configuration file. If this is not specified, the queue name has a default value of WMQFTE.

Attribute	Description
QMGR	The name of the command queue manager on which the temporary dynamic queue is generated to receive replies.

Examples

Examples of XML messages that conform to this schema are provided for each of the following monitor requests: