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 Tasks > 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 | |
Version | |
Description | |
Member of Business Services | |
Resolve Name Immediately | |
Time Zone Preference | |
Hold on Start | |
Hold Reason | |
Virtual Resource Priority | |
Hold Resources on Failure | |
Mutually Exclusive With Self | |
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 | |
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 | |
Scan Forward | |
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 | |
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. |
Updated | Date and time that this record was last updated. |
Created By | Name of the user that created this record. |
Created | Date and time that this record was created. |
Buttons | This section identifies the buttons displayed above and below the Task Details that let you perform various actions. |
Save | Saves a new task record in the Controller database. |
Save & New | Saves a new record in the Controller database and redisplays empty Details so that you can create another new record. |
Save & View | Saves a new record in the Controller database and continues to display that record. |
New | Displays empty (except for default values) Details for creating a new task. |
Update |