POST

Use the HTTP POST method with the transfer resource to create a transfer.

Note: We must set a command queue manager before we can create a transfer with the transfer resource. For more information, see Configure the REST API for MFT.

Resource URL
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/

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

Request headers

The following headers must be sent with the request:

Content-Type: This header must be sent with a value of application/json optionally followed by ;charset=UTF-8.
ibm-mq-rest-csrf-token: This header must be set, but the value can be anything, including being blank.
Authorization: This header must be sent if we are using basic authentication. For more information, see Use HTTP basic authentication with the REST API.

Request body format

The request body must be in JSON format in UTF-8 encoding. Attributes marked required are mandatory. If we do not provide values for the other parameters in the request body, the default values are used.

The following objects can be included in the request body:

job: Contains attributes that are related to the transfer job.
sourceAgent: Contains attributes that are related to the source agent. This object is required.
destinationAgent: Contains attributes that are related to the destination agent. This object is required.
scheduleTransfer: Contains attributes that are related to scheduling a transfer.
transferSet: Contains attributes that are related to the transfer.

See Request body attributes for transfers with HTTP POST for a list of all the attributes.

Security requirements

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

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

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 Use token-based authentication with the REST API.

If we have set up a user sandbox, or MFT authority checking is turned on, we need to grant additional authority to the mqweb server user ID to access the specified file system location.

If we have set up a user sandbox, or MFT authority checking is turned on, we need to grant the following additional authorities:

For the MFTWebAdmin role, the user ID which started the mqweb server needs to have access to the specified file system location.
For the MQWebUser role, the principal of the MQWebUser role needs access to the specified source location.

For the MFTWebAdmin role, transfer requests are submitted under the context of the mqweb server user ID. To distinguish between different principals of the MFTWebAdmin role, and for audit purposes, the transfer request submitted contains the name of the authenticated user as the transfer originator. This method ensures that there is a record of who initiated the transfer request.

For example, if the user mftadminusr, of the MFTWebAdmin role, initiates a transfer with this login, the originator data in the XML that is created to describe the transfer has mftadminusr in the userID element, as shown in this example:

<originator>
  <hostName>example.com.</hostName>
  <userID>mftadminusr</userID> 
</originator>

For the MQWebUser role support, the principal logged onto the Liberty profile requires the following authority. If the command queue is:

Local, grant PUT authority to the command queue.
Remote, that is, when the command queue manager and source agent queue manager are different, grant PUT authority to the transmission queue.

Notes:

If the Principal name with an effective MQWebUser role is longer than 12 characters, the request fails with a 403 return code.
If the Principal is configured to have multiple roles, only one role applies when determining behavior, and that role is determined by the Principal having the highest privileges applicable to the requested REST API operation.

If security is disabled on the mqweb server, the transfer request submitted contains the name "UNAUTHENTICATED" as the transfer originator.

Response status codes

202: The file transfer request has been accepted by the REST API. It might still get rejected by the MFT agent. We should issue a GET command, using the URL from the location response header to ascertain the state of the transfer.
400: Invalid data provided.; For example, invalid attributes specified.
401: Not authenticated.; The user must be authenticated to the mqweb server. See Security requirements for more information.; The ibm-mq-rest-csrf-token header must also be specified.
403: Not authorized.; The caller is authenticated to the mqweb server and is associated with a valid principal. However, the principal does not have access to all, or a subset, of the required IBM MQ or MFT resources.
500: Server issue, or error code from IBM MQ or MFT.
503: Queue manager not running.

Response headers

The following header is returned with the response:

location: If the request was successful, this header specifies the URL for the new transfer.

Response body format

The response body is empty if the transfer is created successfully.

If an error occurs, the response body contains an error message; see REST API error handling.

Examples

The following example creates a simple file transfer. The following URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/

The following JSON payload is sent:

{
  "sourceAgent": {
     "qmgrName": "NYQM",
     "name": "NY.AGENT"
  }, 
  "destinationAgent": {
     "qmgrName": "WASHQM",
     "name": "WASH.AGENT"
  },
  "transferSet": {
     "item": [
        {
           "source": {
              "name": "C:\\temp\\src\\test.txt",
              "type": "file"
           },
           "destination": {
              "name": "C:\\temp\\dst\\test.txt",
              "type": "file"
           }
        }
     ]
  }
}

The following example creates a transfer from a file to a queue. The following URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/

The following JSON payload is sent:

{
  "job": {
     "name": "TESTJOB",
  },
  "sourceAgent": {
     "name": "WASH.AGENT",
     "qmgrName": "WASHQM"
  },
  "destinationAgent": {
     "name": "NY.AGENT",
     "qmgrName": "NYQMGR"
  },
  "transferSet": {
     "priority": 1,
     "recoveryTimeout": -1,
     "item": [
        {
           "checksum": "md5",
           "mode": "text",
           "destination": {
              "actionIfExists": "error",
              "name": "LQ@NYQMGR",
              "type": "queue",
              "delimiterType": "size",
              "messagePersistence": "persistent",
              "queueExtended": {
                 "messageSize": 4,
                 "setMQProperties": false
              }
           },
           "source": {
              "disposition": "leave",
              "name": "C:\\temp\\src\\test.txt",
              "recursive": false,
              "type": "file"
           }
        }
     ]
  }
}

The following example creates a transfer from a directory to a directory. The following URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/

The following JSON payload is sent:

{
  "job": {
     "name": "TESTJOB",
  },
  "sourceAgent": {
     "name": "WASH.AGENT",
     "qmgrName": "WASHQM"
  },
  "destinationAgent": {
     "name": "NY.AGENT",
     "qmgrName": "NYQMGR"
  },
  "transferSet": {
     "item": [
        {
           "checksum": "md5",
           "destination": {
              "actionIfExists": "error",
              "name": "C:\\temp\\dst",
              "type": "directory"
           },
           "source": {
              "disposition": "leave",
              "name": "C:\\temp\\src",
              "recursive": false,
              "type": "directory"
           }
        }
     ]
  }
}

The following example creates a transfer from a file to a file, using preSourceCall, postSourceCall, preDestinationCall, and postDestinationCall to invoke programs during the transfer. The following URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/

The following JSON payload is sent:

{
  "sourceAgent": {
     "qmgrName": "NYQM",
     "name": "NY.AGENT"
  },
  "destinationAgent": {
     "qmgrName": "WASHQM",
     "name": "WASH.AGENT"
  },
  "transferSet": {
     "item": [
        {
           "source": {
              "name": "C:\\temp\\src\\test.txt",
              "type": "file"
           },
           "destination": {
              "name": "C:\\temp\\dst\\test.txt",
              "type": "file"
           }
	 }
     ],
     "userProperties": {
        "ARCHIVE_PATH": "C:\\MFT\\ARCHIVE",
        "REJECT_PATH": "C:\\MFT\\REJECT"
     },
     "postSourceCall": {
        "type": "executable",
        "executable" : {
           "name": "posttransfersource.exe",
           "arguments": "postdata1 postdata2"
        }
     },
     "postDestinationCall": {
        "type": "executable",
        "executable" : {
           "name": "posttransferdest.exe",
           "arguments": "postdataDest1 postdataDest2"
        }
     },	 
     "preDestinationCall": {
        "type": "executable",
        "executable": {
           "name": "pretransferdest.exe"
        }
     },
     "preSourceCall": {
        "type": "executable",
        "executable" : {
           "name": "posttransferdest.exe",
           "arguments": "predata1 predata2"
        }
     },
     "priority": 0,
     "recoveryTimeout": 21600
  }
}

Request body attributes for transfers with HTTP POST
When you create the request body for creating a transfer request with the administrative REST API for MFT, we can specify attributes for the transfer within named JSON objects. A number of objects and attributes are available.

Parent topic: /admin/mft/transfer

Related reference

Request body attributes for transfers with HTTP POST

Related information

Getting started with the REST API for MFT