HCL Workload Automation, Version 9.4

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.

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.

The following table lists all the language elements used for defining an event rule. Table 1 explains the meaning of the notation that follows each language element. n represents an unbounded number.
Table 1. Explanation of the notation defining the number of occurrences for a language element.
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)
    • 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)
Event rule definitions are grouped into event rule sets.
  • eventRuleSet (1, 1)
    • eventRule (1, n)
Use the eventRuleSet language element also if you have to enclose a single rule definition.
Note: None of the comments that you write in the XML, in the form <!--text-->, 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

The keywords that describe an event rule are the following XML tags:
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 name of the event rule. It can be up to 40 alphanumeric characters in length, it 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 and sequence 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:
    • &amp; for &
    • &gt; for >
    • &lt; for <
    • &quot; for "
    and so on.
    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.
    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.

    Table 2 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
    An event is not sent if the critical job is in the job stream named JOBS.
    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 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
    Note:

    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.

    Table 3 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 percentage full value.
    TivoliWorkloadSchedulerProcessNotRunning A specified process is not running.
    Note: Only unplanned stop will trigger the event.
    Table 4 lists the FileMonitor 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)
    Table 5 lists the DatasetMonitor 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.
    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.
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 and sequence 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)
    TWSForZosAction
    Adds an application occurrence (job stream) to the current plan on IBM Workload Scheduler for z/OS. 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 IBM Workload Scheduler for z/OS.

    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 to set and sequence 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)
    In either case the rule is first deactivated and then reactivated. At this time all pending actions are executed.
  • 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:
    • &amp; for &
    • &gt; for >
    • &lt; for <
    • &quot; for "
    and so on.
    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.

    Where:
    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.

    For example, the task of an event rule is to detect when any of the jobs that have a name starting with job15 end in error and, when that happens, submit that job again. The eventCondition section of the rule is coded as follows: 
    <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>
    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 job15 and to their associated workstation. Variable substitution is used in the action section to submit again the specific job that ended in error on the same workstation. The action 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>

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:
  1. 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.
  2. 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 the SendMail 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=“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:

Creating an event rule.