GET - managed call

Use the HTTP GET method with the call resource to request information about the status of a Managed File Transfer managed call. You can query only the managed calls that are initiated after the mqweb server is started.

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
Optional query parameters
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

returns the attributes of a specified managed call in the response body.

Optional query parameters

attributes: Specifies a comma-separated list of attributes to retrieve.; 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 managed call. However, if you make a request that specifies a managed call ID and includes attributes that are not valid for that managed call, an error occurs.
limit: Specifies the maximum number of managed calls to retrieve.; This query parameter is valid only when no managed call ID is specified.; For example, if the limit=200, the REST API returns a maximum of 200 managed calls.
after: Specifies a managed call ID. All managed calls that are initiated after the specified managed call are retrieved. If you specify after, you cannot also specify before.; This query parameter is valid only when no managed call ID is specified.
before: Specifies a managed call ID. All managed calls that are initiated before that particular managedncall are retrieved. If you specify before, you cannot also specify after.; This query parameter is valid only when no managed call 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

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.

The security principal of the caller must be granted authority to subscribe to the SYSTEM.FTE 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

Manged call information retrieved successfully.

400

Invalid data provided.

For example, invalid attributes specified.

401

Not authenticated.

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

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 is not a member of one or more of the MFTWebAdmin, MFTWebAdminRO, or MQWebUser roles. For more information about the access that is required, see Security requirements.
Access prohibited in the current server environment. You cannot use the administrative REST API with the stand-alone IBM MQ Web Server.

404

A managed call 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-managed-calls: This header is returned with a value that is the total number of managed calls 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 call. Each element in the array is a JSON object that represents information about a manged call. Each of these JSON objects can contain the following objects and attributes.

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.; Name of the group containing the name of the job given to a managed call.
name: String; Specifies a user-defined job name for the managed call.
agent: JSON object.; Name of the group containing details of the agent to which a managed call request is submitted
name: String; Attribute in the agent group and refers to the agent name
qmgrName: String; Attribute in the agent group and refers to the agent queue manager name
priority: Integer; Priority assigned to the managed call. Same as MQMD.Priority with a value of 0 to 9.
userProperties: JSON object; 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; Name of the group containing attributes describing a managed call request.
retryCount: Integer; Specifies the number of attempts to run the command before ceasing.
retryWait: Integer; Specifies the amount of time to wait, in seconds, between retry attempts.
successReturnCode: String; 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; Identifies the type of managed call. antScript, executable, and jcl are the supported values
executable: JSON object; A JSON object that can contain attributes related to a platform-specific executable program to be invoked. This object can be specified only when the value of the type attribute is executable.
name: String; Specifies the name of the program to run. This attribute is required if the executable JSON object is specified.
arguments: String; Specifies a list of user-defined custom data in space separated key=value pairs.
antScript: JSON object; A JSON object that can contain attributes related to an Apache Ant script to be invoked. This object can only be specified when the value of the type attribute is antScript.
name: String; 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; Specifies a list of user-defined custom data in key=value pairs.
jcl: JSON object; A JSON object that can contain attributes related to a z/OS® JCL job to submit. This object can only be specified when the value of the type attribute is jcl.
name: String; Specifies the name of the JCL to submit.
results: JSON array; An array of JSON objects that describes the outcome of the processing of the script or program.; The response can contain multiple result object if the specified command has been retried.
Assuming the processing failed first and succeeded in the next attempt, the first result object has details of the failure and the second one has details of the success.
returnCode: Integer; Return code that describes the code returned by the processing of the command.
time: String; Date and time when processing of the command completed.
outcome: String; Outcome of the processing of a command. The possible values are success or failure.
consoleOutput: JSON array; A JSON array object that describes each line of the console output when the command was processed. This includes output in both stdout and stderr.
retries: Integer; Describes the number of times the command was retried before completing. The value can also be equal to the maximum retry count specified in the request if the command failed to succeed.
finalOutcome: String; Provides the description of the overall result of the processing of the command.
id: String; Unique identifier of the managed call.
originator: JSON object; A JSON object that identifies the initiator of managed call.
host: String; Identifies the name of the machine from where the managed call was submitted.
userId: String; Identifies the user that submitted the request.
mqmdUserId: String; Identifies the IBM MQ user that submitted the request.
status: JSON object; Contains attributes that are related to the status of the managed call. The state attribute in this object is always returned.
state: String; Describes the state of the managed call. Possible values are successful, failed, or in-progress
lastStatusUpdate: String; Describes the time (in UTC) when the state of the managed call was last updated.
statistics: JSON object; Describes the statistics of a managed call. Attributes of this object include the start and end time of the managed call.

Note: The managed call fails to complete if the total length of the console output exceeds 10KB. Message BFGCR0004E is logged by the agent in such a situation.

If an error occurs, see REST API error handling.

Examples

The following is an example of a response body with the default attributes of a managed call:

{
  "call": [
     {
       "agent": {
          "name": "SECURITIES.AGENT"
       },
       "id": "414D51204D4654514D20202020202020987C936103A80140",
       "command": {
          "retryWait": 0,
          "successReturnCode": "0",
          "retryCount": 0,
          "type": "antScript",
          "antScript": {
             "name": "/usr/cmds/hubprocess.xml",
             "arguments": "out.file=c:/temp/Catted.xsd",
             "target": "concatenate"
          }
        },
        "originator": {
           "host": "host.johnwatson.com",
           "userId": "john.watson"
        },
        "status": {
           "state": "started"
        }
      }
    ]
}

The following is an example of a response body with the status of the call in started state:

{
  "call": [
     {
       "agent": {
          "qmgrName": "SECURITIES.QM",
          "name": "SECURITIES.AGENT"
       },
       "priority": 0,
       "userProperties": {
          "com.ibm.wmqfte.SourceAgent": "SECURITIES.AGENT",
          "com.ibm.wmqfte.OriginatingUser": "john.watson",
          "com.ibm.wmqfte.OriginatingHost": "host.johnwatosn.com",
          "com.ibm.wmqfte.TransferId": "414d51204d4654514d20202020202020987c936103a80140",
          "com.ibm.wmqfte.MqmdUser": "john.watson",
          "com.ibm.wmqfte.Priority": "0",
          "com.ibm.wmqfte.DestinationAgent": "SECURITIES.AGENT"
       },
       "command": {
          "retryWait": 0,
          "retryCount": 0,
          "successReturnCode": "0"
          "type":"antScript",
          "antscript": {
             "name": "/usr/sample/hubprocess.xml",
             "target": "concatenate"
             "arguments": "out.file=/usr/out/outfile.txt
                in.file1=/usr/sample/input/infile1.txt
                in.file2=/usr/sample/input/infile2.txt"
           }
        },
        "id": "414D51204D4654514D20202020202020987C936103A80140",
        "originator": {
           "host": "host.johnwatson.com",
           "mqmdUserId": "john.watson",
           "userId": "john.watson"
        },
        "job": {
           "name": "pushsecurities"
        },
        "status": {
           "lastStatusUpdate": "2021-11-17T07:12:35.459Z",
           "state": "started"
        },
        "statistics": {
           "startTime": "2021-11-17T07:12:35.459Z"
        }
      }
    ]
}

The following is an example of a response body with failed status.

{
  "call": [{
     "agent": {
        "qmgrName": "SECURITIES.QM",
        "name": "SECURITIES.AGENT"
     },
     "priority": 0,
     "userProperties": {
        "com.ibm.wmqfte.SourceAgent": "SECURITIES.AGENT",
        "com.ibm.wmqfte.OriginatingUser": "john.watson",
        "com.ibm.wmqfte.OriginatingHost": "host.johnwatson.com",
        "com.ibm.wmqfte.TransferId": "414d51204d4654514d20202020202020987c936103a80140",
        "com.ibm.wmqfte.MqmdUser": "john.watson",
        "com.ibm.wmqfte.Priority": "0",
        "com.ibm.wmqfte.DestinationAgent": "SECURITIES.AGENT"
      },
      "results": {
         "result": [{
            "returnCode": 1,
            "completionTime":  2021-11-23T03:40:05.794Z",
            "outcome": "failure"
            "consoleOutput": [
               "BFGCL0207E: Target "concatenate1" does not exist in the project "null"."
            ]
         }],
          "retries": 0,
          "finalOutcome": "failure"
       },
       "command": {
          "retryWait": 0,
          "retryCount": 0,
          "type":"antScript",
          "antscript": {
             "name": "/usr/sample/hubprocess.xml",
             "target": "concatenate"  
             "successReturnCode": "0"
             "arguments": "out.file=/usr/out/outfile.txt
                in.file1=/usr/sample/input/infile1.txt
                in.file2=/usr/sample/input/infile2.txt"             
           }
        },
        "id": "414D51204D4654514D20202020202020987C936103A80140",
        "originator": {
           "host": "host.johnwatson.com",
           "mqmdUserId": "john.watson",
           "userId": "john.watson"
        },
        "job": {
           "name": "pushsecurities"
        },
        "status": {
           "lastStatusUpdate": "2021-11-17T07:12:35.459Z",
           "state": "failed"
        }
        "statistics": {
           "startTime":"2021-11-23T03:40:03.967Z",
           "endTime":"2021-11-23T03:40:05.794Z"
        }
      }
    ]
}