File monitor tasks

You can use the file monitor tasks to create tasks that track changes in files. File monitor tasks can track changes in a single file or multiple files in HCL UnO agent installed in your local machine or mounted virtual machine.

Overview

All types of changes to a file such as create, modify and delete can be tracked using file monitor tasks. The file monitor tasks run until they detect a change or until a predefined time elapses, looking for a change. You can customize the attributes of the task definition to change the type of modification check. The file monitor tasks either wait for an event to happen or monitor the file at specified intervals looking for a change, before moving to SUCC status. The output log of the tasks contains the names of the files affected along with the type of event that occur.

The tasks can monitor a single file or all files in a folder or files in multiple folders. You can use wildcards to monitor multiple files or files in multiple folders. When the task runs for the first time, it stores the state of the file or files in the database and compares this state with the current state during subsequent runs. If a change is detected the task is moved to SUCC immediately or else the task runs till a change occurs or until the specified time elapses. This depends on how the task definition is configured and extends the functionality of the file monitor plug-in.

The file monitor tasks monitor the following types of events in a file:
  • create: The task monitors for the creation of a specific file or any new files.
  • modify: The task monitors for the changes in a specific file or multiple files.
  • delete: The task monitors for the deletion of a specific file or multiple files.
Each task can monitor only one type of event.
You need to add the specific attributes for file monitor with the mandatory attributes of the task definition to create a file monitor task. The specific attributes to create a file monitor task are as follows:
Attributes Description Mandatory option
Event You can specify any one of the following event types:
  • create
  • modify
  • delete
 Yes
file path

Specify the file path followed by the file name to monitor a specific file or else use wildcards to monitor multiple files in a single or multiple folders. You can use wildcards for folder also.

For example,

D:\Trial\folder\*
D:\Trial\fol*\abc.txt
 Yes
Minimum file size Specify a value in bytes that acts as the threshold for monitoring the files. Only the files that are either equal to or greater than this value are monitored. No
timeout (Monitoring time1) Specify a value in seconds to monitor the change in files. The files are monitored until this time period elapses. The monitoring time also depends on the value provided for Polling type. No
modificationCompletedTime (Monitoring post modification1) Specify a value in seconds to monitor the files only if a change is detected. If any change is detected, before the task moves to SUCC, it continues to monitor the file until this time elapses. This value cannot be greater than the specified timeout. You can add this attribute when the event type is either create or modify. No
exitOnPathToMonitorNotFound (Exit if the path to the monitoring file is not found1) If an invalid path is given for file path attribute, then the task is moved to ABEND status. No
outputFile (Output file path1) Specify a file path followed by a file name. After the task moves to SUCC, this file is updated with the names of all modified files. No
pollingType (Polling type1) This attribute determines the monitoring type for the task. You can select any one of the following options:
  • eventDriven: As the name suggests the task moves to SUCC immediately after an event, that is, after identifying a change in the file. The task does not monitor the file until the specified timeout elapses, instead moves to SUCC status immediately after detecting a change.

  • periodic: The file is monitored at specified intervals throughout the timeout period. You can configure this time interval by adding the polling attribute. The default value is five seconds.

    polling: Specify a value in seconds as time interval. You must specify a value lower than the timeout value for the polling attribute. The default value is five seconds.

    For periodic type, you can also monitor files that the current user does not have access to. In such scenarios, you must add the following attributes with the polling to create a valid task definition:
    • username: Specify a valid username with access to the file you monitor.
    • password: Specify the valid password for the username.

For more information, see Exploring file monitor task scenarios

 Yes
batch (Record all modified files1) Specify this option to log the names of all files in which the task detects a change. You can add this option and set the value to two double quotation marks "" in the task definition. If this option is not added only the name of the first modified file is recorded in the output. No

1 The attribute name in the UI.
Note: While configuring HCL UnO agent you can modify certain file monitor attributes.
  • If you want to restrict the tasks from monitoring any specific file paths, add those file paths, separated by comma, as values to the -bld or --blacklistedDir attribute.
  • You can modify the default value for the following attributes:
    • Add -fmt or --fileMonitorTimeout to modify timeout.
    • Add -fmp or --fileMonitorPolling to modify polling.
    • The status of files collected while monitoring is stored in the database. It is stored for a default period of 400 days. To update this default value, add the -fmr or --fileMonitor attribute while configuring the agent.
Important:
  • If you want to monitor a large number of files in multiple folders with frequent changes, it is recommended to use the periodic polling type.
  • In Windows operating system, when you delete a file and create a new file within a short time, the newly created file has the deleted file's time in the Date created column instead of the current time. To monitor such changes with the create event type, ensure that the new files are created sometime after the deletion of files and they have the current time in Date created column.
  • Modifying multiple files simultaneously or subsequently within a short time can result in changes not being captured in order. In such scenarios, if the polling type is eventDriven, then the output log does not show the first file that is modified.

Exploring file monitor task scenarios

The behaviour of file monitor tasks varies based on the Polling type attribute in the definition. The combination of Polling type attribute with the batch attribute in the task definition constitute different scenarios.
  • eventDriven

    When the task is run for the first time with or without the batch attribute, the task returns with the first changed file even if multiple files are affected. As soon as an event is detected, the task moves to SUCC status.

    If some files change before rerun, when rerun, the task immediately moves to SUCC status. This is because when the task runs initially the state of the file is already stored in the database. During rerun, this state is compared with the current state, and by detecting the changes that occur before rerun, the task moves to SUCC status.

    If batch attribute is added and multiple files change before rerun, then all the file names are displayed in the output. For eventDriven, this is the only scenario were multiple files are recorded if batch attribute is added in the definition. In all other scenarios, only the first changed file is displayed in the output.

    In all the above scenarios, if you add the modificationCompletedTime in the task definition, then the task waits until it elapses before moving to SUCC status.

  • periodic

    The task monitors for changes at specified intervals during the first run and rerun.

    If some files change before rerun, the behaviour is same as explained for eventDriven. When rerun, the task immediately moves to SUCC status. If the batch attribute is added in the definition and multiple files change before rerun, then all the file names are displayed in the output. If not, only one file is displayed in the output. This file selection is based on the alphabetical order of file names.

    If no files change before rerun, the task monitors for changes at specified intervals like the first run. If the batch attribute is added and multiple files change during rerun, then all the file names are displayed in the output. If not added, then only one file is displayed in the output. This file selection is based on the alphabetical order of file names.

    In all the above scenarios, if you add the modificationCompletedTime, then the task waits until it elapses, before moving to SUCC status.