POST - managed call

Use the HTTP POST method with the call resource to create a Managed File Transfer managed call.

Note:

This resource is available only from version 3 of the IBM® MQ REST API.
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 managed calls, see Managed calls.

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

Resource URL

https://mqweb.ibm.com:9443/ibmmq/rest/v3/admin/mft/call

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

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 you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.

Request body format

The request body must contain attributes for only one managed call. Submitting multiple managed calls in a single request is not allowed.

The body can contain details of an AntScript, executable or a JCL (for agents running on z/OS®).

The following section describes the request body format for each of the types. Note that the attributes of the command section of a managed call are the same as the attributes described in the preSourceCall section of Request body attributes for transfers with HTTP POST.

Attention: Use the appropriate name parameter for the variable that your enterprise uses.

Which objects and attributes are returned depends on the URL that was specified for the request:

job: JSON object.; Optional; Name of the group containing the name of the job given to a managed call.
name: String; Required if you specified the job attributes; Specifies a user-defined job name for the managed call.
agent: JSON object.; Required; Name of the group containing details of the agent to which a managed call request is submitted
name: String; Required; Attribute in the agent group and refers to the agent name
qmgrName: String; Required; Attribute in the agent group and refers to the agent queue manager name
priority: Integer; Optional; Priority assigned to the managed call. Same as MQMD.Priority with a value of 0 to 9.
userProperties: JSON object; Optional; Name of the group that contains attributes where each attribute refers to user-defined meta data. The name and value of each attribute is defined by the user.
command: JSON object; Required; Name of the group containing attributes describing a managed call request.
retryCount: Integer; Optional - zero is assumed if not specified.; Specifies the number of attempts to run the command before ceasing.
retryWait: Integer; Optional - zero is assumed if not specified.; Specifies the amount of time to wait, in seconds, between retry attempts.
successReturnCode: String; Required; Specifies the condition, based on the return code from the executable, AntScript, or JCL, that must be true in the order for the managed call to be successful.; The condition is specified as an operator, followed by a value. Valid characters for the operator are >, <, !, and =.
It is valid to have a combination of more than one operator. See successrc for more information on the operators.; For example, an expression ">2&<7&!5|0|14" indicates that the return codes of 0, 3, 4, 6, and 14 are considered as success.; The default value is zero.
type: String; Required; Identifies the type of managed call. antScript, executable, and jcl are the supported values
executable: JSON object; Required if the value of the type attribute is executable, and can be specified only when the value of the type attribute is executable; A JSON object that can contain attributes related to a platform-specific executable program to be invoked.
name: String; Required if the value of the type attribute is executable, and can be specified only when the value of the type attribute is executable; Specifies the name of the program to run.
arguments: String; Optional; Specifies a list of user-defined custom data in space separated key=value pairs.
antScript: JSON object; Required if the value of the type attribute is antScript, and can be specified only when the value of the type attribute is antScript; A JSON object that can contain attributes related to an Apache Ant script to be invoked.
name: String; Required if the value of the type attribute is antScript, and can be specified only when the value of the type attribute is antScript; Specifies the name of the Ant script to run.
target: String; Specifies the target to invoke in the specified Ant script. If this attribute is not specified, the target named default is invoked
arguments: JSON object; Optional; Specifies a list of user-defined custom data in key=value pairs.
jcl: JSON object; Required if the value of the type attribute is jcl, and can be specified only when the value of the type attribute is jcl; A JSON object that can contain attributes related to a z/OS JCL job to submit.
name: String; Required if the value of the type attribute is jcl, and can be specified only when the value of the type attribute is jcl; Specifies the name of the JCL to submit.

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 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, grant additional authority to the mqweb server user ID to access the specified file system location. For example, to restrict file system or queue access to only user IDs that contain the characters a,A or b,B:

<tns:userSandboxes
         xmlns:tns="http://wmqfte.ibm.com/UserSandboxes"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://wmqfte.ibm.com/UserSandboxes UserSandboxes.xsd">

    <tns:agent>
         <tns:sandbox user="^[a-bA-B]*$" userPattern="regex">
              <tns:read>
                  <tns:include name="/mountpath/**"/>
                  <tns:include name="**" type="queue"/>
              </tns:read>
              <tns:write>
                   <tns:include name="/mountpath/**"/>
                   <tns:include name="**" type="queue"/>
              </tns:write>
        </tns:sandbox>
     </tns:agent>
</tns:userSandboxes>

If you have MFT authority checking turned on, grant additional authorities as described in Restricting user authorities on MFT agent actions.

For the MFTWebAdmin role, managed call 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 managed call request submitted contains the name of the authenticated user as the managed call originator. This method ensures that there is a record of who initiated the managed call request.

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

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

where:

hostName: Is the name of host where the mqweb server is running.
userId: Is the name of the user that is logged in to the mqweb server.
mqmdUserId: Is the name of the user under which the mqweb server is running and connects to the command queue manager.

If the caller is a member of the MQWebUser role, the security principal of the caller must be granted one of the following authorities:

If the command queue is local, that is, the command queue manager and source agent queue manager are the same, grant put authority to the command queue.
If the command queue is remote, that is, the command queue manager and source agent queue manager are different, grant put authority to the transmission queue.

Notes:

If the user ID of a principal that is a member of the MQWebUser role is longer than 12 characters, the request fails. Response status code 403 is returned to the caller.
If the caller is assigned more than one role, the highest privilege role that is applicable to the operation is used.

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 managed call 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 managed call.

400

Invalid data provided.

For example, invalid attributes specified.

401

Not authenticated.

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

The ibm-mq-rest-csrf-token header must also be specified.

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 does not have access to the required IBM MQ or MFT resources.
Access prohibited in the current server environment. The administrative REST API is not available in a stand-alone IBM MQ Web Server installation.

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 managed call.

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

An example of a request body format for a managed call for running an antScript:

{
  "job": {
     "name": "pushsecurities"
   },
   "agent": {
      "name":"SECURITIES.AGENT",
      "qmgrName":"SECURITIES.QM"
   },
   "priority": 0,
   "command": {
      "retryCount": 0,
      "retryWait": 0,
      "successReturnCode":"0",
      "type":"antScript",
      "antScript": {
      "name": "publish.xml",
      "target": "publishsecurities",
         "arguments": "filename=abc.csv updateInterval=5"
     }
   }
}

An example of a request body format for a managed call for running an executable:

{
  "job": {
     "name": "compressfiles"
   },
   "agent": {
      "name":"SECURITIES.AGENT",
      "qmgrName":"SECURITIES.QM"
   },
   "priority": 0,
   "command": {
      "retryCount": 0,
      "retryWait": 0,
      "successReturnCode":"0",
      "type":"executable",
      "executable": {
         "name": "compress.sh",
         "arguments": "filename zlib"
      }
   }
}

An example of a request body format for a managed call with JCL to be run by an agent running z/OS:

{
  "job": {
     "name": "pushsecurities"
   },
   "agent": {
      "name":"SECURITIES.AGENT"
      "qmgrName":"SECURITIES.QM"
   },
   "priority": 0,
   "command": {
      "retryCount": 0,
      "retryWait": 0,
      "successReturnCode":"0",
      "type":"jcl",
      "jcl": {
            "name": "publish",
      }
   }
}