Request body attributes for MFT resource monitors

The Create Monitor REST API takes the input attributes as JSON objects.

The following list shows the attributes that you need to be provide to a REST call:

name
type
general
resource
transferDefinition
triggerCondition

name: String.; A unique name for the resource monitor or queue.; The name is not case sensitive - lower case characters are folded to upper case characters, and you cannot use the wildcard character (*).; The name attribute is required.

type

String.

Type of the resource monitor

The value is one of the following values:

directory: Type of the resource to create is a file system directory.
queue: Type of the resource to create is an IBM® MQ queue.

general

Group element that defines the basic attributes of the monitor.

pollInterval: Integer.; Frequency, in units of time, at which a monitor polls a resource.; The default value is 1.
pollIntervalUnit: String.; Specifies the time interval for the pollInterval attribute. Possible values are seconds, minutes, hours, days.; The default value is minutes.
matchesPerTask: Integer.; Maximum of trigger matches to include in a single task.; The default value is 2.

resource

Group element that defines the details about the resource to be monitored.

The name attribute in this object is always returned.

name: String.; Specifies the name or the resource to be monitored. It can be absolute path of a file or directory, or the name of a queue.
recursionLevel: Integer.; Specifies the level in the directory structure that needs to be monitored.; The default value is 1.
Note: This attribute is valid only for a directory type of resource monitor.

transferDefinition

This attribute contains details for the transfer, which is initiated when the trigger condition is satisfied.

destinationAgent

Group element containing elements that define a destination agent.

The name and the qmgrName attributes in this object are always returned.

qmgrName: String.; The name of the queue manager on the destination system.
name: String.; The name of the agent on the destination system.

job

Contains the name of the transfer job:

name: String.; User defined job name for the transfer.

sourceAgent

Group element containing elements that define a source agent.

The name and the qmgrName attributes in this object are always returned.

qmgrName: String.; The name of the queue manager on the source system.
name: String.; The name of the agent on the source system.

transferSet

Group element that contains the elements specifying a transfer request.

The item attribute in this object is always returned.

priority

Number (optional).

Priority assigned to the transfer request with zero being the default, if no value is set.

userProperties

Object (optional).

User defined properties specified in the transfer request.

item

Object.

Array of group elements that describes the source and destination item configuration to transfer.

source

Object.

Group element that contains the attributes of a source item.

The name and type attributes in this object are always returned.

name

String.

Specifies the absolute path of the file, directory, data set, partitioned data set, or queue at source end.

type

String.

The type of source. The value is one of the following values:

queue: Specifies an IBM MQ queue as the source.
file: Specifies a file as the source.
directory: Specifies a directory as the source.
sequentialDataset: Specifies a z/OS® sequential data set as the source.
partitionedDataset: Specifies a z/OS partitioned data set as the source.

recursive

Boolean (optional).

Specifies that files are transferred recursively in subdirectories when the source element is a directory, or contains wildcard characters.

disposition

String (optional).

Specifies the action that is taken on the source element when a source has successfully been transferred to its destination. possible values are:

leave: The source files are left unchanged.
delete: The source files are deleted from the source system after the source file is successfully transferred.

encoding

String (optional)

Specifies which character encoding to use, to read the source file when performing character conversion. This option is only applicable to text files and the possible value is any valid code page number.

datasetExtended

Object (optional).

Group element that defines additional attributes of the source specification, if the source is a z/OS data set in a transfer request.

The hexDelimiters and delimiterPosition attributes in this object are always returned.

keepTrailingSpaces

Boolean (optional).

Describes the action that is taken if there are trailing spaces in the source records that are read from a fixed-length-format record-oriented file (for example, a z/OS data set) as part of a text mode transfer.

hexDelimiters

String.

For source files that are record oriented (for example, z/OS data sets), specifies one or more byte values to insert as the delimiter when appending records into a binary file. Each value is represented as two hexadecimal digits in the range 00-FF, prefixed by x.

delimiterPosition

String

Specifies the position of insertion for source text and binary delimiters. The value is one of the following values:

prefix: The delimiters are inserted at the start of each record.
postfix: The delimiters are inserted at the end of each record; this is the default option.

queueExtended

Object (optional).

Group element that defines additional attributes of a source specification, if the source is an IBM MQ queue in a transfer request.

The useMessageGroup and grouplD attributes in this object are always returned.

useMessageGroup

Boolean.

Specifies that the messages are grouped by IBM MQ group ID. The first complete group is written to the destination file. If this parameter is not specified, all messages on the source queue are written to the destination file.

grouplD

String.

Group ID to be used when getting messages from a queue.

textDelimiters

String (optional).

Specifies a sequence of text to insert as the delimiter, when appending multiple messages to a text file.

hexDelimiters

String (optional).

Comma separated string of hexadecimal bytes to use, when appending multiple messages to a file. For example x12 or x03,x7F.

delimiterPosition

String (optional).

Defines where the delimiters are positioned in the message being put to the source queue. The value is one of the following values:

prefix: Before the beginning of the message body.
postfix: After the end of the message body; this is the default option.

messageArrivalWaitTime

Integer.

Time in seconds, to wait for arrival of messages in the source queue.

destination

Object.

Group element that contains the attributes of a destination item.

The name and type attributes in this object are always returned.

name

String.

Specifies the absolute path of the file, directory, data set, partitioned data set, or queue at the destination end.

type

String.

The type of destination. The value is one of the following values:

queue: Specifies an IBM MQ queue as the destination.
file: Specifies a file as the destination.
directory: Specifies a directory as the destination.
sequentialDataset: Specifies a z/OS sequential data set as the destination.
partitionedDataset: Specifies a z/OS partitioned data set as the destination.

actionIfExists

String(optional).

Specifies the action that is taken if a destination file exists on the destination system. The value is one of the following values:

error: Reports an error and the file is not transferred; this is the default value.
overwrite: Overwrites the existing destination file.

encoding

String (optional).

endOfLine

String (optional).

Specifies the end-of-line characters that are used when the file is written at the destination. This option is applicable to text files only.

userId

String (optional).

The name of the user, whose destination file space the files are transferred into.

datasetExtended

Object (optional).

Group element that defines additional attributes of the destination specification, if the destination is a z/OS data set in a transfer request.

truncateRecords: Boolean.; Specifies that destination records longer than the LRECL data set attribute are truncated. If this parameter is not specified, the records are wrapped. This parameter is valid only for text mode transfers where the destination is a data set.

queueExtended

Object (optional).

Group element that defines additional attributes of a destination specification, if the destination is an IBM MQ queue in a transfer request.

The messagePersistence and delimiterType attributes in this object are always returned.

messagePersistence

String.

Defines if the message put to the destination queue is persistent or non-persistent. The value is one of the following values:

persistent: Messages are persistent.
nonPersistent: Messages are non-persistent.
asQueueDefault: Message persistency is set, depending on the queue definition.

delimiterType

String.

Defines the type of delimiter to use when splitting incoming data into messages. The value is one of the following values:

size: Split based on given size.
binary: Split based on given delimiters.

hexDelimiters

String (optional).

Comma separated string of hexadecimal bytes to use when splitting messages. For example x12 or x03,x7F.

textDelimiters

String (optional).

Specifies the Java regular expression to use, when splitting a text file into multiple messages.

includeDelimitersInMessage

Boolean.

Defines whether delimiters are included in a message being put to the destination queue.

delimiterPosition

String

Defines where the delimiters are positioned in the message being put to the destination queue. The value is one of the following values:

prefix: Before the beginning of the message body.
postfix: After the end of the message body; this is the default option.

setMQProperties

Boolean (optional).

Valid only when the destination is a queue. The value is one of the following values:

true: Sets message properties on the first message that is created by the transfer.
false: Does not set message properties on the first message that is created by the transfer.

messageSize

Number.

Defines a size in bytes to split the incoming data into the message.

checksum

String (optional).

Checksum method for verifying data integrity. The value is one of the following values:

md5: MD5 algorithm used for integrity validation.
none: No checksum validation.

mode

String (optional).

Specifies the transfer mode as either binary or text. The value is one of the following values:

text: Data is transferred as text.
binary: Data is transferred in binary.

recoveryTimeout

Number (optional).

Time in seconds to wait for a transfer to recover, with -1 being the default if no value is set.

preSourceCall

Object (optional).

Group elements that contain the elements for program invocation before a transfer begins at the source.

These group elements are not present if a resource monitor is not configured to use any program invocation.

type

String (optional).

Defines the type of the program to be invoked. The value is one of the following values:

executable

This value is the default value.

Defines attributes for a platform specific executable program:

name: String.; Name of the program to process.
arguments: String (optional).; Argument or arguments to be passed to the program being invoked.

antScript

Defines attributes for Ant Script:

name

String.

Name of the Ant script to process.

target

String (optional)

Target to invoke in the specified Ant script. Attribute is not present in the JSON response, if the default target is to be invoked.

arguments

String (optional).

A list of user defined custom data in space separated key=value pair of type String. For example:

"arguments":"coffeeType=Arabica teaChoice=lemon"

jcl

Defines attributes for z/OS JCL to submit.

name: String.; Name of the JCL to submit.

retryCount

Number (optional).

A positive number of attempts to run the command before ceasing.

retryWait

Number (optional).

Amount of time to wait, in seconds, between two retry attempts.

successReturnCode

String (optional).

Reason code that is returned when transfer is complete. This is looked for before running the specified program, script, or JCL. This return code is a combination of an operator and value in the form of "[>|<|!] value". Note that it is valid to have a combination of more than one operator, for example ">= 40".

postSourceCall

Object (optional).

Group elements that contain the elements for program invocation after a transfer completes at source. This object contains the same elements as preSourceCall.

preDestinationCall

Object (optional).

Group elements that contain the elements for program invocation before a transfer begins at the destination. This object contains the same elements as preSourceCall.

postDestinationCall

Object (optional).

Group elements that contain the elements for program invocation after a transfer completes at the destination. This object contains the same elements as preSourceCall.

triggerCondition

Group element that defines details of a trigger condition used by a resource monitor.

type

String.

Indicates the type of matching done, to decide on triggering a transfer. Possible values are:

For resource type Directory:

matchAll: Must match the value specified for the includePattern and excludePattern attributes.
matchNone: None of the files in the monitored directory match the value specified for the includePattern and excludePattern attributes.
noChangeInSize: Initiate a transfer, if the size of the file being monitored does not change for a specified number of poll intervals.
sizeGreaterOrEqualTo: Initiate a transfer, if the size of the file being monitored is greater than or equal to a specified size.

For resource type Queue:

queueNotEmpty: Queue must have at least one message.
completeMessageGroups: Queue must have at least one group of messages.

noFileSizeChangePollCount

Number.

Refers to the number of polling intervals during which the size of the monitored file does not change. Used in conjunction with the noChangeInSize attribute

fileSize

Number.

Refers to the size of the trigger file being monitored, whose size is equal to or greater. Used in conjunction with the sizeGreaterOrEqualTo attribute.

fileSizeUnit

String

Defines the unit for the fileSize attribute. The value is one of the following values:

bytes: File size unit is in bytes
kilobytes: File size unit is in kilobytes
megabytes: File size unit is in megabytes
gigabytes: File size unit is in gigabytes

includePattern

String.

A pattern of the name, or names, of files to be included, while doing match for a trigger condition.

excludePattern

String.

A pattern of the name, or names, of files to be excluded, while doing match for a trigger condition.

matchPattern

String.

Indicates how to interpret the contents of the includePattern and excludePattern attributes. The value is one of the following values:

wildcard: - Indicates the includePattern and excludePattern attributes contain wildcard characters, for example, *.
regularExpression: Indicates the includePattern and excludePattern attributes contain Java regular expressions.