Agent File Monitor Task
Overview
The Agent File Monitor task allows you to monitor a specific remote machine for the creation, deletion, change, existence, or non-existence of one or more files at a specific location. In order to run an Agent File Monitor task, you need Universal Agent for Windows, Linux/Unix, or z/OS running on the machine where you are monitoring for the file.
Processing Flow for Agent File Monitors
Agent File Monitor tasks are meant to be launched either by using a Agent File Monitor trigger or by being included within a Workflow. However, there are no technical restrictions on how an Agent File Monitor task can be launched. The processing may differ depending on which of the following methods was used to launch it:
Launched by a Workflow
Launched by an Agent File Monitor trigger
Launched manually or by another trigger type
The processing on an Agent File Monitor task for each launching method is described below.
Note
Any changes made to an Agent File Monitor task are not recognized by its respective Triggers until those Triggers are disabled and re-enabled.
Launching an Agent File Monitor Task Within a Workflow
The Agent File Monitor task can be launched within a Workflow.
In this scenario, the task launches when the upstream workflow conditions are satisfied. Workflow processing then pauses until the conditions in the Agent File Monitor task are satisfied. If the Agent File Monitor is watching for the creation, change, or deletion of a file, the task goes to SUCCESS when the event occurs. If the Agent File Monitor is watching for the existence or non-existence of a file, the task immediately goes to SUCCESS or FAILURE. Subsequent processing depends on the conditions built into the Workflow.
The following diagram illustrates the processing for this scenario.
Launching an Agent File Monitor Task Using an Agent File Monitor Trigger
A common use for the Agent File Monitor task is to launch it using an Agent File Monitor trigger, which specifies one or more tasks that are launched when a condition(s) is satisfied.
In this scenario, the Agent File Monitor task launches when its associated Agent File Monitor trigger is enabled.
Note
You should use an Agent File Monitor trigger to launch only Agent File Monitor tasks that specify a single Agent, not an Agent Cluster. An Agent File Monitor trigger can launch only a single task, not multiple tasks, which would be the case if an Agent Cluster was specified.
This method is best geared toward watching for the creation, deletion, or change in files. When the conditions in the Agent File Monitor task are satisfied, the Agent File Monitor task goes to SUCCESS and the tasks listed in the associated trigger are launched. The Agent File Monitor task continues running until its conditions are satisfied or until the user disables the trigger.
If you use this method to check for the existence or non-existence of a file, as soon as the task is launched it goes to SUCCESS or FINISHED status. If it goes to SUCCESS, the tasks specified in the trigger are launched. A FINISHED status indicates that it found a file that should not be there or did not find a file that should be there. Both of these cases constitute a "failure" of the conditions and therefore the tasks in the trigger are not launched.
When the Agent File Monitor task goes to FINISHED or SUCCESS, the associated Agent File (Monitor) trigger is automatically disabled.
Note
Using an Agent File Monitor trigger to trigger an Agent File Monitor task that is monitoring for the creation of one or more files (Monitor Type = Exists) will disable the trigger. You should instead specify (Monitor Type = Create) and check Trigger on Existence.
When you launch an Agent File Monitor task from an Agent File Monitor trigger, you cannot manually cancel or force finish the task. You can only stop the task by disabling the trigger. If you manually disable the trigger while the task is still running, the task goes to FINISHED status.
The diagram below illustrates the processing flow for this scenario.
Launching an Agent File Monitor Task Manually or Via Other Trigger
If you manually launch an Agent File Monitor task or launch it using a non-Agent File Monitor trigger, such as a Time trigger, the task continues running until its specified conditions are met, at which time the task goes to SUCCESS. No other processing occurs unless you have configured notifications with the task or set up some other task(s) to launch based on the status of this task.
If the conditions are not met, the task runs perpetually or until a user issues a Cancel or Force Finish command against it.
Built-In Variables
The following built-in variables can be used in an Agent File Monitor task to pass data where appropriate:
Creating an Agent File Monitor Task
Step 1 | From the Automation Center navigation pane, select Agent File Monitor Tasks. The Agent File Monitor Tasks list displays a list of all currently defined Agent File Monitor tasks. |
|---|---|
Step 2 | Enter/select Details for a new Agent File Monitor task, using the field descriptions below as a guide.
To display more of the Details fields on the screen, you can either:
|
Step 3 | Click the button. The task is added to the database, and all buttons and tabs in the Task Details are enabled. |
Note
To open an existing record on the list, either:
Click a record in the list to display its record Details below the list. (To clear record Details below the list, click the New button that displays above and below the Details.)
Clicking the Details icon next to a record name in the list, or right-click a record in the list and then click Open in the Action menu that displays, to display a pop-up version of the record Details.
Right-click a record in the a list, or open a record and right-click in the record Details, and then click Open In Tab in the Action menu that displays, to display the record Details under a new tab on the record list page (see Record Details as Tabs).
Agent File Monitor Task Details
The following Agent File Monitor Task Details is for an existing Agent File Monitor task.
Depending on the values that you enter / select for these fields, and whether or not the Agent File Monitor task has ever been launched, more (or less) fields may display. See the field descriptions, below, for a description of all fields that may display in the Agent File Monitor Task Details.
Agent File Monitor Task Details Field Descriptions
The following table describes the fields, buttons, and tabs that display in the Agent File Monitor Task Details.
Field Name | Description |
|---|---|
General | This section contains general information about the task. |
Name | User-defined name of this task (Maximum = 255 alphanumeric characters); variables supported. It is the responsibility of the user to develop a workable naming scheme for tasks. |
Version | System-supplied; version number of the current record, which is incremented by the Controller every time a user updates a record. Click the Versions tab to view previous versions. For details, see Record Versioning. |
Description | Description of this record. Maximum length is 255 characters. |
Member of Business Services | User-defined; Allows you to select one or more Business Services that this record belongs to. (You also can Check All or Uncheck All Business Services for this record.) You can select up to 62 Business Services for any record type, and enter a maximum of 2048 characters for each Business Service. If the Business Service Visibility Restricted Universal Controller system property is set to true, depending on your assigned (or inherited) Permissions or Roles, Business Services available for selection may be restricted. |
Resolve Name Immediately | If enabled, the Instance Name of the task instance will be resolved immediately at trigger/launch time. |
Time Zone Preference | User-defined; Allows you to specify the time zone that will be applied to the task. Options:
|
Hold on Start |
If enabled, when the task is launched it appears in the Activity Monitor with a status of Held. The task runs when the user releases it. |
Hold Reason |
Information about why the task will be put on hold when it starts. |
Virtual Resource Priority | |
Virtual Resource Priority Variable | |
Hold Resources on Failure | |
Mutually Exclusive With Self | |
Simulate | |
Override Previous Instance Wait | |
Agent Details | This section contains assorted detailed information about the Agent / Agent Cluster selected for this task. |
Cluster | |
Agent | |
Agent Variable | |
Agent Cluster | |
Agent Cluster Variable | |
Broadcast | |
Cluster Broadcast | |
Cluster Broadcast Variable | |
Credentials | |
Credentials Variable | |
Agent File Monitor Details | This section contains assorted detailed information about the task. |
Monitor Type | |
Trigger on Existence | |
Trigger on Create | |
Monitor File(s) | |
Use Regular Expression | Enables the use of a regular expression in the Monitor File(s) field. |
Recursive | |
Maximum Files | |
File Owner | |
Stable (seconds) | |
By Percentage (+/-) | |
By Size (+/-) | |
By Scale | |
To Size | |
To Scale | |
Minimum File Size | |
Minimum File Scale | |
Scan Text | If Monitor Type = Change, Exists, or Create; Specifying a string means that only files containing the string constitute a match. The string will be processed as a regular expression. Not applicable for z/OS. Note For Linux/Unix Agents: If Monitor Type = Create, a value for Stable (seconds) must be specified. Maximum is 256 bytes. |
Scan Forward | |
Use Exit Code On Failed | |
Wait / Delay Options | This section contains specifications for waiting to start and/or delaying on start the task. |
Wait To Start | |
Wait Time | |
Wait Day Constraint | |
Wait Duration | |
Wait Duration In Seconds | |
Delay On Start | |
Delay Duration | |
Delay Duration In Seconds | |
Workflow Only | |
Time Options | This section contains time-related statistics for task instances of the task. |
Late Start | |
Late Start Type | |
Late Start Time | |
Late Start Day Constraint | |
Late Start Nth Amount | |
Late Start Duration | |
Late Finish | |
Late Finish Type | |
Late Finish Offset Type | |
Late Finish Percentage Offset ( + ) | |
Late Finish Duration Offset ( + ) | |
Late Finish Duration Offset Unit | |
Late Finish Time | |
Late Finish Day Constraint | |
Late Finish Nth Amount | |
Late Finish Duration | |
Early Finish | |
Early Finish Type | |
Early Finish Offset Type | |
Early Finish Percentage Offset ( - ) | |
Early Finish Duration Offset ( - ) | |
Early Finish Duration Offset Unit | |
Early Finish Time | |
Early Finish Day Constraint | |
Early Finish Nth Amount | |
Early Finish Duration | |
User Estimated Duration | |
Critical Path Options | This section contains Critical Path-related specifications for the task. |
CP Duration | |
CP Duration (Resolved) | |
CP Duration Unit | |
Workflow Execution Options | This section contains Execution Restriction specifications for the task if it is within a Workflow. |
Execution Restriction | |
Restriction Period | |
Before Date | |
Before Time | |
After Date | |
After Time | |
Date List | |
Self-Service Options | This section contains Self-Service specifications for the task. |
Enforce Variables | |
Lock Variables | |
Statistics | This section contains time-related statistics for task instances of the task. |
First Execution | |
Last Execution | |
Last Instance Duration | |
Lowest Instance Time | |
Average Instance Time | |
Highest Instance Time | |
Number of Instances | |
Metadata | This section contains Metadata information about this record. |
UUID | Universally Unique Identifier of this record. |
Updated By | Name of the user that last updated this record. |