The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
When a job enters the production schedule, it begins a life cycle consisting of five general phases:
Step 1 The job waits in the schedule for its dependencies to be met.
Step 2 The job enters a queue and waits for an execution slot to be available.
Step 3 The job is launched on an agent.
Step 5 The job completes and enters history.
Throughout the life cycle of a job, it goes through a variety of conditions that affect it. Some of these conditions arise from factors that occur within the job process and other conditions arise from factors outside of the job’s life cycle. Some conditions are recognized as key occurrences within the process of job scheduling by designating them as event triggers.
Once the event condition is defined, a predefined action must be associated with it. In effect, an event defines a cause and effect–when this condition occurs, do this. Defining events allows you to create automatic responses to conditions within your system.
Some of these event triggers are predefined by TES as internal events and some events are defined externally by users as conditions to be monitored by event monitors during designated times periods.
These event triggers are grouped into different categories according to the type of conditions that create the events.
From the Navigator pane, select Definitions>Events to display the Events pane.
Enter text that you want to search for within the columns displayed into this field.
Note This field at the top right of the grids will only search text columns that are not grayed out and are string-based. See Searchable Columns.
Job and system events are defined as conditions that occur within TES while variable, file and email are defined as conditions that occur outside of the system that TES will monitor for.
Every job or system event log action generates a entry to the TES log. If you are running TES on Windows, you can also choose to write to the Windows application log. Each Windows log message generated by a TES event has a unique event ID number. The unique IDs make it possible to interact with other third party software. (These event IDs do not apply to the Unix platform.)
A complete list of both job and system event triggers and their event ID numbers is provided in Chapter 12, “Event ID Tables”.
If you select Preferences from the View main menu while viewing the Events pane, the Events Preferences dialog displays.
From the Events Preferences dialog, you can select which columns are displayed in the Events pane and in what order they appear.
When you right-click in the Navigator pane while viewing the Events pane, the Navigator context menu displays.
The Events Navigator context menu contains the following elements:
When you right-click in the Events pane, a context menu displays.
The Events pane context menu contains the following elements:
A job event connects job event triggers to actions. For example, you can create a job event that sends you an email message (an email action) if any of your jobs complete with a Completed Abnormally status. Each job event that you create is associated with a particular event trigger, and can result in one or more actions that you select. You can make job events generic for assignment to multiple jobs. Job events can also be made public for all users of TES to use. You can only view job events that belong to you and any workgroups you belong to.
The job event is created in the Job Event Definition dialog by linking predefined actions to the job event triggers that TES provides.
TES monitors every point of a job’s life cycle to trigger job events. These job event triggers are associated with a job event from the Job Event Definition dialog.
The Job Event Definition dialog displays when you add or edit a job event.
This tab associates action(s) to the job event. An event must have at least one associated action before it can be enabled. The actions that are available are the actions that are predefined in the Actions pane. If you are defining a job event, then job control actions are also available. The associated actions will occur in sequence that they are listed.
You cannot add the same action more than once. Although you can assign multiple actions to a job event, you can apply only one job control action to an event. Adding a second job control action will replace the original job control action displayed in the Selected Actions field. The actions available to use may be limited by your security policy.
You can choose from the following types of job control actions that TES provides (for Job event only):
Abort – Terminates the job if it is active, resulting in the job completing abnormally.
Cancel – Cancels the job occurrence if it has not started yet.
– Cancel Pending – Cancels the job occurrence but passes the job’s dependencies to any successor jobs. In essence, the job goes into a Waiting on Dependencies state as the dependencies run. Once all of the job’s dependencies are satisfied, the job ends with a Cancelled Normally status that is equivalent to a Completed Normally status.
Hold – Prevents your job from running when its dependencies are met. The job changes its status to Held . You can release the job at a future time. (Not available for jobs running on Windows agents).
Stop – Stops the execution of an active job. You can restart the job at a future time using the Resume job control. (Not available for jobs running on Windows agents).
– Override – Overrides any dependencies for which your job is waiting. It is recommended to use this option only with the Job not ready by end of its time window and Job might not be ready by end of time window event triggers.
Release – Releases a job that has the Waiting On Operator status.
Resume – Resumes a job that has either a Held or Stopped status.
– Rerun – Sets the maximum number of job reruns. To set the number of reruns, double-click Rerun in the Available Action(s) pane in the Job Event Definition dialog to display the Event Parameter dialog. See the following figure.
Maximum Reruns – Use to set the number of reruns. The default is 0. The maximum number the field can accommodate is 9999.
– Set To Completed Abnormally – Sets the job’s completion status to Completed Abnormally .
– Completed Normally – Sets the job’s completion status to Completed Normally . For example, when your process completes with a non-zero exit code, TES assumes the job has completed abnormally. Using this action, with a Job Completed Abnormally job event trigger, the job will be reset with a final status of Completed Normally .
Note Although job status can be changed using the Set Status action, the actual exit code of a job (0 for Completed Normally, non-zero for Completed Abnormally) is not changed.
– Set To Error Status – Sets the job’s completion status to Error Occurred .
– Set To External Status – Sets the job’s completion status to Externally Defined.
– Set To Orphaned Status – Sets the job’s completion status to Orphaned .
– Set To Skipped Status – Sets the job’s completion status to Skipped .
When you right-click in the Available Action(s) field on the Associated Action(s) tab of the Job Event Definition dialog, the Available Actions context menu displays.
The Available Action(s) context menu contains the following elements:
Note When creating an email message for a system event about losing your database connection, do not use variables that will not work without a connection to the database, i.e., <JobName> or <JobStatus>.
Note Fundamental master and agent connection information is automatically logged by TES, so you do not have to create a separate alert action for master or agent start or stop.
Note Add Job Action – Displays the Action Definition: Job dialog to submit unscheduled jobs in response to the event. The action will be added to the Actions pane and to the Available Action(s) field. For more information about job actions, see “Action Definition: SNMP Dialog” section.It is possible to create an infinite loop that continually submits jobs if a job inserted with a new job action is also listed in the Associated job(s) tab.
This tab is used to link the job event to any number of jobs. This tab does not appear if you selected the Apply this event to all jobs option. You can also assign job events in the Job and Job Group Definition dialogs. The specified event trigger is monitored for all jobs that are listed in this tab.
This tab contains the following elements:
The jobs that are added are displayed in the field below but they are not added (or associated with the job event) until the Add button is clicked.
This is a free text field where you can provide a description and notes about this particular event, up to 255 characters.
The Trigger History tab lists all of the instances when the event was triggered during the trigger history retention period. This retention period is configured on the Default tab of the System Configuration dialog.
There are usually only four columns of basic information about each time that the event occurred but a job event has two additional columns to identify the job that was triggered by the event.
This tab contains the following elements:
– Scheduled – The event trigger is scheduled for the current day
– Suspended – The event trigger is scheduled for the current day but has been suspended using the Suspend Monitoring option in the Monitor Control context menu in the Event Activity pane.
– Outside time window – The event trigger is scheduled for the current day but is currently outside of the event monitor’s specified time windows and is thus inactive.
You can drill down to get additional information about each event instance listed in this Trigger History tab. Right-click any of the listed event triggers to either update the information with the Refresh option or you can display details about the trigger with the Trigger Details option.
The Trigger Details dialog displays more information about an event instance that occurred. The Trigger Details dialog displays by selecting an event trigger listed in an Event Details dialog and right-clicking and selecting the Trigger Details option.
The Details tab displays basic run information about the event trigger.
This tab contains the following elements:
The Triggered Actions tab () provides information about the action(s) that the event initiated.
The Triggered Actions tab displays the following columns of information about its associated actions:
If an action triggered is a job action, you can display additional details about the job that was triggered.
Right-click the job to display a context menu. You can update the details about the job by clicking the Refresh option.
This tab displays in the Job Event Definition dialog only if the Job completed with specified exit code(s) option is selected in the Event Trigger field. If you are creating a job event that is triggered by a specific exit code or a range of exit codes, type the exit code(s) on this tab. You can create several actions using different job event triggers keyed to different exit code ranges to denote various job statuses. The exit code you use is determined by the script you are using. The exit code value can range from 0 to 30,000.
Use the operator field to select an operator for comparing the exit code(s) specified in the adjacent fields.
System events assign actions to events generated by the TES master. For example, if the master is shutdown, you can notify users via email that jobs will not run until the master has started again. System events are useful for notifying interested users of conditions with system-wide effects.
You create system events much like job events, except that they are not associated with particular jobs, since they are applicable to all jobs. Each includes a system event trigger, and one or more actions to take when the event occurs. The system event is created in the System Event dialog by linking predefined actions to the system event triggers that TES provides.
The TES master is constantly monitoring for the conditions that trigger system events. The four categories of system event triggers monitored by TES are:
This tab associates action(s) with the system event. An event must have an associated action before it can be enabled. For information about the fields on this tab, refer to “Associated Action(s) Tab” section
This is a free text field where you can provide a description and notes about the system event (up to 255 characters).
The Trigger History tab lists all of the instances when the event was triggered during the trigger history retention period. This retention period is configured on the Default tab of the System Configuration dialog. For information about the fields and options on this tab, refer to the “Trigger History Tab” section .
An event monitor can be defined to watch a designated variable on a master. Whenever the variable matches a specified value it becomes an event that triggers an assigned action.
A variable monitor is defined from the Variable Event Definition dialog. The Variable Event Definition dialog displays whenever you add or edit a variable event.
In the Navigator pane, select Definitions>Events>Variable Events to display the Variable Events pane. To display the Variable Event Definition dialog, either right-click in the pane in the Variable Events pane and select Add Event from the context menu or click the Add Event button.
The Variable tab () designates a variable to be monitored and defines the characteristics of the variable that will trigger an action.
In this section, designate a variable, a master associated with the variable and a value to be monitored for.
– Greater Than or Equal To (>=)
When text strings are used in comparison, higher letters of the alphabet are greater than lower letters. For example, A < Z . If the first letters of the string match, succeeding letters are used for comparison. For example, AA < AZ . The operation works similar to sorting strings.
The Schedule tab displays when the event monitor is scheduled to monitor for the defined event conditions. The fields on these tabs are the same fields that are on their respective tabs in their Event Definition dialogs. Refer to the “Configuring the Schedule Tab on an Event Monitor” section for more information about the fields on this tab.
This tab associates action(s) with the variable event. An event must have an associated action before it can be enabled. For information about the fields on this tab, refer to “Associated Action(s) Tab” section .
This is a free text field where you can provide a description and notes about this particular event, up to 255 characters.
The Trigger History tab lists all of the instances when the event was triggered during the trigger history retention period. This retention period is configured on the Default tab of the System Configuration dialog. For information about the fields and options on this tab, refer to the “Trigger History Tab” section .
An event monitor can be defined to monitor for a designated file and trigger an associated action whenever that file meets the defined conditions.
A file event monitor is defined from the File Event Definition dialog. The File Event Definition dialog displays whenever you add or edit a file event.
In the Navigator pane, select Definitions>Events>File Events to display the File Events pane. To display the File Event Definition dialog, either right-click in the File Events pane and select Add Event from the context menu or click the Add Action button.
The File Monitor tab defines the file and the event characteristics that a file monitor will watch for.
This tab contains the following elements:
Any combination of the following criteria options can be selected to apply to the file.
– Move file to target directory – Moves the monitored file to the directory that is specified in the Target field. This does not replace any of the existing files in the target directory.
– Delete file from source directory – Deletes the monitored file from the directory designated in the Source field once the specified conditions are met.
The Schedule tab displays when the event monitor is scheduled to monitor for the defined event conditions. The fields on these tabs are the same fields that are on their respective tabs in their Event Definition dialogs. Refer to the “Configuring the Schedule Tab on an Event Monitor” section for more information about the fields on this tab.
This tab associates action(s) with the file event. An event must have an associated action before it can be enabled. For information about the fields on this tab, refer to “Associated Action(s) Tab” section .
This is a free text field where you can provide a description and notes about this particular event, up to 255 characters.
The Trigger History tab lists all of the instances when the event was triggered during the trigger history retention period. This retention period is configured on the Default tab of the System Configuration dialog. For information about the fields and options on this tab, refer to the “Trigger History Tab” section .
The Event Activity pane displays information about the status and activity of each event that has been defined. A user can only view events in this pane that are made public to all users or that belong to that user or the workgroups that the user is a member of. A user can drill down through each event record for more details about the circumstances of each event.
From the Navigator pane, select Operations>Event Activity to display the Event Activity pane. You can double-click any of the listed events to display its details.
Enter text that you want to search for within the columns displayed into this field.
Note This field at the top right of the grids will only search text columns that are not grayed out and are string-based. See Searchable Columns.
– Yellow – Outside time window status
– Scheduled – The event trigger is scheduled for the current day
– Suspended – The event trigger is scheduled for the current day but has been suspended using the Suspend Monitoring option in the Event Control context menu in the Event Activity pane.
– Outside Time window – The event trigger is scheduled for the current day but is currently outside of the event monitor’s specified time windows and is thus inactive.
Select Preferences from the View main menu while viewing the Events Activity pane to display the Event Activity Preferences dialog.
This dialog contains the following elements:
– A checkmark to the left of a column title indicates that it will be displayed in the pane. No checkmark indicates that it will not be displayed.
– To rearrange the order in which the columns are displayed, select the column and click the up or down arrow.
When you right-click in the Navigator pane while viewing the Event Activity pane, the Navigator context menu displays.
The Navigator context menu for the Event Activity pane contains the following options:
When you right-click in the Event Activity pane, the Event Activity context menu displays. The Monitor Control options only apply to external events such as file, email or variable events that have defined a monitor. The Event Activity context menu has the following options:
– Suspend Monitoring – Suspends the monitoring activity of the selected event monitor.
– Resume Monitoring – Resumes the monitoring activity of the event monitor that was suspended.
The details for any event listed in the Event Activity pane can be displayed by either double-clicking it or by right-clicking it and selecting Details from the context menu. Those events that define monitors have additional tabs to provide details specific to that type of event.The fields on the tabs of the Event Details dialog are read-only though a user can update the information in the fields at any time by selecting the Refresh option from the context menu.
These tabs appear depending upon the type of event selected. Job and system events do not have these tabs because they do not require a monitor. The fields on these tabs are the same fields that are on their respective tabs in their Event Definition dialogs.
These tabs only appear for variable, file and email events. The Schedule tab displays when the event monitor is scheduled to monitor for the defined event conditions. The fields on these tabs are the same fields that are on their respective tabs in their Event Definition dialogs. Refer to the “Configuring the Schedule Tab on an Event Monitor” section for more information about the fields on this tab.
The Triggered Today tab lists all of the instances when the event was triggered during the current production day. The columns of information on this tab is the same as the ones on the Trigger History tab. Once the current production day ends, the information on this tab is moved to the Trigger History tab. Like the Trigger History tab, you can also drill down to get more information about the event trigger, and, if a job event, more information about the job that the event was associated with. Refer to the “Trigger History Tab” section for more information about the fields on this tab.
The Trigger History tab lists all of the instances when the event was triggered during the trigger history retention period configured in the System Configuration dialog. The fields on this tab are the same fields as on the Triggered History tab of the Event Definition dialog. Refer to the “Trigger History Tab” section for more information about the fields on this tab.
You can link any number of jobs or job groups to a job event.
To add a job/job group to a job event:
Step 1 Select one of the defined job events in the Job Events pane.
Step 2 Double-click the job event to edit from the Job Events pane, or right-click the job event and select Edit Event from the context menu, or select the job event and click the Edit button on the TES toolbar to display the Job Event Definition dialog.
Step 3 Click the Associated Job(s) tab.
Step 4 The drop-down arrow button lists all the jobs you own and that are owned by workgroup to which you belong.
Step 5 Select the job(s) and/or job group(s) you want to associate to this job event and click the Add button.
You can associate any number of actions to an event. However, if you are using a job control action type (Job events only), then only one job control can be associated (or combined with the other action types) at any time. When the event trigger occurs, all the actions that are associated with the event will occur.
To associate actions to events:
Step 1 From the Navigator pane, select Definitions>Events to display the Events pane.
Step 2 Double-click the event or right-click the event and select Edit Event from the context menu, or select the event and click the Edit button on the TES toolbar to display the Event Definition dialog.
Step 3 Click the Associated Action(s) tab.
Step 4 In the Available Action(s) field, select the action(s) to associate with the event.
You can select the actions and then use the left arrow button (<). To select more than one action at the same time, hold down the Shift key or the Ctrl key on your keyboard while clicking your selections, then click the left arrow button.
Job control actions are displayed in the Available Actions field if you are working on a Job event.
Note It is possible to create an infinite loop that continually submits jobs if you assign a new job action that inserts a job that is also listed in the Associated job(s) tab.
To change the ownership of an event:
Step 1 From the Navigator pane, select Definitions>Events to display the Events pane.
Step 2 Double-click the event to edit from the Events pane or right-click the event and select Edit Event from the context menu, or select the event and click the Edit button on the TES toolbar to display its Event Definition dialog.
Step 3 From the drop-down menu in the Owner field, select a new owner of the event.
You can create a job event that connects an event trigger to one or more actions. You can link jobs or job groups to job events at any time either from the Job Event Definition dialog or the Job Definition or Job Group Definition dialogs. Actions are associated with a job event only from the Job Event Definition dialog.
Step 1 From the Navigator pane, select Definitions>Events>Job Events to display the Job Events pane.
Step 2 Click the Add button or right-click and select Add Event from the context menu to display the Job Event Definition dialog.
Step 3 In the Event Name field, type a name for the job event (up to 30 characters).
Step 4 If you do not want to own this job event, select another user or workgroup from the drop-down menu in the Owner field.
Step 5 If you want this job event to be associated with all jobs, select the Apply this event to all jobs option; otherwise, you must click the Associated Jobs tab to select a job(s) to associated with the event.
Step 6 If you want the event to be public, select the Public option. Note that if an event is public, all users of TES with the appropriate security policy have access to that job event.
Step 7 If you want to define the event now, but you are not ready to have it triggered, clear the Enabled option
Step 1 From the Navigator pane, select Definitions>Events>Email Events to display the Email Events pane.
Step 2 From the Email Events pane, right-click and select the Add Event option from the context menu, to display the Email Event Definition dialog.
Step 3 In the Event Name field, enter a name for the email event.
Step 4 By default, the user defining the event is the owner but you can select one of the other listed users from the drop-down menu as the owner.
Step 5 In the Email Connection field, select a connection to an Exchange server. The connection must be already defined before it will appear in the drop-down list.
Step 6 In the Folder field, enter the name of the mail account to be monitored.
Step 7 In the Conditions section, designate what text is to be considered an event when it is detected.
Step 8 Click the adjacent Insert button to add a line to the Conditions section.
a. In the Scan for Text column, enter a text string that the monitor will scan for in the email going to the designated mail account.
b. In the In column, select from the drop-down list where in the email that the monitor should look for the text.
c. In the Case Sensitive column, designate whether the text match is dependent upon case.
d. In the Disposition section, select what will occur once the monitor detects the specified text. From the drop-down list in the Operation field, select an option. If you select the Move message to folder option, in the Target field, enter the pathname to the folder where you want the message stored.
e. If you want to access the message text from within TES, select the Return message body to Scheduler option.
Step 1 From the Navigator pane, select Definitions>Events>Email Events to display the Email Events pane.
Step 2 From the Email Events pane, right-click and select the Add Event option from the context menu, to display the Email Event Definition dialog.
Step 3 In the Event Name field, enter a name for the email event.
Step 4 By default, the user defining the event is the Owner but you can select one of the other listed users from the drop-down menu as the owner.
Step 5 In the Master field, select the master that owns the variable.
Step 6 In the Variable Name field, select the variable to be monitored.
Step 7 In the Operator field, select the operator to be used with the specified value.
Step 8 In the Value field, specify the value that the variable needs.
Step 9 If defining an intermaster variable so that the monitor will watch for a variable published from another master, select the Variable option and specify the Master and the Variable Name .
Step 1 From the Navigator pane, select Definitions>Events>Email Events to display the Email Events pane.
Step 2 From the Email Events pane, right-click and select the Add Event option from the context menu, to display the Email Event Definition dialog.
Step 3 In the Event Name field, enter a name for the email event.
Step 4 By default, the user defining the event is the Owner but you can select one of the other listed users from the drop-down menu as the owner.
Step 5 In the Agent Name field, enter the
Step 6 In the Directory field, enter the path to the directory to be monitored for the file’s appearance.
Step 7 In the File Mask field, you can enter a file mask using wild card characters.
Step 8 If needed, you can configure the monitor to delay its response or to only respond after the designated file is stable for a stated interval of time or reaches a certain size.
Step 9 In the Disposition section, specify what should be done with the file when it meets the monitor’s criteria.
Step 10 In the Operation field, you can either delete the file or move it to another directory that is designated in the Target field.
Step 11 If needed, you can select the Return file contents as output option include the file’s contents as part of the job output.
Whenever an event monitor is defined, it must be configured to watch for the defined event criteria at the crucial times. This is done by scheduling when the monitor should be active.
To configure the Schedule tab:
Step 1 Select the Schedule tab in the event being defined.
Step 2 In the Calendar section, select and configure a calendar as needed.
Step 3 If you want to restrict how often the event can be triggered, select the Trigger Constraints option and configure how often the event can be triggered within a designated interval. Select the Ignore occurrences that exceed the limit option
Step 4 If you want the event monitor to operate all of the time, do not select the Time window option; however, if you want the event monitor to operate only during certain periods of the day, select this option. Click Insert to create a row in the Time window field and enter a starting time in the From Time column and an ending time in the Until Time column. Create as many time windows as needed.
You can delete an event that is no longer in use. When you delete an event, the job event is removed from the jobs and job groups associated with it.
Step 1 From the Navigator pane, select Definitions>Events>Job Events to display the Job Events pane.
Step 2 Select the job event to delete and press the Delete key on your keyboard or click the Delete button on the TES toolbar or right-click the job event and select Delete Event from the context menu.
Step 3 Click OK in the confirmation dialog to delete the job event.
To remove an action from an event:
Step 1 Select an event in the Events pane.
Step 2 Open the event definition by double-clicking the event or right-click the event and select Edit Event from the context menu, or select the event and click the Edit button on the TES toolbar to display the its Event Definition dialog.
Step 3 Click the Associated Action(s) tab.
Step 4 In the Selected Actions(s) field, select the action(s) to remove from the job event, and click the right arrow button (>).
To remove a job or job group from a job event:
Step 1 From the Navigator pane, select Definitions>Events>Job Events to display the Job Events pane.
Step 2 Double-click the job event to edit from the Job Events pane or right-click the job event and select Edit Event from the context menu, or select the job event and click the Edit button on the TES toolbar to display the Job Event Definition dialog.
Step 3 Click the Associated Job(s) tab.
Step 4 From the Associate Job(s) field, select the job(s)/job group(s) to disassociate from the job event.
You can view all the events available to you according to your security policy and all public events in the Events pane. You can also view the job events for a job from the Job Events tab of the Job Definition and Job Group Definition dialogs.
From the Navigator pane, select Definitions>Events>Job Events to display the Job Events pane.
To view a job or job group associated with a job event:
Step 1 From the Navigator pane, select Definitions>Events>Job Events to display the Job Events pane.
Step 2 Double-click the desired job event from the Job Events pane, or click the Edit button on the TES toolbar to display the Job Event Definition dialog.
Step 3 Click the Associated Job(s) tab to display the jobs and job groups associated with the job event.
To view a job event associated with a job or job group:
Step 1 From the Navigator pane, select Definitions>Jobs to display the Jobs pane.
Step 2 Double-click the desired job or job group or right-click and select Edit Job/Group from the context menu to display its Job Definition (or Job Group Definition ) dialog.
Step 3 Click the Job Events tab to display all job events associated with the job or job group.