Defining event rules

About this task

When you define an event rule, you specify one or more events, a correlation rule, and one or more actions. To define event rules you can use:
  • The composer command line
  • The Dynamic Workload Console
  • A set of APIs described in a separate document

    You can try out the REST API services and the operations available for each on Swagger Docs by connecting to: https://start.wa.ibmserviceengage.com/twsd/. Click List Operations to view the operations available with the service, and then click Expand Operations to view details such as, the implementation notes, parameters, and response messages for each method. At the end of the details you can find a Try it out! button to see the operation in action.

    You can also access some HCL Workload Automation REST API samples here: REST API samples.

In composer, you edit the rules with an XML editor of your choice (preferable but not mandatory) since event rule definitions are made using XML syntax.

The explanation of how you use composer to define event rules is in Event rule definition, while the explanation of how you use the Dynamic Workload Console can be found in: Creating an event rule

Event rule definitions are saved in the HCL Workload Automation database like all other scheduling objects. You can save them as:
Draft
The rule is saved in the database but is not ready yet to be deployed and activated.

This state is determined by the isDraft=yes attribute.

Not draft
This rule is being deployed or is ready to be deployed in the scheduling environment.

This state is determined by the isDraft=no attribute.

Non-draft rules are ready to be activated. The rule builder calculates the status of each rule. The status can be:
  • active
  • not active
  • update pending
  • update error
  • activation pending
  • activation error
  • deactivation pending
  • deactivation error
The scheduler periodically (every five minutes or in accordance with a time set in the deploymentFrequency global configuration option) scans the database for non-draft rules and builds rule configuration files for deployment. The new monitoring configurations are downloaded to the agents (each agent gets its own configuration file containing strictly the rules it is to run) only if there have been changes since the previous configuration files.

As an additional feature, a planman deploy command is available to deploy rules manually at any time.

The time required for deployment increases proportionally with the number of active rules to deploy. If you need to manually deploy a large number of new or changed rules, and you are concerned with keeping the deployment time low, run planman deploy -scratch to reduce the deployment time.

You can deploy and undeploy rules as you need by setting the isDraft attribute to no or to yes with composer or with the Dynamic Workload Console.

Based on their characteristics, rules are classified as:
filter
The rule is activated upon the detection of a single specific event.
sequence
The rule is activated when an ordered group of events is detected or fails to complete within a specific time interval.
set
The rule is activated when an unordered group of events is detected or fails to complete within a specific time interval.

Filter rules are based on the detection of one event such as a job being late, an HCL Workload Automation workstation going down, a file being modified, a job stream completing its run successfully, and so on.

Set and sequence rules are based on the detection of more events. Optionally, they can be based on a timeout condition. A rule times out when the first event(s) in a sequence or part of the events in a set are received, but not all the events are received within a specified time interval counted from when the first event was received.

Rule definitions may include attributes that specify a validity period and an activity time window within each day of validity. If you do not specify these attributes, the rule is active perpetually at all times once it is deployed and until it is changed back to draft status or deleted from the database.

You can use variable substitution. This means that when you define action parameters, you can use attributes of occurrences of events that trigger the event rule 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.

You can see the use of variable substitution in some of the following sample definitions, where attribute filter values are replaced in email subject and body matters.