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. To the right of list, Agent File Monitor Task Details for a new Agent File Monitor task displays.
Step 2	Enter/select Details for a new Agent File Monitor task, using the field descriptions below as a guide. Required fields display an asterisk ( * ) after the field name. Default values for fields, if available, display automatically. To display more of the Details fields on the screen, you can either: Use the scroll bar. Temporarily hide the list above the Details. Click the button above the list to display a pop-up version of the Details.
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: – System Default – Time zone is based on the value of the Task Time Zone Preference Universal Controller system property: Server or Inherited. Server (xxx) Where (xxx) is the time zone ID of the server; time zone is evaluated in the time zone of the server. Inherited Time zone is evaluated in the time zone of the Parent Workflow or Trigger / Launch specification in the case there is no Parent Workflow.
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	Priority for acquiring a resource when two or more tasks are waiting for the resource. This priority applies to all resources required by the task. Options: 1 (high) - 100 (low). Default is 10.
Hold Resources on Failure	If enabled, the task instance will continue to hold Renewable resources if the task instance fails. Renewable resources will be returned only if the task instance status is either Complete, Finished, or Skipped.
Mutually Exclusive With Self	If enabled, the task will not be allowed to run concurrently with itself. Task will not start until the instance that is running finishes. An instance will transition to Exclusive Wait status if it cannot start due to another instance already running.
Simulate	Specifies if the instance should execute under simulation mode.
Override Previous Instance Wait	Specifies whether or not to override the parent workflow's Previous Instance Wait configuration. This option only applies for an instance running within a workflow. Options: No Behavior determined by the parent workflow configuration. Yes / -- None -- Regardless of the parent workflow configuration, the task instance will never wait for a previous instance to complete. Yes / Wait for Last Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until the most recent prior instance of the same task has completed. Yes / Wait for Last / Same Workflow Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until the most recent prior instance of the same task, within an instance of the same workflow, have completed. Yes / Wait for All Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until all prior instances of the same task has completed. Yes / Wait for All / Same Workflow Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until all prior instances of the same task, within an instance of the same workflow, have completed.
Agent Details	This section contains assorted detailed information about the Agent / Agent Cluster selected for this task.
Cluster	Indication that selecting an Agent Cluster is required and selecting Broadcast, which lets you select a Cluster Broadcast, is optional. If Cluster is selected, selecting an Agent is not required unless Agent Variable is selected.
Agent	Name of the Agent resource that identifies the machine where the operation will run. If you do not specify an Agent, you must specify an Agent Cluster or Cluster Broadcast.
Agent Variable	Indication of whether the Agent field is a reference field for selecting a specific Agent (unchecked) or a text field for specifying the Agent as a variable (checked). Use the format: ${variable name}. The variable must be a supported type as described in Variables and Functions. Note When updating multiple Tasks, to change from using an Agent reference to using an Agent variable, you must change the Agent Variable field to Yes and specify the Agent variable in the Agent Unresolved field. Conversely, to change from using an Agent variable to using an Agent reference, you must change the Agent Variable field to No and specify the Agent reference in the Agent field.
Agent Cluster	If Cluster is selected and Broadcast is not selected; Group of Agents, one of which the Controller will choose to run this task (compare with Cluster Broadcast). You can specify an agent cluster in addition to or in place of a specific Agent. If you specify an Agent and an agent cluster, the Controller first tries to run the task on the specific agent. If the Agent is not available, the Controller reverts to the agent cluster. See Agent Clusters for more information.
Agent Cluster Variable	Indication of whether the Agent Cluster field is a reference field for selecting a specific Agent Cluster (unchecked) or a text field for specifying the Agent Cluster as a variable (checked). Use the format: `${variable name}`. The variable must be a supported type as described in Variables and Functions. Note When updating multiple Tasks, to change from using an Agent Cluster reference to using an Agent Cluster variable, you must change the Agent Cluster Variable field to Yes and specify the Agent Cluster variable in the Agent Cluster Unresolved field. Conversely, to change from using an Agent Cluster variable to using an Agent Cluster reference, you must change the Agent Cluster Variable field to No and specify the Agent Cluster reference in the Agent Cluster field.
Broadcast	Displays only if Cluster is selected; Indication that selecting a Cluster Broadcast is required. Selecting Broadcast hides the Agent and Agent Cluster fields; you cannot select values for them.
Cluster Broadcast	Group of Agents, all of which will run this task (compare with Agent Cluster). If Broadcast is selected for a task, you must select a Cluster Broadcast instead of a specific Agent and/or agent cluster. Each instance of the task running on its own Agent becomes a separate task instance record in the database and displays separately on the Activity Monitor.
Cluster Broadcast Variable	Indication of whether the Cluster Broadcast field is a reference field for selecting a specific Cluster Broadcast (unchecked) or a text field for specifying the Cluster Broadcast as a variable (checked). Use the format: ${variable name}. The variable must be a supported type as described in Variables and Functions. Note When updating multiple Tasks, to change from using a Cluster Broadcast reference to using a Cluster Broadcast variable, you must change the Cluster Broadcast Variable field to Yes and specify the Cluster Broadcast variable in the Cluster Broadcast Unresolved field. Conversely, to change from using a Cluster Broadcast variable to using a Cluster Broadcast reference, you must change the Cluster Broadcast Variable field to No and specify the Cluster Broadcast reference in the Cluster Broadcast field.
Credentials	Credentials under which an Agent runs this task. These Credentials override any Credentials provided in the Agent Details for any Agent running this task. If the user does not have a login shell, add a - character in front of the runtime credentials name. The Controller will provide a shell for that user and strip the - character from the name. Required if the Agent Credentials Required Universal Controller system property is true. When required, if the Credential is specified as a variable, and the variable resolves to blank, a Start Failure will occur.
Credentials Variable	Indication of whether the Credentials field is a reference field for selecting a specific Credential (unchecked) or a text field for specifying the Credential as a variable (checked). Use the format: `${variable name}`. The variable must be a supported type as described in Variables and Functions. Note When updating multiple Tasks, to change from using a Credentials reference to using a Credentials variable, you must change the Credentials Variable field to Yes and specify the Credentials variable in the Credentials Unresolved field. Conversely, to change from using a Credentials variable to using a Credentials reference, you must change the Credentials Variable field to No and specify the Credentials reference in the Credentials field.
Agent File Monitor Details	This section contains assorted detailed information about the task.
Monitor Type	Type of file event being monitored for. Options: Create - Wait for the creation of one or more files. Delete - Wait for the deletion of one or more files. Change - Monitor for a change in one or more files. Exists - Check to see if one or more files already exist. Missing - Check to see if one or more files do not exist. Note For UNIX and Windows, Agent File Monitor polls the directory listing every 5 seconds to compare the listings and decide whether there were any file system changes that match the monitor criteria.
Trigger on Existence	If Monitor Type = Create; Task is triggered if the file being monitored for creation already exists. Note This field is valid only for Linux/Unix and Windows Agents.
Trigger on Create	If Monitor Type = Change; Task is triggered if the file being monitored is being created. Note This field is valid only for z/OS Agents.
Monitor File(s)	Location and name of a specific file or file pattern (for example, ACT001*) being monitored. Variables supported. Wildcards supported. Note z/OS files must be valid names based on the Data Set Naming Rules. No extra quoting is necessary. Note Agent File Monitors with Monitor Type = Exists or Missing do not work with GDG datasets. Whether the generation is coded explicitly (for example: DATA.SET.NAME.G0001V00) or relatively (for example: DATA.SET.NAME(0)), the Agent File Monitor will always end with 'Dataset Not Found'.
Use Regular Expression	Enables the use of a regular expression in the Monitor File(s) field.
Recursive	If enabled, the monitor searches the specified directory and all subdirectories.
Maximum Files	If Monitor Type = Create, Delete, or Change; For searches that use wildcards, limits the number of files to be searched.
File Owner	If Monitor Type = Create, Delete, Change, or Exists; User name / group name of the owner of the file on the operating system; that is, the user name / group name returned by the operating system in the file ownership information. LDAP groups are supported. Specifying a file owner limits the search to files with that owner.
Stable (seconds)	If Monitor Type = Change or Create; Period of time, in seconds, that a file's timestamp and size may not change to be considered as stable. Not applicable for z/OS.
By Percentage (+/-)	If Monitor Type = Change; Number that specifies the growth of a file as a percentage. A negative number specifies a reduction in size as a percentage. Not applicable for z/OS.
By Size (+/-)	If Monitor Type = Change; Used in conjunction with the By Scale field, specifies an actual change in file size. For example, to monitor for a change in file size of 10 MB, enter 10 in this field and select MB in the By Scale field. Enter a negative number to specify a reduction in size. Not applicable for z/OS.
By Scale	If