Use a trigger file

We can use the contents of a trigger file in a resource monitor to define a set of files to transfer in a single transfer request. Each time a matching trigger file is detected, its contents are parsed for source file paths and optionally for destination file paths. These file paths are then used to define file items in the task transfer XML file that you specify, which is submitted as single transfer request to the agent. The definition of the resource monitor determines whether trigger content is enabled.

We can enable file content triggering when you create a monitor by specifying the -tc (trigger content) parameter. This -tc parameter applies only to the file trigger options match and noSizeChange. For more information about creating a monitor, see fteCreateMonitor: create an MFT resource monitor.

The format of each trigger file is a single file path to transfer on each line of text. The default format for the line is either a single source file path or a source and destination file path separated by a comma. White space characters are handled as part of the file path.

After a trigger file is parsed, a list of file paths is generated and applied to the transfer task XML that you specified. As with all monitors, the format of the transfer task XML is a complete transfer task XML generated by the fteCreateTransfer command with a single item or file defined. The single item must use the substitution variables ${contentSource}, and optionally ${contentDestination}, as replacements for the source and destination file paths. The monitor expands the transfer task XML to include a file item for each line (file path) in the trigger file.

We cannot use file content triggering with the -bs parameter because the -tc parameter implies one transfer request for each trigger file.

Example

The following example defines a monitor to trigger on a file that ends in trig and reads the file paths in that file.

fteCreateTransfer -gt task.xml -sa SrcAgent -da DestAgent -dd /file/destdir ${contentSource}
fteCreateMonitor -mn TrigMonitor -md /home/trigdir -mt task.xml -ma SrcAgent -tr "match,*.trig" -tc

The fteCreateTransfer command creates a file that is called task.xml for a single file with a source file path of ${sourceContent}. For example:

<item checksumMethod="MD5" mode="binary">
    <source disposition="leave" recursive="false">
          <file>${contentSource}</file>
    </source>
</item>

The fteCreateMonitor command scans for files that end in trig in the /home/trigdir directory and uses the contents to create a single transfer request that is based on the task.xml for all paths in that trigger file. The format of the trigger file must be one file path (source only) on each line with no comma separator. For example:

/home/file/first.txt
/home/file/second.txt
/home/different/third.txt
⋮

All files are delivered to the /file/destdir directory with its file name and not its file path, that is, /home/file/first.txt is delivered to /file/destdir/first.txt. Alternatively, if you change the -dd /file/destdir parameter in the fteCreateTransfer command to -df ${contentDestination} and the format of the content of a trigger file to source file path,destination file path, we can define different destination paths for the same destination agent. For example:

/home/file/first.txt,/home/other/sixth.txt

The destination location then becomes /home/other/sixth.txt.

The substitution variables can be tokenized. For example, we can separate the file name part from the provided path using ${contenDestination{token=-1}}. Therefore, if the fteCreateTransfer destination is defined as -df /file/destdir/${contentDestinstion{token=-1}}, the new destination for /home/file/first.txt is /file/destdir/sixth.txt.

Advanced options

We can change the default line format for the content of the trigger file by using the -tcr regex parameter. Supply a regular expression that matches the required line format and supplies either one or two capture groups. The first capture group is the source and the second, optional, capture group is the destination. For example:

The source and destination path are separated by a hyphen:
```
((?:[^-])+)-((?:[^-])+)
```
In this example, the separator is defined in three locations and all three instances of the hyphen, -, can be changed to any character. Ensure that you escape any special characters.
The source and destination paths are separated by a comma with trailing spaces. Comments that are indicated by a number sign (#) are ignored.
```
((?:[^,])+),((?:[^,])+) *(?:#.*)+
```
File paths cannot contain the number sign (#). Typically an entry is as follows: /home/source/from.txt,/home/destination/to.txt # some comment.

If we use the -tcr parameter, ensure that the regular expression is well designed and tested so that the expression can detect errors and correctly parse the trigger files.

You can reverse the order of the capture by using the -tcc destSrc parameter. If you specify this parameter, the first capture group is the destination file path and the second group is the source file path.

How errors are handled

Empty trigger file: If the trigger file is empty, the outcome is no file transfer. That is, the monitor creates a transfer request but no file items are specified.
Trigger file with errors: If any entry in a trigger file fails to parse against the expected format, no transfer request is generated. A monitor error log is published and the error is also logged in the event log. The trigger file is marked as processed and the monitor does not attempt to process the file again until the file has been updated.
Mismatching transfer task XML: The transfer task XML must match the trigger file, that is if the transfer task XML has both ${sourceContent} and ${destinationContent}, all trigger files for that monitor must have source and destination file paths and similarly for the reverse. In the first case the monitor reports a substitution failure of the ${destinationContent} if the trigger file supplies the source file path only.

Examples

The following example is a basic content trigger where the contents of a trigger file has a source file path only:

fteCreateTransfer -gt task.xml -sa SrcAgent -da DestAgent -dd /file/destdir ${sourceContent}
fteCreateMonitor -mn TrigMonitor -md /home/trigdir -mt task.xml -ma SrcAgent -tr "match,*.trig" -tc

A trigger file with reversed file paths (destination then source) and a separator of comma ",".

fteCreateTransfer -gt task.xml -sa SrcAgent -da DestAgent -df ${destinationContent} ${sourceContent}
fteCreateMonitor -mn TrigMonitor -md /home/trigdir -mt task.xml -ma SrcAgent -tr "match,*.trig" -tc -tcc destSrc

The -tcr parameter defines two capture groups of a sequence of any characters that are separated by a space character. The -tcc destSrc parameter and option indicate that the capture groups are to be processed as destination then source.

fteCreateTransfer -gt task.xml -sa SrcAgent -da DestAgent -df ${destinationContent} ${sourceContent}
fteCreateMonitor -mn TrigMonitor -md /home/trigdir -mt task.xml -ma SrcAgent -tr "match,*.trig" -tc 
    -tcr "((?:[^ ])+) ((?:[^ ])+)" -tcc destSrc