POST

Use the HTTP POST method with the monitor resource to create a resource monitor.

Note: Set the command queue manger in the configuration before issuing any MFT Create Monitor or Transfer REST API command. See Configure the REST API for MFT for more information.

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

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.

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

Request body format

The request body must be in JSON format in UTF-8 encoding. Attributes marked required are mandatory, and if we do not provide values for the other parameters in the request body, the default values are used.

name: JSON string.; Contains the name of the resource monitor.; The name is not case sensitive - lower case characters are folded to upper case characters, and we cannot use the wildcard character (*).; The name is required.
type: JSON string.; Type of the resource to be monitored.
general: JSON object.; This JSON object contains details of the poll interval, the units of the poll interval, and the matches per task.
resource: JSON object.; This JSON object contains details of the resource, that is the name for both monitoring a queue and a directory, and for a directory resource the recursion level.; The name attributes in this object are required.
triggerCondition: JSON object.; This JSON object contains the type attribute and various other attribute depending upon whether the resource type is a directory or a queue. See Request body attributes for MFT resource monitors for details of this attribute.; The type attributes in this object are required.
userProperties: JSON object.; Specifies the user-defined metadata that is passed to the exit points of the monitor. The parameter can take one or more name pairs that are separated by commas. Each name pair consists of a name=value.
transferDefinition: JSON object.; Contains details about the transfer, for example, source agent and queue manager, destination agent and queue manager, and so on. See Request body attributes for MFT resource monitors for details of this attribute.

Request body attributes for MFT resource monitors lists all the attributes.

Security requirements

The caller must be authenticated to the mqweb server and must be a member of the MFTWebAdmin or MFTWebUser 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 Use token-based authentication with the REST API.

If we have set up a user sandbox, and MFT authority checking , or MFT authority checking, is turned on, we need to grant an additional authority for the user that started the WebSphere Liberty server to access the specified file system location.

For the MFTWebAdmin role, transfer requests are submitted under the context of the user that started the Liberty server. To distinguish between different principals of the MFTWebAdmin role, and for audit purposes, the transfer request submitted contains the name of the authorized Liberty profile user as the transfer originator. This method ensures that there is a record of who initiated the transfer request.

For example, if the user mftadminusr, of the MFTWebAdmin role, initiates a transfer with this login, the originator data in the xml has mftadminusr:

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

For the MQWebUser role support, the principal logged onto the Liberty profile requires the following authority. If the command queue is:

Local, grant PUT authority to the command queue.
Remote, that is, when the command queue manager and source agent queue manager are different, grant PUT authority to the transmission queue.

Notes:

If the Principal name with an effective MQWebUser role is longer than 12 characters, the request fails with a 403 return code.
If the Principal is configured to have multiple roles, only one role applies when determining behavior, and that role is determined by the Principal having the highest privileges applicable to the requested REST API operation.

If security is disabled on the Liberty profile, the transfer request submitted contains the name "UNAUTHENTICATED" user as the transfer originator.

Response status codes

202: The create monitor request has been accepted by the mqweb server. It might still get rejected by the MFT agent.
400: Invalid or unknown data provided to create resource monitor.; For example, invalid attributes specified.
401: Not authenticated.; The user must be authenticated to the mqweb server. See Security requirements for more information.; The ibm-mq-rest-csrf-token header must also be specified.
403: 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 all, or a subset, of the required IBM MQ or MFT resources.
500: Server issue, or error code from IBM MQ or MFT.

Response headers

The following header is returned with the response:

location: If the request is successfully submitted, the location attribute in the response header is updated with the url, through which details about the resource monitor can be further queried.

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

The following example creates a resource monitor for monitoring a directory:

{
       "name": "DIRMONREGEX",
	"type": "directory",
       "general": {"pollingInterval": 1, "pollingIntervalUnit": "minutes","matchesPerTask": 5 },
       "userProperties": {"companyName": "IBM", "unit": "ISL" },
        "resource": { "name": "/MFT/TRIGGER", "recursionLevel": 2 },      
                      "triggerCondition": { "excludePattern": "*.xls","includePattern": "*.txt","type": "matchAll 
},
        “transferDefinition” { 
             "sourceAgent": { "qmgrName": "srcQmgr", "name": "SRC" },	
              "destinationAgent": {"qmgrName": "desQmgr", “name": "DES" },
              "transferSet": { 
                 "item": [ 
                   { "source”: { "name": "C:\src\test.txt","type": "file" },
                         "destination": {"name": "C:\dst\test.txt","type": "file" } } ],
                   "userProperties": { "ARCHIVE_PATH": "C:\\MFT\\ARCHIVE", 
                                       "REJECT_PATH": "C:\\MFT\\REJECT" },
                   "postSourceCall": { "name": "posttransfersource.exe", 
                                       "executable":{"arguments": "data1 data2"} ),
                   "postDestinationCall": { "name": "posttransferdest.exe", 
                             "executable":{"arguments": "dataDest1 dataDest2" } },},
                   "preDestinationCall": { "name": "pretransferdest.exe"},
                   "preSourceCall": { "name":"posttransferdest.exe", 
                                      "executable" : { "arguments": "predata1 predata2"} },
                   "priority": 0,
                   "recoveryTimeout": 21600   }  }

}

The following example creates a resource monitor for monitoring a queue:

{    "name": "QMON", "type": "queue", 
     “general”:{ "pollingInterval": 1 "pollingIntervalUnit": "minutes","matchesPerTask": 5 },
     "triggerCondition": { "excludePattern": "*.xls","includePattern": "*.txt","type": "matchAll },
     "userProperties ": { "companyName": "IBM", "unit": "ISL" },
     "resource": { "name": "MSGQ", "matchCondition": "containsMessages" },
     " transferDefinition ": {
         "job": {"name": "testJob" },
         "sourceAgent": {"name": "SRC","qmgrName": "srcQmgr"},
         "destinationAgent": {"name": "DES","qmgrName": "desQmgr"},
         "transferSet": {
             "item": [ {
                "source":{"name": "C:\temp\src\test.txt","type": "file",
                          "recursive": false "disposition": "leave"},
                "destination":{"name": "LQ@NYQMGR ", "type": "queue",
                               "actionIfExists": "error", "delimiterType":"size",
                               "messagePersistence":"persistent"
                               “queueExtended” :{ “messageSize”=4, “setMQProperties”=”false” },
               "priority": 1, "recoveryTimeout":"-1","checksum": "md5", "mode":"text" } ] }  }

The following example creates a resource monitor for monitoring a directory with more attributes:

{
   "name": "DIRMONREGEX", "type": "directory","agentName": "SRC",
   “general”: { "pollingInterval": 1, "pollingIntervalUnit": "minutes","matchesPerTask": 5},
   “userProperties” : {"companyName": "IBM", "unit": "ISL" },
   "resource": { "name": "/MFT/TRIGGER","recursionLevel": 2 },
   “triggerCondition”: { "matchPattern": " [a-zA-Z]{3}", "excludePattern": " [d-fD-F]{3}",
                         "patternType": "regularExpression", 
                         "matchCondition": {"matchNoSizeChangeInterval": 5 } },
   "transferDefinition": { 
       "sourceAgent": { "name": "SRC”, "qmgrName": "srcQmgr" },
       "destinationAgent": { "name": "NY.AGENT","qmgrName": "NYQMGR" },
  "transferSet": {
     "item": [ { "source": {"name": "C:\temp\src\source.exe","type": "file" },
                 “destination” : {"name": "C:\temp\dst","type": "file"},
                  “mode”: “binary” } ] } }
}

The following example creates a resource monitor, demonstrating variable substitution functionality:

{  "name":
"VARSUB-TEST", "type": "directory", "agentName":"SRC",
  "general": { "pollInterval": 1, "pollIntervalUnit": "minutes"},
  "resource":{"name":"c\\source_dir"},
  "triggerCondition": { "excludePattern": "*.exe", "includePattern": "*.txt", 
                         "matchPattern": "wildcard","type": "matchAll" },
  "transferDefinition": {
      "job": {"name": "varSub"},
      "sourceAgent": { "name": "SRC", "qmgrName": "gandhi"},
      "destinationAgent": { "name": "DES", "qmgrName": "gandhi","actionIfExists":"overwrite"},
      "transferSet": { "item": [ {
          "destination": {"name": "C:\\dest\\${fileName}","type": "directory"},
          "source": {"name": "C:\\source_dir\\file.txt","type": "file"},
          "mode":"text"}] } }
                     
}

Request body attributes for MFT resource monitors
The Create Monitor REST API takes the input attributes as JSON objects.

Parent topic: /admin/mft/monitor

Related reference

Request body attributes for MFT resource monitors

Related information

Getting started with the REST API for MFT