2.4.4 Executing an event-driven process (example of defining a jobnet that uses an event job)
Use an event job when defining a jobnet in which a process is triggered by an occurrence such as event receipt or file update.
An event job can be used to monitor events on any manager host or agent host on the network. The following figure shows the types of events that can be monitored.
|
- Timing of event detection by an event job
-
There might sometimes be a time lag between the execution time of an event job and the time that it is ready to monitor events. Events occurring during this time lag will not be detected. You should bear this in mind when defining a jobnet that uses an event job.
For Receive JP1 event jobs, you can use the find events prior to execution setting to solve this problem (see (1) Executing a process on receipt of a JP1 event (Receive JP1 event job) below.)
- Using randomly occurring events to trigger a jobnet
-
When an event occurs more than once at irregular times, we recommend that you set a start condition for the jobnet triggered by that event. For details on setting a start condition, see 3.4 Defining a start condition in the manual Job Management Partner 1/Automatic Job Management System 3 Overview.
If you know that the event you are monitoring occurs in a predictable manner, you can define an event job at the start of the jobnet, rather than defining a start condition.
- Setting a timeout period for an event job
-
When a timeout period is set for an event job, the period is counted at the host on which the job is executed. If a power failure or other problem occurs at the target host and event monitoring is resumed after the host is restarted, the timeout period is counted again, beginning from the restart time. To suspend monitoring by the event job at an absolute time, counted from the execution start time regardless of the host status, define an event job as the jobnet start condition and set the valid range of start condition to absolute time. For details on start conditions, see 3.4 Defining a start condition in the manual Job Management Partner 1/Automatic Job Management System 3 Overview.
You must also specify what status the event job is to be placed in after the timeout period specified for the job has elapsed. Select Killed, Ended normally, Ended with warning, or Ended abnormally status (the default is Killed status).
By setting an event job in this way, you can choose to cancel or continue the jobnet after the event job's timeout period elapses.
- Passing event information
-
You can define the event information received by an event job as a variable (macro variable) that is passed to the succeeding unit. For details on passing event information, see (6) Passing information received by an event job below.
An example of an event job defined in a jobnet is given below. For additional information on defining an event job in a jobnet, see 7.6 Notes on using event jobs
JP1/AJS3 must be linked with the appropriate program to use a Receive mail job. For details, see the Job Management Partner 1/Automatic Job Management System 3 Linkage Guide.
- Organization of this subsection
-
-
(1) Executing a process on receipt of a JP1 event (Receive JP1 event job)
-
(2) Executing a process at file update (Monitoring files job)
-
(3) Executing a process at log file update (Monitoring log files job)
-
(4) Executing a process on receipt of a Windows event log record (Monitoring event log job)
-
(5) Executing a process after a specified wait time (Interval control job)
-
(1) Executing a process on receipt of a JP1 event (Receive JP1 event job)
A JP1 event is an event managed by JP1/Base, issued whenever some event occurs in a JP1 program. Because JP1 events contain information such as a severity level (error, warning, or notice) or message, you can execute a succeeding job or jobnet on receipt of an error or warning, or only when a specific message is received. Using the JP1/Base event converter, you can also execute a succeeding job or jobnet at termination of an external application program.
To execute a Receive JP1 event job, you must first start the JP1/Base event service. (In the API settings file, set keep-alive for the JP1/Base event service.) If this service is inactive, the Receive JP1 event job is placed in the Now running status until the service starts.
The following figure shows an example of defining a jobnet that executes a certain job when the Receive JP1 event job receives a JP1 event from hostA, which differs from the host where the jobnet was defined.
|
A Receive JP1 event job can link with a jobnet defined on another host.
On hostA, define a Send JP1 event job that sends an event with the event ID of 100. To monitor any JP1 events issued by hostA, set hostA in the Receive JP1 event job as the event-originating host name. In addition, to execute the succeeding job when an expected JP1 event is received, set 100 as the event ID.
After these settings have been made, if the Send JP1 event job in the jobnet is executed on hostA, the jobnet stops monitoring JP1 events and executes the succeeding job.
Note that the system will not detect any JP1 event occurring during the time lag after execution of the Receive JP1 event job until it is actually able to monitor for receipt of JP1 events. One solution to this problem is the find events prior to execution setting.
(2) Executing a process at file update (Monitoring files job)
Use a Monitoring files job when defining a jobnet in which file update or file creation triggers a job.
The monitoring options that you can specify for a Monitoring files job are described below.
- Monitoring options
-
Specify the file status required as the condition to end monitoring and initiate the job. You can set any of the following four monitoring options:
-
Creation of a file of the specified file name (Create)
-
Deletion of a file of the specified file name (Delete)
-
Change in size of a file of the specified file name (Change size)
-
Change in last update time of a file of the specified file name (Final time write)
-
- Supplementary notes
-
-
When creation of a file with the specified name is being monitored, that file might already exist at the time the Monitoring files job starts. You can specify whether the job should assume that the monitoring condition has been satisfied if a file with the specified name already exists.
-
You can specify more than one monitoring condition. For example, if you want to execute a succeeding job when a file is deleted or updated, you can specify the Delete and Final time write options. Note, however, that the Change size and Final time write options are mutually exclusive.
-
For details on when a monitoring condition is or is not satisfied, see 7.6.2(1) Events monitored by the Monitoring Files job.
-
If any of the Create, Change size, and Final time write monitoring conditions are satisfied, the system performs a close check to make sure the monitored file is not being accessed by any process other than the Monitoring files job. If another process is accessing the file, the condition is judged to be unsatisfied, and another close check is performed when the next monitoring interval occurs. If the file is not being accessed by a process other than the Monitoring files job, the condition is judged to have been satisfied.
The close check prevents the job from assuming that the condition is satisfied before the transmission (for example, copying) of a monitored file has been completed.
-
In the example below, a Monitoring files job is used to define a jobnet that monitors the write time to a particular file (file name: File1) and executes a succeeding job when the file is updated.
|
Specify the file to monitor and the monitoring option in the definition of the Monitoring files job. In the Monitoring file field, enter the path for File1, and in the Monitoring option area, select Final time write.
In this example, the Monitoring files job ends and the triggering condition is satisfied when the monitored file closes (no further applications are accessing the file) and the last update time changes.
(3) Executing a process at log file update (Monitoring log files job)
A Monitoring log files job utilizes the JP1/Base log file trapping facility. JP1/Base log file trapping converts the log file records output by an application into JP1 events, and registers them in an event database. By defining a Monitoring log files job, you can execute a job or jobnet when a log file is updated. For details on JP1/Base log file trapping, see the Job Management Partner 1/Base User's Guide. For notes about Monitoring log files jobs, see 7.6.4 Notes on the Monitoring Log Files job.
The following figure shows how a Monitoring log files job operates.
|
A Monitoring log files job monitors for output of specific data to a log file on the host specified as the monitoring target. In this job, you specify the log file and the character string to be monitored. Regular expressions can be used to specify the character string (see the Job Management Partner 1/Base User's Guide for regular expressions in Windows, or your UNIX documentation for regular expressions in UNIX).
As the monitoring interval, you can specify a value from 1 to 86,400 (seconds). Only log files in text format can be monitored. You can monitor up to eight log files.
An example of setting a Monitoring log files job as the triggering condition is shown below.
In this example, the Monitoring log files job is used to define a jobnet that executes a succeeding job when log data containing a specific character string is written to the log file (file name: File1).
|
Specify the log file name and the character strings to be monitored in the definition of the Monitoring log files job. In the File to be monitored field, enter the path for File1. In the Data to be trapped area, enter the desired character strings as shown in the figure.
In this example, the Monitoring log files job ends when data matching any of three conditions (a string containing "abc" and "def", a string containing "ghi", or a string containing "jkl") is written to File1 and the log data is retrieved from the log file. This satisfies the triggering condition and the succeeding job is executed.
You can also configure a Monitoring log files job to monitor multiple log files and execute the succeeding job when log data containing a specific character string is written to any of the monitored files.
(4) Executing a process on receipt of a Windows event log record (Monitoring event log job)
A Monitoring event log job utilizes the JP1/Base event log trapping facility, which converts Windows event log records into JP1 events and registers them in an event database. By defining a Monitoring event log job, you can execute a job or jobnet when a Windows event is logged.
For details on JP1/Base event log trapping and the action definition file, see the Job Management Partner 1/Base User's Guide. For notes about Monitoring event log jobs, see 7.6.5 Notes on the Monitoring Event Log job.
The following figure shows how a Monitoring event log job operates.
|
A Monitoring event log job works as follows.
- Log type
-
The types of logs that you can specify are listed below:
-
Application
-
Security
-
System
-
DNS Server
-
Directory Service
-
File Replication Service
-
Any log type#
-
- #
-
For details about how to check the log types that can be specified for Any log type, see the Job Management Partner 1/Base User's Guide.
- Event types
-
You can specify the following types of events:
-
Verbose
-
Information
-
Warning
-
Error
-
Critical
-
Success audit
-
Failure audit
-
An example of defining a Monitoring event log job is shown below.
In this example, the Monitoring event log job is used in a jobnet that executes a succeeding job when a Windows event reporting successful authentication on the security system is logged to the Windows event log.
|
Before executing a Monitoring event log job, you must set the event log trapping behavior in the JP1/Base action definition file. In this example, the log type is Security, and the attribute name (with Type set) is Audit_success.
You must also set the log type and event type to be monitored. Set Security in Log type, and Success audit in Event type.
With these settings, the Monitoring event log job ends when the specified Windows event is output and the event log data is retrieved. This satisfies the triggering condition and the succeeding job is executed.
(5) Executing a process after a specified wait time (Interval control job)
Use an Interval control job when defining a jobnet in which a job is executed after a specified wait time.
In the example below, an Interval control job is used to define a jobnet that executes a recovery job 10 minutes later if the succeeding job ends abnormally.
|
If the preceding job ends abnormally, the next process is executed 10 minutes later. Therefore, use an Interval control job to monitor the time period. Set 10 minutes in Waiting time. Because the Interval control job will be executed at abnormal termination, set Recovery in the job Type. Likewise, set Recovery in Type for standard job C (the Interval control job's succeeding job).
With these settings, if standard job A ends abnormally, the Interval control job (recovery job) monitors the time until 10 minutes has passed, then standard job C (the succeeding job) is executed. If standard job A ends normally, standard job B is executed.
The Waiting time specified in an Interval control job refers to the wait time of the interval control process, not the time required to execute the Interval control job. Depending on the communication status or other factors, there might be a difference between the specified wait time and the actual interval.
(a) Defining the Interval Control job as a start condition
When you define the Interval Control job as a start condition, you can choose whether to satisfy the start condition as soon as the Interval Control job starts executing.
If you want the start condition to be satisfied immediately after the job has started executing, in the Detailed Definition - [Interval Control] dialog box, in the Expire right after starting section, click Yes. If you do not want the start condition to be satisfied immediately after the job has started executing and instead want to wait for the length of time specified in the Waiting time section for execution to start, in the Expire right after starting section, click No.
The following figure shows the behavior of two cases when five executions from 0:00 on July 1 have been specified in the Schedule Rule dialog box.
|
In example 1, Yes is chosen for Expire right after starting. In this case, the monitoring for the start condition starts at 0:00 on July 1. The start condition is quickly satisfied and the first execution of the jobnet begins. After that, the jobnet is executed every 10 minutes as specified in the Waiting time section.
In example 2, No is chosen for Expire right after starting. In this case, the monitoring for the start condition starts at 0:00 on July 1. After the 10 minutes specified in the Waiting time section have elapsed (at 0:10), the first execution of the jobnet begins. Thereafter, the jobnet is executed every 10 minutes.
When you click No for Expire right after starting, for the start time, you need to specify a period of time equal to the waiting time that is earlier than the time that the first execution of the jobnet starts.
- Cautionary notes
-
-
Expire right after starting is available when the version of JP1/AJS3 - Manager or JP1/AJS3 - Agent on the execution target host of the Interval Control job is 10-00 or later, and the version of JP1/AJS3 - View is 10-00 or later. If the version of JP1/AJS3 - Manager is 10-00 or later and the version of JP1/AJS3 - Agent on the execution target host is earlier than 10-00, specify the default execution agent (@SYSTEM) running on JP1/AJS3 - Manager as the execution agent. If the version of JP1/AJS3 - Manager or JP1/AJS3 - Agent on the execution target host is earlier than 10-00, the Interval Control job changes to the Ended abnormally status.
-
If you kill the JP1/AJS3 service or the scheduler service when Yes is chosen for Expire right after starting, the jobnet starts executing after the time specified in the Waiting time section has elapsed the next time the jobnet starts.
-
(6) Passing information received by an event job
The event information received by an event job can be defined as a variable (macro variable) that is inherited by the succeeding unit. This inherited information is called passing information.
To pass event information to a succeeding unit, you must define a macro variable in the event job and specify the same macro variable name in the succeeding unit.
In the event job, specify the macro variable in the following form:
- Macro variable definition
-
macro-variable-name:passing-information-name
For macro-variable-name, specify a character string of no more than 64 characters in the format ?AJS2xxxxx?. In xxxxx, you can use uppercase alphabetic characters (A to Z), numerals (0 to 9), and periods (.). In passing-information-name, you can specify only the passing information supported for the particular type of event job. For details, see B. Information Passed by Event Jobs.
At execution of a macro variable, the passed information is expanded in the command line on the target host that executes the succeeding unit of the event job. You should define a macro variable only if you are sure that the information to be passed is of a form that can be handled as a command argument when the succeeding job is executed.
For details on macro variables, see 2.2.6 Considerations regarding the use of macro variables.
The following explains how the information received by event jobs is passed to the various types of succeeding units.
To make event job information available to an entire jobnet, use a start condition. (For details on start conditions, see 3.4 Defining a start condition in the manual Job Management Partner 1/Automatic Job Management System 3 Overview.)
(a) Standard job or action job defined after an event job
The information received by an event job can be passed in a macro variable to a standard job (PC job or Unix job) or to an action job defined as the succeeding job. To enable the received event information to be passed, specify the macro variable name using items that can accept a character string, such as command text, a script file name, parameter name, or environment variable.
The following figure shows an example of a PC job defined after an event job.
|
When a standard job (PC job or Unix job) or action job is defined as the succeeding job of an event job, the received information is passed only to the job immediately following the event job. In the above example, the event information received by the Receive JP1 event job is passed to PC job A. The information is not passed to PC job B, even if PC job A ends abnormally.
(b) Nested jobnet defined after an event job
By specifying a macro variable name in a nested jobnet defined as the succeeding unit of an event job, you can pass the received event information to the standard jobs (PC jobs or Unix jobs) and action jobs defined in the nested jobnet. The following figure shows an example of a nested jobnet defined after an event job.
|
When a nested jobnet is defined as the succeeding unit of an event job, the received information is passed to all standard jobs (PC jobs or Unix jobs) and action jobs in the nested jobnet. In the above example, the event information received by the Receive JP1 event job is passed to PC jobs X, Y, and Z defined in nested jobnet A.
If the same event job with the same macro variable is also defined within the nested jobnet, the information received by the nested event job takes precedence. The following example shows the same event job and macro variable defined as a preceding job and also within the nested jobnet.
|
In this example, PC job X inherits event information from Receive JP1 event job (1), whereas PC job Y inherits the information received by Receive JP1 event job (2). The macro variable defined in Receive JP1 event job (1) is specified in PC job Z, so the information received by Receive JP1 event job (1) is passed to PC job Z.
(c) Judgment job defined after an event job
By specifying a macro variable name in the dependent job of a judgment job that follows an event job, you can pass the information received by the event job to both the dependent job and the succeeding job of the judgment job.
The following figure shows an example of a judgment job defined after an event job.
|
When a judgment job is defined as the succeeding job of an event job, the received information is passed to both the dependent job and the succeeding job of the judgment job. In the above example, the event information received by the Receive JP1 event job is passed to PC job A (the dependent job) and to PC job B (the succeeding job).
(d) OR job defined after an event job
By specifying a macro variable name in the succeeding job of an OR job that follows an event job, you can pass the information received by the event job to the succeeding job of the OR job.
The following figure shows an example of an OR job defined after an event job.
|
When an OR job is defined as the succeeding job of an event job, the received information is passed to the succeeding job of the OR job. In the above example, events are being monitored by two types of event jobs: a Monitoring files job and a Receive JP1 event job. A JP1 event occurs at 8:00. The information received by the Receive JP1 event job on detecting this event is passed to the OR job's succeeding job, and the Monitoring files job is placed in Bypassed status.
- Cautionary notes
-
-
Passing information can be passed even if the event job and the succeeding job are executed on different agent hosts. If the hosts use different character sets, the character codes in the passing information are converted. Note, however, that if the character set for the succeeding job does not contain character codes corresponding to the character codes being converted, character conversion will fail.
-
When a macro variable is specified in the command line of a succeeding job, the information will not be passed correctly if it contains a space or single quotation mark (').
-
Do not pass data containing an escape order to the command line. Enclose the macro variable with double quotation marks ("). This prevents unpredictable behavior should a space be included in the passed information.
-
When passing information is used in the command line of a job, any double quotation marks (") included in the information are ignored. For example, AB"C is passed to the succeeding job in the form ABC. This might cause the job to execute incorrectly, depending on the command line constraints of the particular operating system. If the information contains a special character, use an environment variable to pass the information, rather than expanding the macro variable in the command line. Note, however, that by utilizing the feature for enabling double quotation marks, information containing double quotation marks (") can be passed as is. For details on this feature, see 4.3.7(4) Passing event data containing double quotation marks in the Job Management Partner 1/Automatic Job Management System 3 System Design (Configuration) Guide. See also 6.3.4 Passing event data containing double quotation marks in the Job Management Partner 1/Automatic Job Management System 3 Configuration Guide 1 and 15.3.4 Passing event data containing double quotation marks in the Job Management Partner 1/Automatic Job Management System 3 Configuration Guide 1. This feature is not available in JP1/AJS2 - Manager 06-71 or earlier versions.
-
- Supplementary notes
-
-
When a single succeeding job follows multiple event jobs, it inherits the information received by all the event jobs. However, if you define the same macro variable name for all the event jobs, the received event job information will be overwritten each time. The succeeding job will be able to reference only the most recently received information.
-
When two or more macro variables with the same name are defined in the passing information of an event job, the information defined first is passed to the succeeding job. For example, if the first macro variable is ?AJS2111?:EVID (which assigns an event ID to ?AJS2111?), and the second macro variable is ?AJS2111?:EVMSG (which assigns message information to ?AJS2111?), the information assigned to this macro variable will be an event ID (EVID).
-
If there is no information to be passed from the event job, or if the event job did not execute, the character string representing the macro variable name is passed to the macro variable defined in the succeeding job. For example, if the macro variable name is ?AJS2111?, the string ?AJS2111? is passed.
-