Request body attributes for transfers with HTTP POST

When you create the request body for creating a transfer request with the administrative REST API for MFT, we can specify attributes for the transfer within named JSON objects. A number of objects and attributes are available.

The following objects are available:


job

The job object can contain the following attributes that relate to the transfer job:

    name
    String.
    Specifies a user-defined job name for the transfer.


sourceAgent

The sourceAgent object can contain the following attributes that relate to the source agent:

    name
    String.
    Specifies the name of the agent on the source system.
    This attribute is required.

    qmgrName
    String.
    Specifies the name of the queue manager on the source system.
    This attribute is required.


destinationAgent

The destinationAgent object can contain the following attributes that relate to the destination agent:

    name
    String.
    Specifies the name of the agent on the destination system.
    This attribute is required.

    qmgrName
    String.
    Specifies the name of the queue manager on the destination system.
    This attribute is required.


scheduleTransfer

The scheduleTransfer object can contain the following attributes that relate to a scheduled transfer:

    startTime
    String.
    Specifies the start time and date for the scheduled transfer in the format yyyy-MM-ddThh:mm or hh:mm. Specify the time by using the 24-hour clock.

    timeBase
    String.
    Specifies the time base for the start and end time of the scheduled file transfer.
    The value must be one of the following values:

      admin
      The start and end time for the scheduled transfer are based on the time and date of the system where the mqweb server is running.

      source
      The start and end time for the scheduled transfer are based on the time and date of the system where the source agent is located.

      utc
      The start and end time for the scheduled transfer are based on Coordinated Universal Time.

    occurrenceInterval
    String.
    Specifies the interval that the scheduled transfer occurs at.
    Use this attribute in conjunction with the startTime and occurrenceFrequency attributes.
    The value must be one of the following values:

    • minutes
    • hours
    • days
    • weeks
    • months
    • years

    occurrenceFrequency
    Integer.
    Specifies the frequency of a repeating scheduled transfer. Use this attribute in conjunction with the startTime and occurrenceInterval attributes.

    occurrenceCount
    Integer.
    Specifies the number of times that the scheduled transfer will occur.
    Use this attribute in conjunction with the startTime and occurrenceInterval attributes.
    This attribute can not be specified with the endTime attribute.

    endTime
    String.
    Specifies the time and date when a repeating scheduled transfer ends in format yyyy-MM-ddThh:mm or hh:mm. Specify the time by using the 24-hour clock.
    Use this attribute in conjunction with the startTime and occurrenceInterval attributes.
    This attribute can not be specified with the occurrenceCount attribute.


transferSet

The transferSet object can contain the following attributes that relate to the transfer:

    priority
    Integer.
    Specifies the priority assigned to the transfer request. The default value is zero.

    userProperties
    JSON object.
    Specifies user-defined metadata that is passed to exits run by the agents involved in the transfer.

    item
    JSON array.
    An array of JSON objects that describe the source and destination item configurations to transfer.

      source
      JSON object.
      A JSON object that contains attributes that relate to the source item to transfer.

        name
        String.
        Specifies the absolute path of the file, directory, data set, partitioned data set, or queue at the source end.
        This attribute is required.

        type
        String.
        Specifies the type of source.
        The value must be one of the following values:

          queue
          The source is an IBM MQ .

          file
          The source is a file.

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

        disposition
        String.
        Specifies the action that is taken on the source element when a source has successfully been transferred to its destination.
        The value must be one of the following values:

          leave
          The source files are left unchanged.

          delete
          The source files are deleted from the source system when they have been successfully transferred.

        encoding
        String
        Specifies which character encoding to use, to read the source file when performing character conversion. This option is only applicable to text files.
        The values can be any valid code page number.

        datasetExtended
        JSON object.
        A JSON object that contains additional source attributes, if the source is a z/OS sequential or partitioned data set.

          keepTrailingSpaces
          Boolean.
          Specifies whether trailing spaces are kept 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.
          If we do not specify this parameter, trailing spaces are stripped from source records.

          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.
          We must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. Separate multiple bytes with commas.

          delimiterPosition
          String
          Specifies the position to insert source record delimiters. This attribute is used in conjunction with the hexDelimiters attribute.
          The value must be 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
        JSON object.
        A JSON object that contains additional source attributes, if the source is an IBM MQ queue.

          messageGroup
          Boolean.
          Specifies whether 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.

          groupID
          String.
          Specifies the group ID to be used when getting messages from a queue.

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

          hexDelimiters
          String.
          Specifies one or more byte values to use, when appending multiple messages to a file.
          We must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. Separate multiple bytes with commas. For example x12 or x03,x7F.

          delimiterPosition
          String.
          Specifies where the delimiters are positioned in the message being put to the source queue.
          The value must be one of the following values:

            prefix
            The delimiters are inserted at the start of each message.

            postfix
            The delimiters are inserted at the end of each message; this is the default option.

          messageArrivalWaitTime
          Integer.
          Specifies the time in seconds to wait for the arrival of messages on the source queue.

      destination
      JSON object.
      A JSON object that contains attributes that relate to the destination item.

        name
        String.
        Specifies the absolute path of the file, directory, data set, partitioned data set, or queue at the destination.
        This attribute is required.

        type
        String.
        Specifies the type of destination.
        This attribute is required.
        The value must be one of the following values:

          queue
          The destination is an IBM MQ queue.

          file
          The destination is a file.

          directory
          The destination is a directory.

          sequentialDataset
          The destination is a z/OS sequential data set.

          partitionedDataset
          The destination is a z/OS partitioned data set.

        actionIfExists
        String.
        Specifies the action that is taken if a destination file, directory, or data set exists on the destination system.
        The value must be one of the following values:

          error
          An error is reported and the file is not transferred; this is the default value.

          overwrite
          The existing destination file is overwritten.

        encoding
        String.
        Specifies which character encoding to use to write the file at the destination. This option is only applicable to text files.
        The value can be any valid code page number.

        endOfLine
        String.
        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.
        The value must be one of the following values:

          LF
          Line feed.

          CRLF
          Carriage return followed by line feed.

        datasetExtended
        JSON object.
        A JSON object that contains additional destination attributes, if the destination is a z/OS data set.

          truncateRecords
          Boolean.
          Specifies whether destination records longer than the data set LRECL 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
        JSON object.
        A JSON object that contains additional destination attributes, if the destination is an IBM MQ queue.

          messagePersistence
          String.
          Specifies the persistence of the message put to the destination queue.
          The value must be one of the following values:

            persistent
            Messages are persistent.

            notPersistent
            Messages are not persistent.

            asQueue
            The message persistence is as set in the queue definition. This is the default value.

          delimiterType
          String.
          Specifies the type of delimiter to use when splitting a file into multiple messages.
          The value must be one of the following values:

            size
            Split based on a specified size.

            binary
            Split based on specified delimiters.

          hexDelimiters
          String.
          Specifies the hexadecimal delimiter to use when splitting a binary file into multiple messages.
          We must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. We can specify a sequence of hexadecimal bytes as a delimiter by specifying a comma-separated list of hexadecimal bytes. For example x12 or x03,x7F.

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

          includeDelimitersInMessage
          Boolean.
          Specifies whether delimiters are inserted in the message put to the destination queue.

          delimiterPosition
          String
          Specifies where the delimiters are positioned in the message put to the destination queue.
          The value must be one of the following values:

            prefix
            The delimiters are inserted at the beginning of the message body.

            postfix
            The delimiters are inserted at the end of the message body.

          setMQProperties
          Boolean.
          Specifies whether message properties are set on the first message that is created by the transfer.

          messageSize
          Integer.
          Specifies whether to split the file into multiple fixed-length messages of this size in bytes.

      checksum
      String.
      Specifies the checksum method for verifying data integrity.
      The value must be one of the following values:

        md5
        The MD5 algorithm is used for integrity validation.

        none
        No checksum validation.

      mode
      String.
      Specifies the transfer mode.
      The value must be one of the following values:

        text
        Data is transferred as text.

        binary
        Data is transferred in binary.
        This is the default value.

    recoveryTimeout
    Integer.
    Specifies the length of time during which a source agent attempts to recover a stalled file transfer.
    The value must be one of the following values:

      -1
      The agent continues to attempt to recover the stalled transfer until the transfer is complete.
      This is the default value.

      0
      The agent stops the file transfer as soon as it enters recovery.

      n
      The agent continues to attempt to recover the stalled transfer for the specified amount of time in seconds.
      The value must be in the range 1 - 999,999,999.

    preSourceCall
    JSON object.
    A JSON object that contains attributes that are related to the program to invoke at the source agent, before a transfer begins.

      type
      String.
      Specifies the type of the program to be invoked.
      The value must be one of the following values:

        executable
        A platform-specific executable is invoked. This is the default value.

        antScript
        An Apache Ant script is invoked.

        jcl
        A z/OS JCL job is submitted.

      executable
      JSON object.
      A JSON object that can contain attributes related to a platform-specific executable program to be invoked. This object can only be specified when the value of the type attribute is executable.

        name
        String.
        Specifies the name of the program to run.
        This attribute is required if the executable JSON object is specified.

        arguments
        String.
        Specifies arguments to be passed to the program that is invoked.

      antScript
      JSON object.
      A JSON object that can contain attributes related to an Apache Ant script to be invoked. This object can only be specified when the value of the type attribute is antScript.

        name
        String.
        Specifies the name of the Ant script to run.
        This attribute is required if the antScript JSON object is specified.

        target
        Specifies the target to invoke in the specified Ant script.
        If this attribute is not specified, the target named default is invoked.

        arguments
        String.
        Specifies a list of user-defined custom data in space separated key=value pairs.

      jcl
      JSON object.
      A JSON object that can contain attributes related to a z/OS JCL job to submit. This object can only be specified when the value of the type attribute is jcl.

        name
        String.
        Specifies the name of the JCL to submit.

      retryCount
      Integer.
      Specifies the number of attempts to run the command before ceasing.

      retryWait
      Integer.
      Specifies the amount of time to wait, in seconds, between retry attempts.

      successReturnCode
      String.
      Specifies the condition, based on the return code from the transfer, that must be true in order for the specified program, script, or JCL to be run.
      The condition is specified as an operator, followed by a value. Valid characters for the operator are >, <, ! and =. It is valid to have a combination of more than one operator. For example, ">= 40".
      The default value is zero.

    postSourceCall
    JSON object.
    A JSON object that contains attributes that are related to the program to invoke at the source agent, after a transfer completes.
    The attributes that can be specified are the same as for the preSourceCall object.

    preDestinationCall
    JSON object.
    A JSON object that contains attributes that are related to the program to invoke at the destination agent, before a transfer begins.
    The attributes that can be specified are the same as for the preSourceCall object.

    postDestinationCall
    JSON object.
    A JSON object that contains attributes that are related to the program to invoke at the destination agent, after a transfer completes.
    The attributes that can be specified are the same as for the preSourceCall object.

Parent topic: POST


Related information