POST
Use the HTTP POST method with the transfer
resource to create a
transfer.
Resource URL
https://host:port/ibmmq/rest/v2/admin/mft/transfer/
v1
where the URL uses v2
. For example, the first
part of the URL is as follows:
https://host:port/ibmmq/rest/v1/
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.
Request headers
- 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 you are using basic authentication. For more information, see Using 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 you do not provide values for the other parameters in the request body, the default values are used.
- 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 Using token-based authentication with the REST API.
If you have set up a user sandbox, or MFT authority checking is turned on, you need to grant additional authority to the mqweb server user ID to access the specified file system location.
- 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 theMQWebUser
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.
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>
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.
- If the
Principal
name with an effectiveMQWebUser
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 thePrincipal
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. You should issue a GET command,
using the URL from the
location
response header to ascertain the state of the transfer. - 400
- Invalid data provided.
- 401
- Not authenticated.
- 403
- Not authorized.
- 500
- Server issue, or error code from IBM MQ or MFT.
- 503
- Queue manager not running.
Response headers
- 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 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 creates a simple file transfer. The following URL is used with the HTTP
POST method:
The following JSON payload is sent:https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/
{ "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:
The following JSON payload is sent:https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/
{ "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:
The following JSON payload is sent:https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/
{ "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:
The following JSON payload is sent:https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer/
{ "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 } }