Response body attributes for transfers

A description of the attributes available to the MFT REST API in the JSON response body.

Outer object attributes

id: Specifies the unique transfer or transaction ID. The ID can be a maximum of 48 alphanumeric characters
job: Job Name for the transfer (if specified)
sourceAgent: Specifies the name of the agent (along with other details) on the system where the source file is located
destinationAgent: Specifies the name of the agent (along with other details) on the system to which the file has been transferred
originator: Group element that contains the elements specifying the originator of the request
transferSet: Contains an array of items, that consists of all the information about the transfers, such as source filename, destination filename, along with each of their path location, size of file, and so on.
userProperties: Contains some additional meta data information about the transfer (if you provided this information before starting the transfer). For example: “userProperties":{“key1":"value1"}
status: The state and description messages for the status of the transfer
statistics: Group element for statistical information for the transfer (when available)

Inner object attributes

Attention: The attributes marked default are always returned, and are part of the default JSON response. All other attributes are returned only if queried.

sourceAgent

qmgrName: The name of the queue manager on the source system
name (default): The name of the agent on the source system.

destinationAgent

qmgrName: The name of the queue manager on the destination system
name (default): The name of the agent on the destination system.

originator

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

host (default): The host name of the system where the source file is located.
userID (default): The user ID that originated the file transfer
mqmdUserId: The IBM® MQ user ID that was supplied in the message descriptor (MQMD)

transferSet

Specifies a group of file transfers you want to perform together. During transmission, transferSet is a group element containing an array of item objects.

item: Group element that contains elements specifying the source and destination file names and locations
bytesSent: Total bytes sent
startTime: Records the time that the set of transfers started, expressed in UTC format

item

source: Group element that contains the file element or the queue element, and the checksum element for the file on the source system
destination: Group element that contains the file element or the queue element, and the checksum element for the file on the destination system; Only one of file and queue is present as a child element of destination
status: The state for a transfer; that is for a particular item object inside the transferSet
mode: Specifies the transfer mode as either binary or text

source

recursive

Specifies that files are transferred recursively in sub-directories, 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

file

Specifies the absolute path of the file that was transferred. The fully-qualified path is in the format consistent with your operating system, for example C:/from/here.txt. Note that a file URI is not used.

The valid options are as follows:

lastModified: Last modified date and time for the file (UTC format)

size: File size

path

Path location for the file

encoding

The encoding for a text file transfer

endOfLine

Specifies the end of line marker. The permitted values are:

LF - line feed character only
CRLF - carriage return and line feed character sequence

checksum

checksum does not appear if a checksum was not performed.

Specifies the type of hash algorithm that generated the message digest to create the digital signature. 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.

The valid options are:

method: Method used for generating checksum

value: Checksum value generated

type

Specifies the type of source. The valid options are as follows:

queue: Specifies an IBM MQ queue as the source

file: Specifies a file as the source, if the source is a file or directory

dataset: Specifies a z/OS® dataset as the source

dataset

Specifies a z/OS dataset. The valid options are as follows:

attributes: Attributes related to the dataset

size: File size

name: Name of the dataset

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.

messageCount

The number of messages that were read from the queue

name

Name of the queue along with the queue manager name, as shown

queueName@queueManagerName

setMqProperties

A boolean operator specifying whether IBM MQ message properties are set on the first message in a file, and any messages written to the queue when an error occurs.

destination

actionIfExists

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

file

The valid options are as follows:

lastModified: Last modified date and time for the file (UTC format)

size: File size

path: Path location for the file

checksum

checksum does not appear if a checksum was not performed.

The valid options are:

method: Method used for generating checksum

value: Checksum value generated

type

Specifies the type of source. The valid options are as follows:

queue: Specifies an IBM MQ queue as the source

file: Specifies a file as the source, if the source is a file or directory

dataset: Specifies a z/OS dataset as the source

dataset

Specifies a z/OS dataset. The valid options are as follows:

attributes: Attributes related to the dataset

size: File size

name: Name of the dataset

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.

messageCount

The number of messages that were written to the queue

messageLength

The length of the message written to the queue

name

Name of the queue along with the queue manager name, as shown

queueName@queueManagerName

messageOrGroupId

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.

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.

delimiter: If delimiterType.size, for example 1K; If delimiterType.binary, for example 12; If delimiter is an empty string, that is, “", the field is not set while initiating the transfer

delimiterType

Type of delimiter being used to split the messages. The valid values are:

size: Split by size
binary: Split by delimiter bytes

If delimiterType is an empty string, that is, “", the field is not set while initiating the transfer

includeDelimiterInMessage

Valid only for delimiterType.binary.

This option can be true or false. For example:

"includeDelimiterInMessage" : true

delimiterPosition

Valid only for delimiterType.binary. The valid values are:

"prefix": Before each message

"postfix": After each message

If delimiterPosition is an empty string, that is, “", the field is not set while initiating the transfer

Note, that if delimiterType is size, both includeDelimiterInMesage, and delimiterPosition are not included in the JSON.

status

Group element for status information for the transfer.

state (default)

The state of the transfer. The value can be one of the following:

started
inProgress
successful
failed
partiallySuccessful
cancelled
malformed - indicates that the file transfer request message content can not be interpreted
notAuthorized
deleted
inProgressWithFailures
inProgressWithWarnings

lastStatusUpdate

Most recent time when the transfer status was captured, expressed in UTC format

description

More detailed information about the status completion. Whether it is:

Partially successful
Successful
Failed, or
Any other relevant information

statistics

Group element for statistical information for the transfer (when available).

startTime (default): The time when the transfer was submitted (UTC format)
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 the agents are not receiving data or acknowledgment messages for a period.; This period is determined by the agent properties: transferAckTimeout and transferAckTimeoutRetries.
numberOfFilefailures (default): The number of files in the transferSet that failed to transfer successfully
numberOfFileWarnings (default): The number of files in the transferSet that generated warnings while being transferred, but otherwise transferred successfully
numberOfFiles (default): This number denotes the total number of files included in the current transfer request. This number includes all the files considered for the transfer operation
endTime (default): The time when the transfer was completed. This field gets updated only when the transfer is complete.; If the transfer is in any other state, then “endTime" will be an empty string
numberOfFileSuccesses (default): The number of files successfully transferred