Event rule definition
A scheduling event rule defines a set of actions that are to run upon the occurrence of specific event conditions. The definition of an event rule correlates events and triggers actions.
An
event rule definition is identified by a rule name and by a set of
attributes that specify if the rule is in draft state or not, the
time interval it is active, the time frame of its validity, and other
information required to decide when actions are triggered. It includes
information related to the specific events (eventCondition)
that
the rule must detect and the specific actions it is to trigger upon
their detection or timeout (action)
. Complex rules
may include multiple events and multiple actions.
When creating a scheduling object, you can define it in a folder. If no folder path is specified, then the object definition is created in the current folder. By default, the current folder is the root (\) folder, but you can customize it to a different folder path. You can also use the composer rename command to move and rename objects in batch mode that use a naming convention to a different folder using part of the object name to assign a name to the object.
Folders are also supported for the scheduling objects contained in event rules, such as workstations, jobs, job streams.
For an overview of scheduling event rules, see Running event-driven workload automation.
Syntax
You define event rules directly
in XML language with the use of any XML editor. You can configure
an environment variable on your computer to automatically open an
XML editor of your choice to work with event rule definitions. See The composer editor for details. The XML
describing the event rule must match the rule language schemas defined
in EventRules.xsd
and in FilteringPredicate.xsd
.
The
rule language schemas defined in eventRules.xsd
and
in FilteringPredicate.xsd
are used to validate your
rule definitions and, depending upon the XML editor you have, to provide
syntactic help. The files are located in the schemas
subdirectory
of the HCL Workload Automation installation
directory.
Notation | Meaning |
---|---|
(0, 1) | 0 indicates that the language element is optional. 1 indicates that if coded, only 1 occurrence is allowed. |
(0, n) | 0 indicates that the language element is optional. n indicates that if coded, multiple occurrences are allowed. |
(1, 1) | The first 1 indicates that the language element is required. The second 1 indicates that only 1 occurrence is allowed. |
(1, 2) | 1 indicates that the language element is required. 2 indicates that 2 occurrences are required. |
(1, n) | 1 indicates that the language element is required. n indicates that multiple occurrences are allowed. |
- eventRule name=" " ruleType=" " isDraft=" " (1, 1)
- description (0, 1)
- timeZone (0, 1)
- validity from=" " to=" " (0, 1)
- activeTime start=" " end=" " (0, 1)
- timeInterval amount=" " unit=" " (0, 1)
- eventCondition eventProvider=" " eventType=" " (1, n)
- scope (0, 1)
- filteringPredicate (0, 1)
- attributeFilter name=" " operator="eq" (0, n)
- value (1, n)
- attributeFilter name=" " operator="ne" (0, n)
- value (1, n)
- attributeFilter name=" " operator="le" (0, n)
- value (1, 1)
- attributeFilter name=" " operator="ge" (0, n)
- value (1, 1)
- attributeFilter name=" " operator="range" (0, 1)
- value (1, 2)
- attributeFilter name=" " operator="eq" (0, n)
- correlationAttributes (0, 1)
- attribute name=" " (1, n)
- action actionProvider=" " actionType=" " responseType=" " (0,
n)
- description (0, 1)
- scope (0, 1)
- parameter name=" "(1, n)
- value (1, 1)
- eventRuleSet (1, 1)
- eventRule (1, n)
eventRuleSet
language element also if
you have to enclose a single rule definition.
,
are saved in the database. The next time that you open a rule definition,
the comments that you wrote the first time are not there. Instead,
use the description
attribute to write any additional
information.Arguments
- eventRule
- The scheduling object that encloses the definition of multiple event conditions and multiple rule actions in addition to a set of attributes that define when the rule is activated. An
eventRule
element typically includes:- A number of required and optional rule attributes
- One or more event conditions
- One or more rule actions, although rules with no actions are also allowed
The rule attributes are:- Required attributes:
- name
- The value of the
name attribute is expressed as [folder/]name. The folder can be up
to 841 characters in length. For more information about the folder syntax, see Folder definition. The name of the event rule can be up to 40 alphanumeric
characters. The name of the event rule must start with a letter, and cannot contain blanks.
Underscore
(_)
and dash(-)
characters are allowed. - ruleType
- The
rule type is based on the number of events - and on their correlation
- that the rule is defined to detect. It can be one of the following:
- filter
- The rule is activated upon the detection of a single specific event.
- sequence
- The rule is activated when an ordered sequence of events arrives within a specific time interval.
- set
- The rule is activated when an unordered sequence of events arrives within a specific time interval.
Rules of type
set
andsequence
can also be activated on timeout, when one or more events arrive but the complete sequence does not arrive within the specified time window. - isDraft
- Specifies if the rule definition is currently enabled. Values can be yes or no. The default is no.
- Optional attributes:
- description
- A
description of the rule. It can be of up to 120 characters. Remember to write any XML special characters you might use in the XML special notation, such as:
&
for &>
for ><
for <"
for "
- timeZone
- Specifies
a different time zone for the execution of the rule. The default time
zone is the time zone defined on the workstation where the event processing
server resides. The application of daylight saving time (DST) has an impact on the
activeTime
interval (described next) of event rules:- On the day that DST is turned on (the clock is adjusted forward one hour) the rule operation times that fall within the hour absorbed by the application of DST are moved forward by one hour. For example, 2:10 becomes 3:10.
- On the day that DST is turned off (the clock is adjusted backward one hour) the rule operation times that fall within the hour duplicated by the application of DST are regarded without DST.
- validity
- Specifies
the rule validity period in terms of:
- from yyyy-mm-dd
- The validity period starts at midnight (of the rule time zone) of the specified day.
- to yyyy-mm-dd
- The validity period ends at midnight (of the rule time zone) of the specified day.
- activeTime
- Specifies
the rule activity time window within each day of validity in terms
of:
- start hh:mm:ss
- The beginning of the time window when the rule is active in hours, minutes, and seconds.
- end hh:mm:ss
- The end of the time window when the rule is active in hours, minutes, and seconds. If the time is earlier than in start hh:mm:ss, it refers to the next day.
- timeInterval
- Applies
to rules that include timeout actions. Specifies the time interval
within which all the events specified in the rule must have been received
before a corrective timeout action is started. The time interval starts
from the moment the first event specified in the rule is detected.
Specify the time interval in terms of:
- amount
- The length of the time interval in time units.
- unit
- The time unit in one of the following:
- hours
- seconds
- milliseconds
This attribute is mandatory when there are timeout actions in the event rule definition.
- eventCondition
- The
event condition is made up by the following attributes:
- Required attributes:
- eventProvider
- Identifies
the event monitoring provider that can capture a type of event. The
event providers supplied at installation time are:
- TWSObjectsMonitor
- Monitors the status of HCL Workload Automation plan objects. This event provider runs on every HCL Workload Automation agent and sends the events to the event processing server.
- TWSApplicationMonitor
- Monitors HCL Workload Automation processes,
file system, and message box.
TWSApplicationMonitor
events are supported on fault-tolerant agents only.For a detailed example about how to set up an event rule that monitors the used disk space, see Monitoring the disk space used by HCL Workload Automation
- FileMonitor
- Monitors events affecting files.
- DatasetMonitor
- Monitors events affecting Data sets.
- eventType
- Specifies the
type of event that is to be monitored. Every event can be referred to an event provider. The
following tables list the event types by event provider.
To see the properties of each event type, go to Event-driven workload automation event and action definitions.
TWSObjectsMonitor events. lists the
TWSObjectsMonitor
events.Table 2. TWSObjectsMonitor
events.Event type When the event is sent JobStatusChanged The status of a job changes JobUntil The latest start time of a job has elapsed JobSubmit A job is submitted JobCancel A job is canceled JobRestart A job is restarted JobLate A job becomes late JobPromoted A job in a critical network approaches the critical start time and has not yet started JobRiskLevelChanged - A new critical job is added to the plan with the risk level set to either high or potential
- The risk level for a job is set to high risk or potential risk and the risk level changes
- A critical job with the risk level set to either high or potential is removed from the plan
JobExceededMaximumDuration A job exceeds the maximum duration time established for the job JobDidnotReachMinimumDuration A job does not run long enough to reach the minimum duration time established for the job JobStreamStatusChanged The status of a job stream changes JobStreamCompleted A job stream has completed JobStreamUntil The latest start time of a job stream has elapsed JobStreamSubmit A job stream is submitted JobStreamCancel A job stream is canceled JobStreamLate A job stream becomes late WorkstationStatusChanged A workstation is started or stopped ApplicationServerStatusChanged WebSphere Application Server Liberty Base has stopped or is restarting ChildWorkstationLinkChanged The workstation defined in the event rule links or unlinks from its parent workstation (the parent workstation sends the event) ParentWorkstationLinkChanged The parent workstation links or unlinks from the workstation defined in the event rule (the child workstation sends the event) PromptStatusChanged A prompt is asked or replied ProductAlert The Symphony file in the workstation specified in the event rule contains a corrupt record Notice:Any change performed on a workstation referenced in a rule is not reported in the rule. For example if you modify, update, or delete a workstation that is referenced in a rule, the rule ignores the change and continues to consider the workstation as it was when it was included in the rule.
A rule with event type ParentWorkstationLinkChanged is not applicable when the Filters Workstation is set to agent, pool, dynamic pool, or remote engine and the ParentWorkstation attribute is set to broker. To monitor a link status change between the workload broker server and a workstation managed by the workload broker server, define a rule with event type equal to ChildWorkstationLinkChanged.A rule with event type equal to ChildWorkstationLinkChanged works only when the broker workstation is linked, unlinked, stopped, or started. If the change in the link status is due to a stop or start operation on the agent workstation with the StartupLwa and ShutDownLwa commands, no action is started. To monitor stop or start operations on agent workstations, define a rule with event type equal to WorkstationStatusChanged.
TWSApplicationMonitor events. lists the
TWSApplicationMonitor
events.Table 3. TWSApplicationMonitor
events.Event type When the event is sent MessageQueuesFilling A specified mailbox exceeds the percentage full value. TivoliWorkloadSchedulerFileSystemFilling The file system where the HCL Workload Automation instance is installed exceeds the disk usage percentage full value. TivoliWorkloadSchedulerProcessNotRunning A specified process is not running. FileMonitor events. lists theFileMonitor
events.Table 4. FileMonitor
events.Event type When the event is sent FileCreated A file is created FileDeleted A file is deleted ModificationCompleted A file is modified (the event is sent only if two consecutive monitoring cycles have passed since the file was created or modified with no additional changes being detected) LoggedMessageWritten A specific string is found in a file (this event can be used to monitor application or system logs) DatasetMonitor events. lists theDatasetMonitor
events.Table 5. DatasetMonitor
events.Event type When the event is sent ModificationCompleted A data set is modified (the event is sent only if two consecutive monitoring cycles have passed since the file was created or modified with no additional changes being detected) ReadCompleted A data set is read.
- Optional attributes:
- scope
- One or more qualifying attributes that describe the event. It can be up to 120 characters. The scope is automatically generated from what is defined in the XML. It cannot be specified by users.
- filteringPredicate
- The
filtering predicate sets the event conditions that are to be monitored
for each event type. It is made up by:
- attributeFilter
- The attribute filter is a particular attribute of the event type
that is to be monitored:
- Is defined by the following elements:
- name
- The attribute, or property name, of the event type that is to be monitored. Refer to Event providers and definitions for a list of property names for every event type.
- operator
- Can
be:
eq
(equal to)ne
(not equal to)ge
(equal or greater than)le
(equal or less than)range
(range)
- Includes one or more:
- value
- The value on which the operator must be matched.
- Is defined by the following elements:
Note: Every event type has a number of mandatory attributes, or property names. Not all the mandatory property names have default values. All the mandatory property names without a default value must have a filtering predicate defined.
- Required attributes:
- correlationAttributes
- The
correlation attributes provide a way to direct the rule to create
a separate rule copy for each group of events that share common characteristics.
Typically, each active rule has one rule copy that runs in the event
processing server. However, sometimes the same rule is needed for
different groups of events, which are often related to different groups
of resources. Using one or more correlation attributes is a method
for directing a rule to create a separate rule copy for each group
of events with common characteristics. Use with
set
andsequence
rule types.You can specify one or more attributes. Each is defined by:- attribute name=" "
- The object attribute that you are correlating.
- action
- The action that is to be triggered if the event is detected. Event
rule definitions with events but no actions are syntactically accepted,
although they may have no practical significance. You may save such
rules as draft and add actions later before they are deployed.
- Is defined by the following required attributes:
- actionProvider
- The
name of the action provider that can implement one or more configurable
actions. The action providers available at installation time are:
- GenericAction
- Runs non-HCL Workload Automation commands. The commands are run on the same computer where the event processor runs.
- MailSender
- Connects to an SMTP server to send an email.
- MessageLogger
- Logs the occurrence of a situation in an internal auditing database.
- TECEventForwarder
- Forwards the event to an external Tivoli Enterprise Console (TEC) server, or any other application capable of listening to events in TEC format.
- TWSAction
- Runs one of the following
conman
commands:- submit job (
sbj
) - submit job stream (
sbs
) - submit command (
sbd
) - reply to prompt (
reply
)
- submit job (
- TWSForZosAction
- Adds an application occurrence (job stream) to the current plan on HCL Workload Automation for Z. This provider is for use in HCL Workload Automation end-to-end scheduling
configurations.
The application description of the occurrence to be added must exist in the AD database of HCL Workload Automation for Z.
- actionType
- Specifies the
type of action that is to be triggered when a specified event is detected. Every action can be
referred to an action provider. The following table lists the action types by action provider.
To see the properties of each action type, go to Event-driven workload automation event and action definitions.
Table 6. Action types by action provider. Action provider Action types GenericAction RunCommand MailSender SendMail MessageLogger PostOperatorMessage TECEventForwarder TECFWD TWSAction reply (ReplyPrompt) sbd (SubmitAdHocJob) sbj (SubmitJob) sbs (SubmitJobStream) TWSForZosAction AddJobStream - responseType
- Specifies
when the action is to run. Values can be:
- onDetection
- The action starts as soon as all the events defined in the rule have been detected. Applies to all rule types. See also Rule operation notes.
- onTimeOut
- The
action starts after the time specified in
timeInterval
has expired but not all the events defined in the rule have been received. Applies toset
andsequence
rules only.Note that timeout actions are not run if you do not specify a time interval. The scheduler will however let you save event rules where timeout actions have been defined without specifying a time interval, because you could set the time interval at a later time. Until then, only actions with the
onDetection
response type are processed.Timeout actions for which a time interval was not defined are run only when the rules are deactivated. An event rule is deactivated in either of two cases:- The
planman deploy -scratch
command is issued - The rule is modified (it is then deactivated as soon as the
planman deploy
command is run)
- The
- Includes the following optional attributes:
- description
- A
description of the action. It can be of up to 120 characters. Remember to write any XML special characters you might use in the XML special notation, such as:
&
for &>
for ><
for <"
for "
- scope
- One or more qualifying attributes that describe the action. It can be of up to 120 characters. The scope is automatically generated from what is defined in the XML. It cannot be specified by users.
- Includes a list of one or more parameters, or property names. All action types have at least one
mandatory parameter. Every parameter is defined by:
- parameter name=" "
- See Action providers and definitions for a list of parameters, or property names, available for every action type.
- value
- See Action providers and definitions for a list of possible values or value types.
You can use variable substitution. This means that when you define action parameters, you can use the property names of the events that trigger the event rule to replace the value of the action property name. To do this, write the value for the action parameter you intend to substitute in either of these two forms:${event.property}
Replaces the value as is. This is useful to pass the information to an action that works programmatically with that information, for example the
schedTime
of a job stream.%{event.property}
Replaces the value formatted in human readable format. This is useful to pass the information to an action that forwards that information to a user, for example to format the
schedTime
of a job stream in the body of an email.
- event
- Is the name you set for the triggering
eventCondition
. - property
- Is the
attributeFilter
name in the filtering predicate of the triggering event condition. The value taken by the attribute filter when the rule is triggered is replaced as a parameter value in the action definition before it is performed.Note that you can use variable substitution also if no
attributeFilter
was specified for an attribute and also if the attribute is read-only.
job15
end in error and, when that happens, submit that job again. TheeventCondition
section of the rule is coded as follows:
Wildcards (* for multiple characters or ? for single characters) are used to generalize the event condition that you want to apply to all the job instances whose name starts with<eventCondition name=“event1” eventProvider=“TWSObjectsMonitor” eventType=“JobStatusChanged”> <filteringPredicate> <attributeFilter name=“JobName” operator=“eq”> <value>job15*<?value> </attributeFilter> <attributeFilter name=“Workstation” operator=“eq”> <value>*<?value> </attributeFilter> <attributeFilter name=“Status” operator=“eq”> <value>Error<?value> </attributeFilter> </filteringPredicate> </eventCondition>
job15
and to their associated workstation. Variable substitution is used in theaction
section to submit again the specific job that ended in error on the same workstation. Theaction
section is:<action actionProvider=“TWSAction” actionType=“sbj” responseType=“onDetection”> <description>Submit again the job that ended in error</description> <parameter name=“JobDefinitionName”> <value>${event1.JobName}<?value> </parameter> <parameter name=“JobDefinitionWorkstationName”> <value>${event1.Workstation}</value> </parameter> </action>
- Is defined by the following required attributes:
Examples
JOB7
has a file dependency on DAILYOPS.XLS
. As soon as
the file is received, JOB7
must start to process the file. The
following rule controls that JOB7
starts within one minute after the
transfer of DAILYOPS.XLS
is finished. If this does not happen, an email
is sent to the evening operator. This is accomplished by defining two sequential event
conditions that have to monitored: - The first event that triggers the rule is the creation of file
DAILYOPS.XLS
on the workstation to which it is to be transferred. As soon as this event is detected, a rule instance is created and a one minute interval count is begun to detect the next event condition. - The second event is the submission of
JOB7
. If this event fails to be detected within the specified time interval, the rule times out and theSendMail
action is started.
<?xml version=“1.0”?>
<eventRuleSet
xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance”
xmlns=“http://www.ibm.com/xmlns/prod?tws/1.0/event-management/rules”
xsi:schemaLocation=“http://www.ibm.com/xmlns/prod?tws/1.0/event-management/rules
EventRules.xsd”>
<eventRule
name=“myfolder/sample_rule”
ruleType=”sequence”
isDraft=“no”>
<description>An email is sent if job JOB7 does not start within
a minute after file DAILYOPS.XLS is created</description>
<timeZone>America/Indianapolis</timeZone>
<validity
from=“2007-01-01”
to=“2007-12-31” ?>
<activeTime
start=“20:00:00”
end=“22:00:00” ?>
<timeInterval
amount=“60”
unit=“seconds” ?>
<eventCondition
name=“DAILYOPS_FTPed_event”
eventProvider=“FileMonitor”
eventType=“FileCreated”>
<filteringPredicate>
<attributeFilter
name=“FileName”
operator=“eq”>
<value>c:?dailybus?DAILYOPS.XLS<?value>
</attributeFilter>
<attributeFilter
name=“Workstation”
operator=“eq”>
<value>ACCREC03<?value>
</attributeFilter>
<attributeFilter
name=“SampleInterval”
operator=“eq”>
<value>300</value>
</attributeFilter>
</filteringPredicate>
</eventCondition>
<eventCondition
name=“job_JOB7_problem_event”
eventProvider=“TWSObjectsMonitor”
eventType=“JobSubmit”>
<filteringPredicate>
<attributeFilter
name=“JobStreamWorkstation”
operator=“eq”>
<value>ACCREC03<?value>
</attributeFilter>
<attributeFilter
name=“Workstation”
operator=“eq”>
<value>ACCREC03<?value>
</attributeFilter>
<attributeFilter
name=“JobStreamName”
operator=“eq”>
<value>JSDAILY<?value>
</attributeFilter>
<attributeFilter
name=“JobName”
operator=“eq”>
<value>JOB7</value>
</attributeFilter>
</filteringPredicate>
</eventCondition>
<action
actionProvider=“MailSender”
actionType=“SendMail”
responseType=“onTimeOut”>
<description>Send email to evening operator stating job did not
start</description>
<parameter name=“To”>
<value>eveoper@bigcorp.com</value>
</parameter>
<parameter name=“Subject”>
<value>Job JOB7 failed to start within scheduled time on
workstation ACCREC03.</value>
</parameter>
</action>
</eventRule>
</eventRuleSet>
Note that the scope does not show the first time the rule
is defined.For more event rule examples, see Event rule examples .
See also
From the Dynamic Workload Console you can perform the same task as described in: