GET

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

Note: We must set a coordination queue manager before we can use the monitor resource. For more information, see Configure the REST API for MFT.

For more information about configuring the MFT REST service, see Configure 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/monitor/{monitorName}

monitorName: Optionally specifies the name of the monitor to query.; If we do not specify a monitor name, a list of monitors is returned.; 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.

We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure the HTTP and HTTPS ports.

Optional query parameters

attributes

Specifies a comma-separated list of attributes to retrieve.

If we 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.

We cannot request the same attribute multiple times.

We can specify an asterisk, *, to specify that all attributes are returned.

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

We cannot have more than three levels of nesting. For example, we cannot directly query the transferDefinition.transferSet.postDestCall.retryWait, only the transferDefinition.transferSet.postDestCall. Therefore, when querying the transferDefinition, we 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, we 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, we 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 we are using basic authentication. For more information, see Use 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 MQWebUser role requires Principal authority, and that principal requires subscribe authority to the relevant topic, that is SYSTEM.FTE/Monitor. The operation succeeds only if the principal of the MQWebUser role has authority to subscribed 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 Use 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. See Security requirements for more information.
403: 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 or MFTWebAdminRO roles. See Security requirements for more information.
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/v2/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/v2/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/v2/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/v2/admin/mft/monitor?type=directory&state=stopped

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

Response body attributes for list resource monitor
When we use the HTTP GET method with the monitor object to request information about resource monitors, the following attributes are returned within named JSON objects.

Parent topic: /admin/mft/monitor

Related reference

Response body attributes for list resource monitor