Request body attributes for MFT resource monitors

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

• 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 we 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

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.

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

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

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.

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

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.

Parent topic: POST

Related reference

• /admin/mft/monitor

Related information

• Getting started with the REST API for MFT