GET

Use the HTTP GET method with the monitor resource to list information about the MFT resource monitor status, and other configuration information.

Note:

You must set a coordination queue manager before you can use the monitor resource. For more information, see Configuring the REST API for MFT.
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 configuring the MFT REST service, 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/v3/admin/mft/monitor/{monitorName}

monitorName: Optionally specifies the name of the monitor to query.; If you do not specify a monitor name, a list of monitors is returned.; If you want to return a list of monitors with a wild carded monitor name, use the name optional query parameter to specify the monitor name instead of specifying the monitor name in the base URL.

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

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 list resource monitor 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 resource monitor information. However, if you make a request that specifies resource monitor information and includes attributes that are not valid for that information, an error occurs.

You cannot have more than three levels of nesting. For example, you cannot directly query the transferDefinition.transferSet.postDestCall.retryWait, only the transferDefinition.transferSet.postDestCall. Therefore, when querying the transferDefinition, you can query only the following attributes:

transferDefinition: Returns the complete details of the transfer definition.
transferDefinition.sourceAgent: Returns the complete details of the sourceAgent section of the transfer definition.
transferDefinition.destinationAgent: Returns the complete details of the destinationAgent section of the transfer definition.
transferDefinition.originator: Returns the complete details of the originator section of the transfer definition.
transferDefinition.transferSet: Returns the complete details of the transferSet section of the transfer definition.
transferDefinition.transferSet.item: Returns the complete details of all transfer items in the item section of the transfer definition.
transferDefinition.transferSet.preSourceCall: Returns the complete details of the preSourceCall section of the transfer definition.
transferDefinition.transferSet.postSourceCall: Returns the complete details of the postSourceCall section of the transfer definition.
transferDefinition.transferSet.preDestCall: Returns the complete details of the preDestCall section of the transfer definition.
transferDefinition.transferSet.postDestCall: Returns the complete details of the postDestCall section of the transfer definition.

name

Specifies the name of the resource monitor.

This query parameter is valid only when monitorName is not specified in the base resource URL.

By specifying the name of the resource monitor as an optional query parameter instead of in the base URL, you can query a wild carded resource monitor name, and can combine the query with the state and type query parameters.

The value can be any string value and * can be used as a wildcard character. Note that the ? character is not permitted.

agentName

Name of the agent that owns the resource monitor.

As resource monitors are agent scoped it is possible to have a resource monitor with the same name under more than one agent. In this situation, the REST API returns multiple resource monitor definitions. You can use the agentName query parameter to return the resource monitors that are associated with that specific agent.

For example, if a resource monitor with name MONITOR1 exists in more than one agent, the following URL returns more than one resource monitor definition:

https://localhost:9443/ibmmq/rest/v1/admin/mft/monitor/MONITOR1

Adding the agentName query parameter, you can return an agent specific resource monitor:

https://localhost:9443/ibmmq/rest/v1/admin/mft/monitor/MONITOR1?agentName=AGENT1

The value can be any string value and * can be used as a wildcard character. Note that the ? character is not permitted.

state

The status of the resource monitor.

This query parameter is valid only when monitorName is not specified in the base resource URL.

The value can be one of the following values:

started: Only monitors that are in a started state are returned.
stopped: Only monitors that are in a stopped state are returned.
all: All monitors, regardless of state, are returned.

The default value is all.

type

The type of the resource monitor.

This query parameter is valid only when monitorName is not specified in the base resource URL.

The value can be one of the following values:

directory: Only directory type monitors are returned.
queue: Only queue type monitors are returned.
all: All monitors, regardless of type, are returned.

The default value is all.

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

Resource monitor 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

Specified monitor not found.

405

Method not allowed.

Returned for any other request apart from GET.

500

Server issue or error code from IBM MQ.

503

Service unavailable. IBM MQ specific reason code is also returned.

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

Each element in the array is a JSON object that represents information about a resource monitor. Each of these JSON objects can contain the following objects and attributes. Which objects and attributes are returned depends on the URL that was specified for the request:

name

String.

Specifies the name of the resource monitor.

agentName

String.

Specifies the name of the agent that runs the resource monitor.

type

String.

Specifies the type of resource monitor:

directory: The type of the resource to be monitored is the file system directory.
queue: The type of the resource to be monitored is an IBM MQ queue.

state

String.

Specifies the state of the resource monitor:

started: The monitor is running.
stopped: The monitor has stopped.

resource

JSON Object.

Specifies the monitored resource, either a directory or queue.

userProperties

JSON Object.

Specifies a list of user defined custom data in key-value pair of type String. For example:

"userProperties":{"key1":"value1"}

This maps to a metadata attribute in resource monitor definition. An empty array is included in the response, if there are no user properties in the resource monitor configuration.

defaultVariables

JSON Object.

Specifies list of user defined variables and their values in key-value pair of type String. Resource monitor uses the values as a "variable substitution" while submitting the transfer request. For example:

"defaultVaraibles":{"groupId":"4F4F4FDEEDF1"}

general

JSON object.

Specifies other high-level attributes of the resource monitor.

triggerCondition

JSON object.

Specifies details of a trigger condition that is used by a resource monitor.

triggerFileContentFormat

JSON object.

Specifies a list of files that are transferred when a trigger condition is satisfied.

transferDefinition

JSON object.

Specifies details of a list of files to be transferred when a resource monitor trigger condition is satisfied.

This object includes the following nested objects:

job: JSON object.; Contains the user-defined job name for the transfer.
sourceAgent: JSON object.; Contains attributes that are related to the agent on the destination system.
destinationAgent: JSON object.; Contains attributes that are related to the agent on the destination system.
originator: JSON object.; Contains attributes that are related to the originator of the request.
transferSet: JSON object.; Contains attributes that are related to the group of file transfers.

For more information, see Response body attributes for list resource monitor.

If an error occurs, see REST API error handling.

Examples

The following example returns a default set of data for all resource monitors.

The following URL is used with the HTTP GET method:

https://localhost:9443/ibmmq/rest/v3/admin/mft/monitor

The following JSON response is returned:

{"monitor":[
   {   "name"":"DIRMONWILDCARD",
       "agentName":"SRCWILDCARD",
       "type":"directory",
       "state"":"started",
       "resource": {
          "name": "C:\\MFT"
       }
   },
   {   "name":"DIRMONREGEX",
	"agentName":"SRCDIRREG",
	"type":"directory",
	"state":"started",
       "resource": {
          "name": "C:\\MFT"
       }
   },
   {   "name":"DIRMONREGEXFILESIZECHANGE",
	"agentName":"SRCDIR",
	"type":"directory",
	"state":"started",
       "resource": {
          "name": "C:\\MFT"
       }
}]
}

The following example lists the default attributes for a specified resource monitor whose names is DIRMONWILDCARD. The following URL is used with the HTTP GET method:

https://localhost:9443/ibmmq/rest/v3/admin/mft/monitor/DIRMONWILDCARD

The following JSON response is returned:

{"monitor":[
   {   "name":"DIRMONWILDCARD",
	"agentName":"SRCWILDCARD",
	"type":"directory",
	"state":"started",
       "resource": {
            "name": "C:\\MFT"
       }
   }]
}

The following example lists the default attributes for all the resource monitors whose names begin with DIR. The following URL is used with the HTTP GET method:

https://localhost:9443/ibmmq/rest/v3/admin/mft/monitor?name=DIR*

The following JSON response is returned:

{"monitor":[
   {   "name":"DIRMONWILDCARD",
	"agentName":"SRCWILDCARD",
	"type":"directory",
	"state":"started",
       "resource": {
          "name": "C:\\MFT"
       }
   },
   {   "name":"DIRMONREGEX",
	"agentName":"SRCDIRREG",
	"type":"directory",
	"state":"started",
       "resource": {
          "name": "C:\\MFT"
       }
   },
   {   "name":"DIRMONREGEXFILESIZECHANGE",
	"agentName":"SRCDIR",
	"type":"directory",
	"state":"started",
       "resource": {
          "name": "C:\\MFT"
       }
   }]
}

The following example lists details for all the resource monitors whose type is directory and the state is stopped. The following URL is used with the HTTP GET method:

https://localhost:9443/ibmmq/rest/v3/admin/mft/monitor?type=directory&state=stopped

{"monitor": [
   {   "name":"TRIGCONTENTSCSTM",
	"type":"directory",
	"state":"stopped",
	"agentName":"TRIGCONTCSTM",
       "resource": {
          "name": "C:\\MFT"
       }
   }]
}