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
default
are always returned, and are
part of the default JSON response. All other attributes are returned only if queried.- qmgrName
- The name of the queue manager on the source system
- name (default)
- The name of the agent on the source system.
- qmgrName
- The name of the queue manager on the destination system
- name (default)
- The name of the agent on the destination system.
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)
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
- 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
- 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
- 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.
- checksum
- checksum does not appear if a checksum was not performed.
- 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
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.
- 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
- 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.
- checksum
- checksum does not appear if a checksum was not performed.
- 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
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.
- delimiter
- If delimiterType.size, for example
1K
- delimiterType
- Type of delimiter being used to split the messages. The valid values are:
- size
- Split by size
- binary
- Split by delimiter bytes
- includeDelimiterInMessage
- Valid only for delimiterType.binary.
- delimiterPosition
- Valid only for delimiterType.binary. The valid values are:
- "prefix"
- Before each message
- "postfix"
- After each message
Note, that if delimiterType is size, both includeDelimiterInMesage, and delimiterPosition are not included in the JSON.
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
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.
- 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.
- numberOfFileSuccesses (default)
- The number of files successfully transferred