File transfer log message formats
File transfer log messages are published to the SYSTEM.FTE topic with a topic string of Log/agent_name/transfer_ID. These messages conform to the schema TransferLog.xsd, which is located in the MQ_INSTALLATION_PATH/mqft/samples/schema directory of your IBM® MQ Managed File Transfer installation.
If you want to monitor file transfers or
collect data about them, set up a subscription to a wildcard topic
tailored to the transfers you are interested in. For example:
Log/#
Log/FTEAGENT/#
Schema
The following schema describes which elements are valid in a transfer log XML message.
<xsd:schema xmlns:xsd="https://www.w3.org/2001/XMLSchema">
<xsd:include schemaLocation="fteutils.xsd"/>
<xsd:element name="transaction">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="action" type="actionType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="sourceAgent" type="agentExitStatusType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="sourceWebGateway" type="webGatewayType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="sourceWebUser" type="webUserType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="destinationAgent" type="agentExitStatusType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="destinationWebGateway" type="webGatewayType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="destinationWebUser" type="webUserType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="agent" type="agentExitStatusType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="originator" type="origRequestType"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="status" type="statusType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="trigger" type="triggerType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="transferSet" type="transferSetType"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="job" type="jobType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="scheduleLog" type="scheduleLogType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="statistics" type="statisticsType"
maxOccurs="1" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="version" type="versionType" use="required"/>
<xsd:attribute name="ID" type="IDType" use="required"/>
<xsd:attribute name="relatedID" type="IDType" use="optional"/>
<xsd:attribute name="agentRole" type="agentRoleType" use="optional"/>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="agentExitStatusType">
<xsd:complexContent>
<xsd:extension base="agentType">
<xsd:sequence>
<xsd:element name="startExits" type="exitGroupType" minOccurs="0" maxOccurs="1"/>
<xsd:element name="endExits" type="exitGroupType" minOccurs="0" maxOccurs="1"/>
<xsd:element name="systemInfo" type="systemInfoType" minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="transferSetType">
<xsd:sequence>
<xsd:element name="metaDataSet" type="metaDataSetType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="call" type="callGroupType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="preSourceCall" type="callGroupType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="postSourceCall" type="callGroupType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="preDestinationCall" type="callGroupType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="postDestinationCall" type="callGroupType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="item" type="itemType"
maxOccurs="unbounded" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="index" type="xsd:nonNegativeInteger" use="optional"/>
<xsd:attribute name="size" type="xsd:nonNegativeInteger" use="optional"/>
<xsd:attribute name="startTime" type="xsd:dateTime" use="required"/>
<xsd:attribute name="total" type="xsd:nonNegativeInteger" use="required"/>
<xsd:attribute name="bytesSent" type="xsd:nonNegativeInteger" use="required"/>
</xsd:complexType>
<xsd:complexType name="itemType">
<xsd:sequence>
<xsd:element name="source" type="fileSourceChecksumType"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="destination" type="fileDestinationChecksumType"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="status" type="statusType"
maxOccurs="1" minOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="mode" type="modeType" use="required"/>
</xsd:complexType>
<xsd:complexType name="fileSourceChecksumType">
<xsd:complexContent>
<xsd:extension base="fileSourceType">
<xsd:sequence>
<xsd:element name="checksum" type="checksumType" minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="fileDestinationChecksumType">
<xsd:complexContent>
<xsd:extension base="fileDestinationType">
<xsd:sequence>
<xsd:element name="checksum" type="checksumType"
minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="actionType">
<xsd:simpleContent>
<xsd:extension base="actionEnumType">
<xsd:attribute name="time" type="xsd:dateTime" use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:simpleType name="actionEnumType">
<xsd:restriction base="xsd:token">
<xsd:enumeration value="cancelled"/>
<xsd:enumeration value="started"/>
<xsd:enumeration value="progress"/>
<xsd:enumeration value="completed"/>
<xsd:enumeration value="malformed"/>
<xsd:enumeration value="notAuthorized"/>
<xsd:enumeration value="deleted"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="systemInfoType">
<xsd:attribute name="architecture" type="xsd:string" use="required"/>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="version" type="xsd:string" use="required"/>
</xsd:complexType>
<xsd:element name="malformed">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="action" type="actionType"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="agent" type="agentExitStatusType"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="status" type="statusType"
maxOccurs="1" minOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="version" type="versionType" use="required"/>
<xsd:attribute name="ID" type="IDType" use="required"/>
<xsd:attribute name="agentRole" type="agentRoleType" use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="notAuthorized">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="action" type="actionType"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="originator" type="origRequestType"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="authority" type="xsd:string"
minOccurs="1" maxOccurs="1"/>
<xsd:element name="status" type="statusType"
maxOccurs="1" minOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="version" type="versionType" use="required"/>
<xsd:attribute name="ID" type="IDType" use="required"/>
<xsd:attribute name="agentRole" type="agentRoleType" use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="statisticsType">
<xsd:sequence>
<xsd:element name="actualStartTime" type="xsd:dateTime"
maxOccurs="1" minOccurs="0"/>
<xsd:element name="retryCount" type="xsd:nonNegativeInteger"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="numFileFailures" type="xsd:nonNegativeInteger"
maxOccurs="1" minOccurs="1"/>
<xsd:element name="numFileWarnings" type="xsd:nonNegativeInteger"
maxOccurs="1" minOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="webGatewayType">
<xsd:attribute name="webGatewayName" type="xsd:string" use="optional"/>
<xsd:attribute name="webGatewayAgentName" type="xsd:string" use="optional"/>
<xsd:attribute name="webGatewayAgentQMgr" type="xsd:string" use="optional"/>
</xsd:complexType>
<xsd:complexType name="webUserType">
<xsd:attribute name="webGatewayName" type="xsd:string" use="required"/>
<xsd:attribute name="webGatewayAgentName" type="xsd:string" use="optional"/>
<xsd:attribute name="webGatewayAgentQMgr" type="xsd:string" use="optional"/>
</xsd:complexType>
</xsd:schema>
Understanding the transfer log message
- <transaction>
- Group element that specifies a group of transfers you want to
perform together.
Attribute Description version Specifies the version of this element as detailed by IBM MQ Managed File Transfer. ID Specifies the unique transaction ID. The ID can be a maximum of 48 alphanumeric characters. relatedID Optional. If the transaction is the delete or download of a file from a file space, relatedID specifies the transaction ID of the transfer that uploaded the file to the file space. agentRole Optional. Specifies whether the agent concerned is on the source or destination system xmlns:xsi Namespace declaration. Indicates that the elements and data types used in this schema derive from the "https://www.w3.org/2001/XMLSchema-instance" namespace. xsi:noNamespaceSchemaLocation Specifies the name and location of the XML schema document to validate this message against if there is no namespace declaration. The value you specify for this attribute must refer to a IBM MQ Managed File Transfer TransferLog.xsd document. - <action>
- Describes the status of the file transfer at the time logged by
the time attribute. The status can be one of the following values:
- started
- progress
- completed
- cancelled
- malformed (indicates the file transfer request message content can not be interpreted.)
- notAuthorized
- deleted
Attribute Description time The time that the transfer status was captured, expressed in UTC format. - <sourceAgent>
- Specifies the name of the agent on the system where the source
file is located. Only one of <sourceAgent>, <sourceWebUser>,
and <sourceWebGateway> can be specified.
- <startExits>
- Group element that contains one or more user exit elements. This element can occur once only.
- <endExits>
- Group element that contains one or more user exit elements. This element can occur once only.
- <systemInfo>
- Describes the system architecture, name, and version. This element can occur once only.
Attribute Description agent The name of the agent on the source system. QMgr The name of the queue manager on the source system. agentType The type of the agent. Valid values are: - STANDARD - a normal agent
- BRIDGE - a protocol bridge agent
- CD_BRIDGE - a Connect:Direct® bridge agent
- EMBEDDED - an embedded agent
- WEB_GATEWAY - a web agent
- SFG - a Sterling File Gateway embedded agent
bridgeURL Optional. If the agent is a protocol bridge agent, the host name of the system hosting the protocol server. pnode Optional. If the agent is a Connect:Direct bridge agent, the name of the Connect:Direct primary node involved in the transfer. snode Optional. If the agent is a Connect:Direct bridge agent, the name of the Connect:Direct secondary node involved in the transfer. bridgeNode Optional. If the agent is a Connect:Direct bridge agent, the name of the Connect:Direct node that is part of the Connect:Direct bridge. This is the same node as either the primary node or the secondary node. - <sourceWebUser>
- Specifies the name of the web user that uploads the source file
to the Web Gateway. Only one of <sourceAgent>, <sourceWebUser>,
and <sourceWebGateway> can be specified.
Attribute Description webGatewayName The name of the Web Gateway that receives the file from the web user. webGatewayAgentName The name of the web agent that the Web Gateway uses to send the file to the destination. webGatewayAgentQMgr The name of the queue manager of the web agent. - <sourceWebGateway>
- Specifies the name of the Web Gateway that the source file is
downloaded from. Only one of <sourceAgent>, <sourceWebUser>,
and <sourceWebGateway> can be specified.
Attribute Description webGatewayName The name of the Web Gateway that receives the file from the web user. webGatewayAgentName The name of the web agent that the Web Gateway uses to send the file to the destination. webGatewayAgentQMgr The name of the queue manager of the web agent. - <destinationAgent>
- Specifies the name of the agent on the system the
file was transferred to. Only one
of <destinationAgent>, <destinationWebGateway>, and <destinationWebUser>
can be specified.
Attribute Description agent The name of the agent on the destination system. QMgr The name of the queue manager on the destination system. agentType The type of the agent. Valid values are: - STANDARD - a normal agent
- BRIDGE - a protocol bridge agent
- CD_BRIDGE - a Connect:Direct bridge agent
- EMBEDDED - an embedded agent
- WEB_GATEWAY - a web agent
- SFG - a Sterling File Gateway embedded agent
bridgeURL Optional. If the agent is a protocol bridge agent, the host name of the system hosting the protocol server. pnode Optional. If the agent is a Connect:Direct bridge agent, the name of the Connect:Direct primary node involved in the transfer. snode Optional. If the agent is a Connect:Direct bridge agent, the name of the Connect:Direct secondary node involved in the transfer. bridgeNode Optional. If the agent is a Connect:Direct bridge agent, the name of the Connect:Direct node that is part of the Connect:Direct bridge. This is the same node as either the primary node or the secondary node. - <startExits>
- Group element that contains one or more user exit elements. This element can occur once only.
- <endExits>
- Group element that contains one or more user exit elements. This element can occur once only.
- <systemInfo>
- Describes the system architecture, name, and version. This element can occur once only.
- <destinationWebUser>
- Specifies the name of the web user who downloads the file from
the Web Gateway. Only one of <destinationAgent>, <destinationWebGateway>,
and <destinationWebUser> can be specified.
Attribute Description webGatewayName The name of the Web Gateway that receives the file from the web user. - <destinationWebGateway>
- Specifies the name of the web user who downloads the file from
the Web Gateway. Only one of <destinationAgent>, <destinationWebGateway>,
and <destinationWebUser> can be specified.
Attribute Description webGatewayName The name of the Web Gateway that receives the file from the web user. webGatewayAgentName The name of the web agent that the Web Gateway uses. webGatewayAgentQMgr The name of the queue manager of the web agent. - <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>
- The WebSphere® MQ user ID that was supplied in the message descriptor (MQMD)
- <webUserID>
- Optional. The user ID that was supplied to the web browser submitting the transfer request.
- <webBrowser>
- Optional. The web browser that the transfer request was submitted from.
- <status>
- The result code and supplement messages.
- <trigger>
- Group element that contains the trigger elements defined in the
original transfer request. These elements can be either or both of
the following:
- <fileExist>
- Trigger condition based on whether a file exists
- <fileSize>
- Trigger condition based on whether a file meets or exceeds the specified size
- <transferSet>
- Specifies a group of file transfers you want to perform together.
During transmission <transferSet> is a group element containing <item>
elements.
Attribute Description startTime Records the time that the set of transfers started, expressed in UTC format. total Specifies the total number of items in this set of transfers. index Optional attribute. Specifies the position of the first item in progress of the transfer set. The index attribute increments from zero. For example, if the index is set to 1, the progress message is the second of two items. size Optional attribute. Specifies the number of items in the progress report. priority Optional attribute. Priority level of the transfer. Priority is a value in the range 0-9, where 0 is the lowest priority. The default priority level is 0 and by default the transfer uses the source agent priority level. - <metaDataSet>
- Group element containing one or more of the following attributes:
- <metaData>
Attribute Description key The key half of a metadata key-value pair. The <metaData> element content contains the value half of the pair. For example <metaData key="testkey1">testvalue1</metaData>
- <job>
- Group element that contains an element specifying job details. <job> is a user-defined job name identifier
that is added to the log message when the transfer has started. This <job>
element is the same as the <job> element that is included in the
transfer request message, which is described in the following topic: File transfer request message format.
- <name>
- The value of name can be any string.
- <scheduleLog>
- Group element that contains elements specifying the source and
destination file names and locations.
Attribute Description ID Matches the schedule ID if the transfer is a scheduled transfer. - <item>
- Group element that contains elements specifying the source and destination file names and locations.
- <source>
- Group element that contains the <file> element or the <queue>
element, and the <checksum> element for the file on the source
system.
Attribute Description recursive Specifies that files are transferred recursively in subdirectories when the <source> element is a directory or contains wildcard characters. disposition Specifies the action that is taken on the <source> element when <source> has successfully been transferred to its destination. The valid options are as follows: - leave - the source files are left unchanged.
- delete - the source files are deleted from the source system after the source file is successfully transferred.
correlationBoolean A boolean correlation value. If the source is a Connect:Direct bridge, this specifies whether the Connect:Direct process is user-defined. correlationString1 A string correlation value. If the source is a Connect:Direct bridge, this specifies the name of the Connect:Direct process that occurs at the destination of the transfer. correlationNum1 A numeric correlation value. If the source is a Connect:Direct bridge, this specifies the ID number of the Connect:Direct process that occurs at the destination of the transfer. - <queue>
- When used with the <source> element, specifies the name of
the queue that the transferred messages were read from, which is located
on the source agent queue manager.
Attribute Description messageCount The number of messages that were read from the queue. groupId The WebSphere MQ group ID of the messages read from the queue. - <destination>
- Group element that contains the <file> element or the <queue>
element, and <checksum> element for the destination.
Only one of <file> and <queue> is present as a child element of destination.
Attribute Description type The type of destination. The valid options are as follows:- file - specifies a file as the destination
- directory - specifies a directory as the destination
- dataset - specifies a z/OS® data set as the destination
- pds - specifies a z/OS partitioned data set as the destination
- queue- specifies a WebSphere MQ queue as the destination
The value queue is valid only when the <destination> element has a child element of <queue>.
The other values are valid only when the <destination> element has a child element of <file>.
exist Specifies the action that is taken if a destination file exists on the destination system. The valid options are as follows:- error - reports an error and the file is not transferred.
- overwrite - overwrites the existing destination file.
This attribute cannot be present if the <destination> element has a child element of <queue>.
correlationBoolean A boolean correlation value. If the destination is a Connect:Direct bridge, this specifies whether the Connect:Direct process is user-defined. correlationString1 A string correlation value. If the destination is a Connect:Direct bridge, this specifies the name of the Connect:Direct process that occurs at the destination of the transfer. correlationNum1 A numeric correlation value. If the destination is a Connect:Direct bridge, this specifies the ID number of the Connect:Direct process that occurs at the destination of the transfer. - <file>
- Specifies the absolute path of the file that was transferred
(both at the source and destination). The fully-qualified path is
in the format consistent with your operating system, for example
C:/from/here.txt. File URIs are not used. - <queue>
- When used with the <destination> element, specifies the name
of the queue that was transferred to, which is located on any queue
manager that is connected to the destination agent queue manager.
Attribute Description messageCount The number of messages that were written to the queue. messageLength The length of the messages written to the queue. groupId If the transfer request specified that the file is split into multiple messages, the value of this attribute is the WebSphere MQ group ID of the messages written to the queue. messageId If the transfer request did not specify that the file is split into multiple messages, the value of this attribute is the WebSphere MQ message ID of the message written to the queue. - <checksum>
- Optional element.
Specifies the type of hash algorithm that generated the message digest to create the digital signature. Currently IBM MQ Managed File Transfer supports Message Digest algorithm 5 (MD5) only. The checksum provides a way for you to confirm the integrity of transferred files is intact.
- <malformed>
- Group element for malformed messages.
Attribute Description version ID agentRole Either source agent or destination agent - <statistics>
- Group element for statistical information for the transfer (when
available).
- <actualStartTime>
- The actual time that the agent started running the transfer. Typically, the time is the same as (or very close to) the start time recorded for the transfer. However, when an agent is busy submitted transfers might be queued until the agent has capacity to run the transfers.
- <retryCount>
- The number of times that the transfer went into the recovery state and was retried by the agent. A transfer can go into a recovery state because the source and destination agents lose communication, either because of a WebSphere MQ network error or because they are not receiving data or acknowledgment messages for a period. This period is determined by the agent properties: transferAckTimeout and transferAckTimeoutRetries.
- <numFileFailures>
- The number of files in the transferSet that failed to transfer successfully.
- <numFileWarnings>
- The number of files in the transferSet that generated warnings while being transferred, but otherwise transferred successfully.
Examples
Examples of XML messages that conform
to this schema are provided for each of the following types of transfer: