POST

Resource URL

https://host:port/ibmmq/rest/v2/admin/mft/transfer/

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

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.

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 or MQWebUser roles. For more information about security for the administrative REST API, see IIBM® 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 the following additional authorities:

1. If the caller is a member of the MFTWebAdmin role, the user ID which started the mqweb server must be granted authority access to the transfer source location.
2. If the caller is a member of the MQWebUser role, the security principal of the caller must be granted access to the transfer 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.

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

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

Response status codes

Response headers

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
    }
  }