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 our Managed File Transfer installation.
To monitor file transfers or collect data about them, set up a subscription to a wildcard topic tailored to the transfers we are interested in. For example:Log/#or,
Log/FTEAGENT/#This subscription can be durable or non-durable. Durable subscriptions continue to exist when a subscribing application's connection to the queue manager is closed. Non-durable subscriptions exist only as long as a subscribing application's connection to the queue manager remains open.
Schema
The following schema describes which elements are valid in a transfer log XML message.
<xsd:schema xmlns:xsd="http://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>
Note: From Version 9.0, Managed File Transfer does not support the Web
Gateway or web agents.
Understand the transfer log message
- <transaction>
- Group element that specifies a group of transfers we want to
perform together.
Attribute Description version Specifies the version of this element as detailed by 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 "http://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 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
<sourceAgent> or <sourceWebUser> 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
- 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. - <destinationAgent>
- Specifies the name of the agent on the system the file was transferred to. Either
<destinationAgent> or
<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
- 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.
- <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 IBM 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 we 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 IBM 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: - queue - specifies an IBM MQ queue as the destination
- 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
The option queue can be present only when the <destination> element has a child element of <queue>. The other options can be present 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 IBM 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 IBM 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 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 an IBM 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:- A transfer of a single file
- A transfer that contains multiple files
- A failed file transfer
- A transfer defined with a trigger
- A transfer started by a schedule
- A transfer that calls user exits
- A transfer through a Connect:Direct bridge node
- Single transfer log message examples
When a transfer occurs, messages are published to the SYSTEM.FTE topic with a topic string of Log/agent_name/transfer_ID. The XML examples show the log messages for a single file transfer being started, in progress, and completed. - Multiple file transfer log message examples
Examples of the messages that are published to the SYSTEM.FTE topic with a topic string of Log/agent_name/transfer_ID when a transfer that contains multiple files occurs. - Failed file transfer log message examples
When a transfer occurs, messages are published to the SYSTEM.FTE topic with a topic string of Log/agent_name/transfer_ID. The XML examples show the log messages for a file transfer that fails being started, in progress, and completed. - Triggered file transfer log message example
When a transfer is in progress, messages are published to the SYSTEM.FTE topic with a topic string of Log/agent_name/transfer_ID. The XML example shows the log message that is created when a file transfer containing a trigger condition is started. - Scheduled file transfer log message examples
When a transfer is in progress, messages are published to the SYSTEM.FTE topic with a topic string of Log/agent_name/transfer_ID. The XML examples show the log messages that are created when a file transfer occurs as a result of a schedule. - MFT user exit log message examples
When a transfer is in progress, messages are published to the SYSTEM.FTE topic with a topic string of Log/agent_name/transfer_ID. The XML examples show the log messages that are created when a file transfer occurs that contains calls to user exits. - Connect:Direct bridge transfer log message examples
The destinationAgent or sourceAgent element contains additional attributes when the destination agent or source agent is a Connect:Direct bridge agent. The Started log message contains only a subset of the information about the Connect:Direct transfer. The Progress and Completed log messages contain full information about the Connect:Direct transfer.
Parent topic: XML message formats used by MFT
Related reference
- Single transfer log message examples
- Multiple file transfer log message examples
- Failed file transfer log message examples
- Triggered file transfer log message example
- MFT user exit log message examples
- Connect:Direct bridge transfer log message examples