GET

Use the HTTP GET method with the agent resource to request information about Managed File Transfer agents.

Note: 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.

The information that is returned is similar to the information returned by the fteListAgents (list the MFT agents for a coordination queue manager) and fteShowAgentDetails (display MFT agent details) commands.

For more information about configuring the MFT REST API, see Configuring the REST API for MFT.

Resource URL
Optional query parameters
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/agent/{agentname}

agentName: Optionally specifies the name of the agent to query.; The agent name is not case-sensitive, but agent names that are entered in lowercase or mixed case are converted to uppercase. The agent name value that is received as a response from the REST API is always in uppercase.; The agent name can contain a maximum of 28 characters, and must conform to the IBM MQ rules for naming objects . In addition to the IBM MQ object naming conventions, the percent (%) character cannot be used in agent names.

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.

Optional query parameters

attributes={object,...|*|object.attributeName,...}

object

Specifies a comma-separated list of JSON objects that are added to a JSON object, which is a subsection of the complete details.

For example to return:

All general details of all agents or a particular agent, specify general.
All queue manager connection details of all agents or a particular agent specify qmgrConnection.
Details of connect direct bridge agent, specify connectDirectBridge. (applicable only for agent of type "connect direct bridge")
Details of protocol agent, specify protocolBridge. (applicable only for agents of type "protocol bridge")

For a full list of attributes see Response body attributes for agents

*

Specifies all attributes.

object.attributeName.,...

Specifies a comma-separated list of agent attributes to return.

Each attribute must specify the JSON object that contains the attribute, in the form object.attributeName. For example, to return the statusAge attribute, which is contained in the general object, specify general.statusAge.

You cannot specify the same attribute more than once. If you request attributes that are not valid for a particular agent, the attributes are not returned for that agent.

name=name

This parameter cannot be used if you specify an agent name in the resource URL. Specifies a wildcard agent name to filter on.

The name specified must include an * as a wildcard character. You can specify one of the following combinations:

*: Specifies that all agents are returned.
prefix*: Specifies that all agents with the specified prefix in the agent name are returned.
suffix*: Specifies that all agents with the specified suffix in the agent name are returned.
prefix*suffix: Specifies that all agents with the specified prefix and specified suffix in the agent name are returned.

type=validAgentType

Specifies the type of agent to return information about. The value can be one of the following values:

all: Specifies that information about all agents is returned. standard, connectDirectBridge, and protocolBridge agent information is returned.; This is the default value.
standard: Specifies that information about agent of type standard is returned.
connectDirectBridge: Specifies that information about agents of type connect direct bridge is returned.
protocolBridge: Specifies that information about agents of type protocol bridge is returned.

state=validAgentState

Specifies the state of the agent to return information about. The value can be one of the following values:

all: Specifies that information about all agents is returned. This information includes all the valid states listed in the following text.; This is the default value.
active: Specifies that information about agents that are in an active state is returned.
ready: Specifies that information about agents that are in a ready state is returned.
starting: Specifies that information about agents that are in a starting state is returned.
unreachable: Specifies that information about agents that are in an unreachable state is returned.
stopped: Specifies that information about agents that are in a stopped state is returned.
stopping: Specifies that information about agents that are in a stopping state is returned.
endedUnexpectedly: Specifies that information about agents that are in an endedUnexpectedly state is returned.
noInformation: Specifies that information about agents that are in a noInformation state is returned.
unknown: Specifies that information about agents that are in an unknown state is returned.
problem: Specifies that information about agents that are in a problem state is returned.

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/Agents 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

Agent information retrieved successfully.

400

Invalid data provided.

For example, invalid agent 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. The administrative REST API is not available in a stand-alone IBM MQ Web Server installation.

404

Agent 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.

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 agent. Each element in the array is a JSON object that represents information about an agent. Each of these JSON objects contains the following attributes:

name

String.

Specifies the name of the agent.

This attribute is always returned.

type

String.

Specifies the type of agent.

The value is one of the following values:

standard
connectDirectBridge
protocolBridge

state

Specifies the state of the agent. The value can be one of the following values:

active
ready
starting
unreachable
stopping
stopped

general

Contains attributes that are related to general agent properties, such as the agent description, the agent age, and the version and level of the queue manager.

queueManagerConnection

This object provides information about the queue manager connections, such as the queue manager name, and transport type.

connectDirectBridge

This object provides information about to connect direct bridge type agent, such as the node name, host, and port.

protocolBridge

This object provides information about protocol bridge type agent, such as the endpoints and default server.

standbyInstance

This object provides information about the status of the standby instances

For more information, see Response body attributes for transfers.

If an error occurs, see REST API error handling.

Examples

The following example returns the basic details of all agents, that is, only the following information is displayed:

agent name
agent type
agent state

The following URL is used with the HTTP GET method:

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

The following JSON response is returned:

{
   "agent":[{
      "name": "AGENT1",
      "state": "ready",
      "type": "standard"
   },
   {
      "name": "AGENT2",
      "state": "ready",
      "type": "standard"
   },
   { 
      "name": "BRIDGE_AGENT3",                
      "type": "protocolBridge",
      "state": "ready"
   },
   {
      "name": "CD_AGENT",
      "type": "connectDirectBridge",
      "state": "ready"
   }
]}

The following example lists all the agent of type standard, along with the general object. The following URL is used with the HTTP GET method:

https://localhost:9443/ibmmq/rest/v2/admin/mft/agent?attributes=general&type=standard

The following JSON response is returned:

{
   "agent":[{
      "name": "SRC",
      "state": "ready",
      "type": "standard",
      "general": { 
         "description": "Standard connected to the qmgr in client mode", 
         "statusAge": "06:31:00", 
         "version": "9.1.5.0", 
         "level": "p915-L190514",   
         "statusPublicationRate": 300,  
         "statusPublishTime": "2019-05-14T06:57:07.000Z",
         "maximumQueuedTransfers": 1000, 
         "maximumDestinationTransfers": 25,
         "maximumSourceTransfers": 25,
         "operatingSystem": "Windows10"
      },
      "standbyInstance": [
             {
                 "host":"MFTHA1",
	          "version":"9.1.5.0"
             },
             {
                 "host":"9.122.123.124",
                 "version":"9.1.5.0"
             }
	 ]
   }]
}

Note that the standbyInstance attributes are displayed only if the agent is enabled as highly available.

The following example lists all the agents starting with the name AGENT, in a ready state, and of type standard, along with the general object of statusAge. The following URL is used with the HTTP GET method:

https:/localhost:9443/ibmmq/rest/v2/admin/mft/agent?name=AGENT*&state=ready&type=standard&attributes=general.statusAge

The following JSON response is returned:

{
   "agent":[{   
      "name": "AGENT1",
      "state": "ready",
      "type": "standard",
      "general":{ 
         "statusAge": "05:00:00" 
      }
   },
   { 
       "name": "AGENT2",
       "state": "ready",
       "type": "standard",
       "general":{ 
          "statusAge": "03:00:00"
       }
    },
    { 
       "name": "AGENT3",               
       "state": "ready",
       "type": "standard",
       "general":{
          "statusAge": "05:00:00"
       }
    }
]}