Page History

Events

Question: How can I trigger a job or a job chain based on a (series of) event(s)?

Introduction

In some cases it is necessary to trigger a job (or a job chain) based on (multiple) events (other jobs, monitored files...) which might even occur on different hosts.

JobScheduler provides a solution to set off events and to handle these events on an active instance of the event service JobScheduler.
You find the complete documentation in scheduler_events.pdf - Documentation. Especially how to define event handlers with JOE is described in chapter 4.1.3 XML Event Handlers
To show the usage of events we will draw up a simple scenario:

...

For this example, two different JobScheduler instances may be configured.
An event service (or event supervisor) and a Workload JobScheduler which is registered with that event service.
The event service is able to receive events from other JobScheduler instances on different servers and platforms.
It is possible also to have the event service and the Workload JobScheduler running in the same JobScheduler instance.
If different JobScheduler instances were used for eventing then it is required that these instances can communicate.

Requirements

The JobScheduler must run using a database. The events are stored permanently in the table "SCHEDULER_EVENTS". To customize an event handler some experience with XML and XSLT are required.

Instructions

• Unzip all files of events.zip or events_windows.zip into the ./config/live folder of your Workload JobScheduler installation. After unzipping you will have in the subfolder samples an subfolder events with the required JobScheduler objects to run the example.
• Edit ./config/scheduler.xml of the Workload JobScheduler and configure a JobScheduler as a Supervisor. The Supervisor is an attribute of the tag config. See Supervisor.
• In the installation directory of your workload JobScheduler create a folder files with two subfolders in and processed
• Unzip all files of events_supervisor.zip into the ./config folder of your instance of the event service JobScheduler installation. After unzipping you will have in the subfolder ./config/live/sos a subfolder events with all the objects required to run the event service. And a folder ./config/events that is used by the event handler.
• Edit config/events/example.event_class.xsl on the active instance of the event service JobScheduler and adjust the host and port parameters to those of the Workload JobScheduler. Copy the file to the folder ./config/events.
   

...

          <job>
            <script language="shell">
                <![CDATA[
          # run any shell script or command(s)
          echo hello world!
          
          # submit event to active instance of the eventservice JobScheduler
          $\{SCHEDULER_HOME\}/bin/jobscheduler_event.sh -x $? -e "example"
                ]]>
            </script>
            <run_time/>
          </job>

...

          <job order="yes">
              <script language="shell">
                  <![CDATA[
          # run any shell script or command(s)
          echo processing file $SCHEDULER_PARAM_SCHEDULER_FILE_PATH
          
          mv $SCHEDULER_PARAM_SCHEDULER_FILE_PATH files/processed
          
          # submit event to Supervisor Job JobScheduler
          $\{SCHEDULER_HOME\}/bin/jobscheduler_event.sh -x $? -e "example"
                  ]]>
              </script>
              <run_time/>
          </job>

...

        <job name="done_job">
            <script language="shell">
                <![CDATA[
        echo content of files/processed:
        ls -la files/processed
        
        echo deleting contents of files/processed
        rm -f files/processed/*
                ]]>
            </script>
            <run_time/>
        </job>

How it works

The job samples/events/simple_shell_job calls the script

  {{$\{SCHEDULER_HOME\}/bin/jobscheduler_event.sh -x $? -e "example"}}

to signal an event of call "example" to the active instance of the even tservice JobScheduler.
The -x switch sets the exit code of the previous shell command (echo in this case), and the -e switch sets the event class as properties of the event.
Other properties (which do not need to be set as parameters for the script jobscheduler_event.sh) include the name of the job that created the event, the name of the job chain (if the job was called in a chain), name of the order etc.

...

Each time the active instance of the event service JobScheduler receives an event it runs the JobScheduler_event_service job .
The job will then process all event handlers that follow the naming scheme:

...

     <remove_event>
       <event event_class="example"/>
     </remove_event>

The scheduler_event_functions.xsl.inc stylesheet

It is recommended to include scheduler_event_functions.xsl.inc into your own event handler stylesheets by adding:

...

• that a root level <commands> tag (element) is created in the resulting xml and
• that the stylesheet will return a valid (and well formed) xml result (returning nothing would result in an error)

Examples for match statements in event handlers

        {{<xsl:template match="events[event[@job_name='simple_shell_job' and @exit_code=0]]">}}

Matches if an event exists for job simple_shell_job with exit code 0.

        {{<xsl:template match="events[event[@job_name='simple_shell_job' and @exit_code>0]]">}}

Matches if an event exists for job simple_shell_job with an exit code greater than 0.

        {{<xsl:template match="events[event[@job_name='simple_shell_job'] and not(event[@job_name='file_job'])]">}}

Matches if an event exists for job simple_shell_job but no event for job file_job.

        {{<xsl:template match="events[event[@job_name='simple_shell_job'] or count(event[@event_class='other_events'])>=3]">}}
        

Matches if an event exists for job simple_shell_job or at least three events of event class other_events.

    {{<xsl:template match="events[event[@job_name='simple_shell_job']/params/param[@name='foo' and @value='bar'] ]">}}
  

Matches if an event exists for job simple_shell_job with an event parameter "foo" with the value "bar".

Downloads:

• scheduler_events.pdf - Documentation

• events.zip - job configuration files
• events_windows.zip - job configuration files (windows version)
• events_supervisor.zip - event handler files

...