TWSObjectsMonitor events

TWSObjectsMonitor events are:
  • Job Status Changed
  • Job Until
  • Job Submitted
  • Job Cancelled
  • Job Restarted
  • Job Late
  • Job Promoted
  • Job Risk Level Changed
  • Job Exceeded Maximum Duration
  • Job Did not Reach Minimum Duration
  • Job Stream Status Changed
  • Job Stream Completed
  • Job Stream Until
  • Job Stream Submitted
  • Job Stream Cancelled
  • Job Stream Late
  • Workstation Status Changed
  • Application Server Status Changed
  • Child Workstation Link Changed
  • Parent Workstation Link Changed
  • Prompt Status Changed
  • ProductAlert
These events are generated by batchman (or mailman for the workstations) and written in a mailbox file named monbox.msg. The scheduling objects are monitored as follows:
  • Jobs are monitored by the workstation where they run
  • Job streams are monitored by the master domain manager
  • Workstations monitor themselves
  • Local prompts are monitored by the workstation running the job or job stream that have a dependency on the prompt
  • Global prompts are monitored by the master domain manager

Using operator instructions as variables

You can use operator instructions as variables for job and job stream events of TWSObjectsMonitor type. The operator instructions are extracted from the description and documentation fields of jobs and job streams definitions, as these fields can contain important information about the definitions, such as runbooks, recovery processes and support contacts.

Using operator instructions as variables in event definitions enhances the reusability of event rules, and supports automated error recovery by providing relevant operational data at the point of failure.

You can extract either the entire content of the operator instructions, or specific key-value pairs. The syntax varies according to your purpose:
Retrieving the entire field content
Use the following syntax to retrieve the full content of the operator instructions:
%{<event>.OpInstr}
For example you can add an Send mail action to an event rule, and use the following syntax in the email body to retrieve the full runbook for a job:
%{jobStatChEvt1.OpInstr}
If the job fails, the entire runbook text from the job definition populates the body of the email.
Retrieving specific key-value pairs
To enable the retrieval of specific values from the operator instructions, the description or documentation fields of a job or job stream definition must contain the key-value pair, with a new line separating the pair from other instructions or text. Key-value pairs must contain a key, a separator (either equal sign "=" or colon sign “:”), and a value. The key must be a unique word, and it cannot contain spaces. For example:
First step: Check connection
escalation_teams_emails=support.db@acme.it; support.it@acme.it
Last step: Run cleanup script

In this case, you can only use escalation_teams_emails as variable.

The syntax requires you to specify the exact key defined in the job or job stream description field:
%{<event>.OpInstr.<key>}
Note: The syntax is limited to one level of key retrieval. Nested retrieval is not permitted.
For example, in the to field of a Send mail action within an event rule, you can use the following syntax to extract a specific recipient from the description field of a job:
%{jobStatChEvt1.OpInstr.escalation_teams_emails}
If the job fails, the recipients support.db@acme.it and support.it@acme.it receive the email.
Only the first matching occurrence is used as key-value pairs. For example, if you use the same syntax as above, and the operator instructions of the job contain the following information:
First step: Check connection
escalation_team_email=support.db@acme.it
Last step: Run cleanup script
escalation_team_email=support.it@acme.it
In this case, only the support.db@acme.it email address receives the email in case of job failure.

To exploit event rule reusability, you can define a generic event rule that triggers on any job or job stream status change or failure. This enables the single rule to perform different actions based on the information provided in the operator instructions of the failing object.

Key-value pairs retrieval hierarchy
Job and job stream information is retrieved according to the item related to the event:
  • If the event is related to a job stream, the operator instructions of a job stream are used as key-value pairs.
  • If the event is related to a job, the operator instructions of a job instance are used as key-value pairs. If the description or documentation fields of the job instance do not contain a matching key, the operator instructions of the job definition are used as key-value pairs. If nothing matches the key again, the operator instructions of the job stream are used as key-value pairs.

Working with WorkstationStatusChanged events

The event is sent when a workstation is started or stopped. But the following operational differences exist depending on the type of workstation that is monitored:
  • For a fault-tolerant agent the event is sent when the workstation is started or stopped.
  • For a dynamic workload broker workstation the event is sent also when it is linked or unlinked (as these commands also start or stop the workstation).
  • For a dynamic pool workstation the event is never sent (even if the hosting dynamic workload broker is stopped) because there is no monitoring on this type of workstations.

Examples

The rule in the following example submits job stream RJS_102739750 on workstation NC125102 as soon as all the jobs of job stream RCF_307577430 of workstation NA022502 are in the RUNNING or SUCCESSFUL status.
<?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="TWS_PLAN_EVENTS_JOB_STATUS_CHANGED" ruleType="filter" isDraft="no">
      <description>Event: Job Status Changed; Action: Submit job stream</description>
      <timeZone>Europe/Rome</timeZone>
      <validity from="2023-04-24" to="2024-04-24" />
      <activeTime start="00:00:00" end="12:00:00" />
      <eventCondition name="jobStatChgEvt1" 
                      eventProvider="TWSObjectsMonitor" 
                      eventType="JobStatusChanged">
      <scope>* # JOBSTREAMVALUE . * [RUNNING, SUCCESSFUL]</scope>
         <filteringPredicate>
          <attributeFilter name="JobStreamWorkstation" operator="eq">
         <value>NA022502</value>
          </attributeFilter>
         <attributeFilter name="JobStreamName" operator="eq">
         <value>RCF_307577430</value>
         </attributeFilter>
         <attributeFilter name="JobName" operator="eq">
         <value>*</value>
         </attributeFilter>
         <attributeFilter name="Priority" operator="ge">
         <value>10</value>
         </attributeFilter>
         <attributeFilter name="Monitored" operator="eq">
         <value>true</value>
         </attributeFilter>
         <attributeFilter name="Status" operator="eq">
         <value>Running</value>
         <value>Successful</value>
         </attributeFilter>
         <attributeFilter name="Login" operator="eq">
         <value>TWS_user</value>
         </attributeFilter>
         </filteringPredicate>
      </eventCondition>
      <action actionProvider="TWSAction" actionType="sbs" responseType="onDetection">
         <description>Launch an existing TWS job stream</description>
         <scope>SBS NC125102#RJS_102739750</scope>
         <parameter name="JobStreamWorkstationName">
            <value>NC125102</value>
         </parameter>
         <parameter name="JobStreamName">
            <value>RJS_102739750</value>
         </parameter>
      </action>
   </eventRule>
</eventRuleSet>
The rule in the following example submits job RJR_30411 on workstation NC122160 as soon as job stream RJS_102739750 of workstation NC125102 is submitted.
<?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="TWS_PLAN_EVENTS_JOB_STREAM_SUBMITTED" ruleType="filter" isDraft="no">
      <description>Event: Job Stream Submitted; Action: Submit job</description>
      <eventCondition name="jsSubEvt1" 
                      <eventProvider="TWSObjectsMonitor" 
                      <eventType="JobStreamSubmit">
      <scope>WORKSTATIONVALUE # JOBSTREAMVALUE</scope>
         <filteringPredicate>
          <attributeFilter name="JobStreamWorkstation" operator="eq">
         <value>NC125102</value>
          </attributeFilter>
         <attributeFilter name="JobStreamName" operator="eq">
         <value>RJS_102739750</value>
         </attributeFilter>
         <attributeFilter name="Priority" operator="range">
         <value>15</value>
         <value>30</value>
         </attributeFilter>
         <attributeFilter name="LatestStart" operator="le">
         <value>2024-04-26</value>
         </attributeFilter>
         </filteringPredicate>
      </eventCondition>
      <action actionProvider="TWSAction" actionType="sbj" responseType="onDetection">
         <description>Launch an existing TWS job stream</description>
         <scope>SBJ NC122160#RJR_30411 INTO NC122160#JOBS</scope>
         <parameter name="JobUseUniqueAlias">
            <value>true</value>
         </parameter>
         <parameter name="JobDefinitionName">
            <value>RJR_30411</value>
         </parameter>
         <parameter name="JobDefinitionWorkstationName">
            <value>NC122160</value>
         </parameter>
      </action>
   </eventRule>
</eventRuleSet>