MFT monitor list message format

The XML messages that are published as retained publications to the topic string SYSTEM.FTE/monitors/agent_name/monitor_name conform to the MonitorList.xsd schema. Each XML message lists an active monitor belonging to that agent. This information is used by the fteListMonitors command and the IBM MQ Explorer plug-in to display a list of monitors to the user. The MonitorList.xsd schema document is located in the MQ_INSTALLATION_PATH/mqft/samples/schema directory. The MonitorList.xsd schema imports Monitor.xsd, which is in the same directory.

Schema

The following schema describes which elements are valid in a monitor list 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="Monitor.xsd"/>

    <xsd:element name="monitorList">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="status"        type="monitorStatusType"          minOccurs="1" maxOccurs="1"/>
                <xsd:element name="configuration" type="monitorConfigurationType"   minOccurs="1" maxOccurs="1"/>
                <xsd:element name="pollInterval"  type="pollIntervalType"           minOccurs="1" maxOccurs="1"/>
                <xsd:element name="batch"         type="batchType"                  minOccurs="1" maxOccurs="1"/>
                <xsd:any minOccurs="0"/>
            </xsd:sequence>
            <xsd:attribute name="version" type="versionType" use="required"/>
            <xsd:attribute name="agent"   type="xsd:string"  use="required"/>
            <xsd:attribute name="monitor" type="xsd:string"  use="required"/>
        </xsd:complexType>
    </xsd:element>

    <xsd:complexType name="monitorStatusType">
        <xsd:sequence>
            <xsd:any minOccurs="0"/>
        </xsd:sequence>
        <xsd:attribute name="state"       type="xsd:token"/>
        <xsd:anyAttribute/>
    </xsd:complexType>

    <xsd:complexType name="monitorConfigurationType">
        <xsd:sequence>
            <xsd:element name="description"  type="xsd:string"           minOccurs="1" maxOccurs="1" />
            <xsd:element name="resources"    type="monitorResourcesType" minOccurs="0" maxOccurs="1" />
            <xsd:element name="triggerMatch" type="triggerMatchType"     minOccurs="0" maxOccurs="1" />
            <xsd:element name="tasks"        type="monitorListTasksType" minOccurs="0" maxOccurs="1" />
        </xsd:sequence>
        <xsd:anyAttribute/>
    </xsd:complexType>

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

    <xsd:complexType name="monitorListTaskType">
        <xsd:sequence>
            <xsd:element name="name"        type="monitorTaskNameType" 	minOccurs="0" maxOccurs="1" />
            <xsd:element name="description" type="xsd:string"          minOccurs="0" maxOccurs="1" />
            <xsd:element name="taskXML"     type="xsd:string"          minOccurs="0" maxOccurs="1" />
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

Understanding the monitor list message

The elements and attributes used in the monitor list messages are described in the following list:

<monitorList>

Group element containing the elements describe a monitor that is defined for the agent.

Attribute	Description
agent	Required. The name of the agent that the resource monitor is defined on.
monitor	Required. The name of the monitor. Unique for this agent.
version	Required. The version of the monitor list message format.

<status>

The status of the monitor.

Attribute	Description
state	The state of the monitor.

<configuration>

Group element containing the elements describe the configuration of the monitor.

<description>

A description of the monitor. (Not currently used.)

<resources>

The resource or resources being monitored.

<directory>

A directory to monitor.

Attribute	Description
recursionLevel	The number of directory levels down from the top level to monitor.
id	The ID of the resource.

<queue>

A queue to monitor.

Attribute	Description
id	The ID of the resource.

<triggerMatch>

Element that contains the <conditions> element.

<conditions>

Element that contains the condition or conditions that the resource monitor is monitoring for. This element can contain only one of the following elements: <allOf>, <anyOf>, or <condition>.

<allOf>

Element that contains the condition or conditions that the resource monitor is monitoring for. This element can contain one or many <condition> elements. For the resource monitor to be triggered all of the conditions inside of this element must be met.

<anyOf>

Element that contains the condition or conditions that the resource monitor is monitoring for. This element can contain one or many <condition> elements. For the resource monitor to be triggered only one of the conditions inside of this element must be met.

<condition>

Element that contains a single condition that the resource monitor is monitoring for. This element can contain only one of the following elements: <fileMatch>, <fileNoMatch>, <fileSize>, <queueNotEmpty>, <completeGroups>, or <fileSizeSame>. It can also contain a <name> element and a <resource> element.

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

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

<name>

Name of the condition.

<resource>

Identifies the resource definition to compare the condition against.

Attribute	Description
id	Unique identifier for the resource.

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

<taskXML>

The XML message that describes the task that the monitor is to perform. The contents of this element are in an escaped XML format.

<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

<batch>

The maximum number of trigger matches to include in a single batch.

Attribute	Description
maxSize	The maximum number of trigger matches to include in a single batch

The following XML shows an example of a retained publication which is published to the topic string SYSTEM.FTE/monitors/agent_name/MONITORTWO when the monitor called MONITORTWO is created on AGENT_JUPITER. The escaped XML within the <taskXML> element describes the task that is submitted when the monitor condition is met.

<?xml version="1.0" encoding="UTF-8"?>
<lst:monitorList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xmlns:lst="http://www.ibm.com/xmlns/wmqfte/7.0.1/MonitorDefinition" 
                 xsi:schemaLocation="http://www.ibm.com/xmlns/wmqfte/7.0.1/MonitorDefinition MonitorList.xsd"
                 version="4.00" 
                 agent="AGENT_JUPITER" 
                 monitor="MONITORTWO">   
    <status state="started"/>   
    <configuration>
        <description/>
        <resources>
            <directory recursionLevel="0" id="">/srv/nfs/incoming</directory>
        </resources>
        <triggerMatch>
            <conditions>
                <condition>
                    <name/>
                    <resource id=""/>
                    <fileMatch>
                        <pattern>*.completed</pattern>
                    </fileMatch>
                </condition>
            </conditions>
        </triggerMatch>
        <tasks>
            <task>
                <name/>
                <description/>         
                <taskXML>&lt;?xml version="1.0" encoding="UTF-8"?&gt;&lt;request 
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.00" 
                         xsi:noNamespaceSchemaLocation="FileTransfer.xsd"&gt;&lt;managedTransfer&gt;
                         &lt;originator&gt;&lt;hostName&gt;example.com.&lt;/hostName&gt;
                         &lt;userID&gt;mqm&lt;/userID&gt;&lt;/originator&gt;
                         &lt;sourceAgent QMgr="QM_JUPITER" agent="AGENT_JUPITER"/&gt;
                         &lt;destinationAgent QMgr="QM_JUPITER" agent="AGENT_SATURN"/&gt;
                         &lt;transferSet&gt;&lt;item checksumMethod="MD5" mode="binary"&gt;
                         &lt;source disposition="leave" recursive="false"&gt;&lt;file
                         &gt;/srv/nfs/incoming/*.txt&lt;/file&gt;&lt;/source&gt;
                         &lt;destination exist="error" type="directory"&gt;
                         &lt;file&gt;/srv/backup&lt;/file&gt;&lt;/destination&gt;
                         &lt;/item&gt;&lt;/transferSet&gt;&lt;/managedTransfer&gt;
                         &lt;/request&gt;
                </taskXML>
            </task>
        </tasks>
    </configuration>
    <pollInterval units="minutes">1</pollInterval>
    <batch maxSize="1"/>
</lst:monitorList>