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.

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/v2/admin/mft/transfer/{transferID}

Note: If you are using a version of IBM® MQ earlier than IBM MQ 9.1.5 you must use the v1 resource URL instead. That is, you must substitute v1 where the URL uses v2. For example, the first part of the URL is as follows: https://host:port/ibmmq/rest/v1/

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

[V9.1.4 Dec 2019] 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.

[V9.1.4 Dec 2019] The MQWebUser role requires Principal authority, and that principal requires subscribe authority to the relevant topic, that is SYSTEM.FTE/Transfer. The operation succeeds only if the principal of the MQWebUser role has authority to subscribed 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. See Security requirements for more information.
403: 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 or MFTWebAdminRO roles. See Security requirements for more information.
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 examples use the v2 resource URL. If you are using a version of IBM MQ earlier than IBM MQ 9.1.5 you must use the v1 resource URL instead. That is, in the resource URL, substitute v1 where the example URL uses v2.

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/v2/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/v2/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
      }
   }]
}