GET

Use the HTTP GET method with the transfer resource to request information about transfers and transfer status. You can query only the transfers that are initiated after the mqweb server is started.

Note:

You must set a coordination queue manager before you can use the transfer resource. For more information, see Configuring the REST API for MFT.
The mqweb server caches information about transfers and returns this information when a request is made. This cache is reset when the mqweb server is restarted. You can see if the server has been restarted by viewing the console.log and messages.log files, or on z/OS® looking at the output from the started task.
This resource is not available in a stand-alone IBM® MQ Web Server installation. For more information about the installation options for the IBM MQ component that runs the administrative REST API, see The IBM MQ Console and REST API.

For more information about configuring the MFT REST service, see Configuring the REST API for MFT.

Resource URL
Optional query parameters
Request headers
Request body format
Security requirements
Response status codes
Response headers
Response body format
Examples

Resource URL

https://host:port/ibmmq/rest/v3/admin/mft/transfer/{transferID}

transferID: Optionally specifies the ID of the transfer to query.; If you do not specify a transfer ID, a list of transfers is returned.

You can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configuring the HTTP and HTTPS ports.

Optional query parameters

attributes: Specifies a comma-separated list of attributes to retrieve.; This query parameter is valid only when a transfer ID is specified.; If you do not specify attributes, the default set of attributes is returned. See Response body attributes for transfers for a list of the available attributes.; You cannot request the same attribute multiple times.; You can specify an asterisk, *, to specify that all attributes are returned.; You can make a request that specifies attributes that are not valid for some of the transfers. However, if you make a request that specifies a transfer ID and includes attributes that are not valid for that transfer, an error occurs.
limit: Specifies the maximum number of transfers to retrieve.; This query parameter is valid only when no transfer ID is specified.; For example, if the limit=200, the REST API returns a maximum of 200 transfers.
after: Specifies a transfer ID. All transfers that are initiated after the specified transfer are retrieved. If you specify after, you cannot also specify before.; This query parameter is valid only when no transfer ID is specified.
before: Specifies a transfer ID. All transfers that are initiated before that particular transfer are retrieved. If you specify before, you cannot also specify after.; This query parameter is valid only when no transfer ID is specified.

Request headers

The following header must be sent with the request:

Authorization: This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.

Request body format

None.

Security requirements

The caller must be authenticated to the mqweb server and must be a member of one or more of the MFTWebAdmin, MFTWebAdminRO, or MQWebUser roles. For more information about security for the administrative REST API, see IBM MQ Console and REST API security.

The security principal of the caller must be granted authority to subscribe to the SYSTEM.FTE/Transfer topic.

If token based security is used, the LTPA token that is used to authenticate the user must be provided with the request as a cookie. For more information about token-based authentication, see Using token-based authentication with the REST API.

Response status codes

200

Transfer information retrieved successfully.

400

Invalid data provided.

For example, invalid attributes specified.

401

Not authenticated.

The caller must be authenticated to the mqweb server. For more information, see Security requirements.

403

Access prohibited for one of the following reasons:

Not authorized. The caller is authenticated to the mqweb server and is associated with a valid principal. However, the principal is not a member of one or more of the MFTWebAdmin, MFTWebAdminRO, or MQWebUser roles. For more information about the access that is required, see Security requirements.
Access prohibited in the current server environment. You cannot use the administrative REST API with the stand-alone IBM MQ Web Server.

404

A transfer with the specified ID does not exist.

500

Server issue or error code from IBM MQ.

503

Queue manager not running.

Response headers

Content-Type: This header is returned with a value of application/json;charset=utf-8.
ibm-mq-rest-mft-total-transfers: This header is returned with a value that is the total number of transfers that have details available in the mqweb server cache.

Response body format

The response is in JSON format in UTF-8 encoding. The response contains an outer JSON object that contains a single JSON array called transfer. Each element in the array is a JSON object that represents information about a transfer. Each of these JSON objects can contain the following objects and attributes. Which objects and attributes are returned depends on the URL that was specified for the request:

id: String.; Specifies the unique transfer or transaction ID. The ID can be a maximum of 48 alphanumeric characters.; This attribute is always returned.
job: JSON object.; Contains the job name for the transfer.
userProperties: JSON object.; Contains additional meta data about the transfer. For example: "userProperties":{"key1":"value1"}
sourceAgent: JSON object.; Contains attributes that are related to the agent on the source system.; The name attribute in this object is always returned.
destinationAgent: JSON object.; Contains attributes that are related to the agent on the destination system.; The name attribute in this object is always returned.
originator: JSON object.; Contains attributes that are related to the originator of the request.; The host and host attributes in this object are always returned.
transferSet: JSON object.; Contains attributes that are related to the group of file transfers.
status: JSON object.; Contains attributes that are related to the status of the transfer.; The state attribute in this object is always returned.
statistics: JSON object.; Contains attributes that are related to the statistics of the transfer.; The startTime, numberOfFileFailures , numberOfFileSuccesses, numberOfFileWarnings, numberOfFiles and endTime attributes in this object are always returned.

For more information, see Response body attributes for transfers.

If an error occurs, see REST API error handling.

Examples

The following example returns a default set of data in the response.

The following URL is used with the HTTP GET method:

https://localhost:9443/ibmmq/ibmmq/rest/v3/admin/mft/transfer/414d512050524d465444454d4f312020f5189c5921f22302

The following JSON response is returned:

{                
   "transfer": [{                                
      "id": "414D512050524D465444454D4F312020F5189C5921F22302",
      "destinationAgent": {
          "name": "AGENT.TRI.BANK"
      },
      "originator": {
         "host": "192.168.99.1",
         "userId": "johndoe"
      },
      "sourceAgent": {
         "name": "TESTAGENT"
      },
      "statistics": {
         "endTime": "2018-01-08T16:22:15.569Z",
         "numberOfFileFailures": 0,
         "numberOfFileSuccesses": 2,
         "numberOfFileWarnings": 0,
         "numberOfFiles": 2,
         "startTime": "2018-01-08T16:22:15.242Z"
      },
      "status": {
         "state": "successful"
      }
   }]
}

The following example lists all the attributes for the specified transfer ID, on the coordination queue manager. The following URL is used with the HTTP GET method:

https://localhost:9443//ibmmq/rest/v3/admin/mft/transfer/414d512050524d465444454d4f312020c5c6705924cf9e02?attributes=*

The following JSON response is returned:

{                
   "transfer": [{                                
      "id": "414D512050524D465444454D4F312020C5C6705924CF9E02",	               
      "sourceAgent": {			
         "qmgrName": "PRMFTDEMO1",
         "name": "AGENT2"	
      },
      "destinationAgent": {
         "qmgrName": "PRMFTDEMO1",
         "name": "AGENT1"                                              
      },
      "originator": {
         "host": "192.168.56.1",
         "userId": "johndoe",
         "mqmdUserId": "johndoe"
      },
      "transferSet": {
         "item": [{
            "source": {
               "file": {
                  "lastModified": "2017-07-13T11:25:20.780Z",
                  "size":179367055 ,
                  "path": "D:/ProgramFiles/WASlibertyprofile.zip"
               },
               "checksum": {
                  "method": "md5",
                  "value": "5F0ED36FBD3C0E1F4083B12B34A318D3"
               },
               "disposition": "leave",
               "type": "file"
            },
            "destination": {
               "file": {
                  "lastModified": "2017-07-28T08:00:12.065Z",
                  "size": 179367055,
                  "path": "C:/Users/IBMADMIN/Desktop/demo.zip"
               },
               "checksum": {
                  "method": "md5",
                  "value": "5F0ED36FBD3C0E1F4083B12B34A318D3"
               },
               "actionIfExists": "overwrite",
               "type": "file"
            }, 
            "status": { 
               "description": "BFGRP0032I: The file transfer request has successfully completed."           
               "state":"successful"
            }
            "mode": "binary"
         }],
         "bytesSent": 0,
         "startTime": "2017-07-28T08:00:10.599Z"
      },
      "job": {
         "name":"job1"
      },
      "userProperties":{
      },
      "status": {
         "lastStatusUpdate": "2017-07-28T08:00:10.599Z",
         "state":"successful",
         "description": "BFGRP0032I: The file transfer request has successfully completed."
      },
      "statistics": {
         "startTime": "2017-07-28T08:00:09.897Z",
         "retryCount": 0,
         "endTime": "2017-07-28T08:00:10.599Z",
         "numberOfFilesSuccesses":1,
         "numberOfFileFailures": 0,
         "numberOfFileWarnings": 0,
         "numberOfFiles":1
      }
   }]
}