3.12 Using an Event Notification in a Job

Jobs can be notified of a PlateSpin Orchestrate event in two ways.

3.12.1 Receiving Event Notifications in a Running Job


For a job to receive notifications, a job subscribes to an event and must remain running for the notification to occur.

How to subscribe to an event is accomplished using the subscribeToEvent() Job method, shown below:

        def subscribeToEvent( <event Name>, <Job callback method> )

In this method, <event name> is the string name of the event being subscribed to; <Job callback method> is the reference to a Job method. Joblets and globals are not supported.

Example: The following is an example of the subscribeToEvent() method.

             self.subscribeToEvent(  "vmhost" ,self.eventHandler)

In this example, vmhost is the name of the event and self.eventHandler is a reference to the callback method.


To unsubscribe, use the unscribeFromEvent() Job method. For the subscribe example shown above, the following is how to unsubscribe.


Callback Method Signature

          def <Job callback method>( self, context):

The callback method must be a Job method. The context argument is a dictionary containing name/value pairs. The dictionary contents passed to the callback vary depending on the event type.

Example: The following is an example of the callback method.

           def eventHandler(self,context):

In this method, context is the required dictionary argument passed to every callback. The contents of the dictionary vary depending on event type (for details, see Section 3.12.2, Event Types).

How an Event Notification Can Start a Job

You can create a schedule using the Job Scheduler or deploy a .sched file to start a job on an event notification. For more information, see Section 8.0, Job Scheduling or The PlateSpin Orchestrate Job Scheduler in the PlateSpin Orchestrate 2.6 Development Client Reference.

The job to be started must match a required job argument signature where the job must define at least one job argument.

The required job argument must be called “context” and be of type Dictionary. The contents of the dictionary vary depending on event type ( refer to "Event Types " below for details).

The contents of EventResponse.jdl is an example of a job and policy that can be scheduled on an event notification:

1class EventResponse(Job):
3   def job_started_event(self):
4       context = self.getFact("jobargs.context")
6       print "Context:"
7       keys = context.keys()
8       keys.sort()
9       for k in keys:
10          v = context[k]
11          print "  key(%s) type(%s) value(%s)" % (k,type(v),str(v))

Line 4: This line pulls out the job argument for the event context.

Lines 6-11: These lines print out the contents of the context dictionary.

The contents of EventResponse.policy are shown below:

2  <jobargs>
3    <fact name="context" type="Dictionary"
4         description="Dictionary containing the context for the event " />
5   </jobargs>

Lines 3-4: These lines define the required job argument containing the Event context. The running job receives the job argument named context with the dictionary completed by the PlateSpin Orchestrate Event Manager with the context that matches the trigger rules.

3.12.2 Event Types

Event Objects

Event objects are defined in an XML document and deployed to a server and managed using the Orchestrate Development Client. In the Development Client, these objects are shown in the tree view.

The callback method context argument dictionary contains every grid object type and a value or list of values. The dictionary depends on the event XML definition and the matching grid objects of the <trigger> rule.

The following example event file (vmhost.event) shows the contents of the dictionary that will be passed as either a jobarg to a job to be scheduled to start, or as a argument to an event callback for a running job.

3   <context>
4      <vmhost />
5      <user>system</user>
6   </context>
8   <trigger>
9       <gt fact="vmhost.resource.loadaverage" value="2" />
10   </trigger>

Lines 3-6: Define the context for the Event object.

Line 4: Defines the match for the trigger rule that iterates over all vmhosts.

Line 5: Defines the context, and contains the user grid object named system.

Assuming that there are 10 vmhosts named "vmhost1, vmhost2, ... vmhost10, but only the first three vmhosts match the trigger rule, the context includse a list of the matching vmhosts. In this case, the context dictionary contains the following:

1          "vmhost" : [  "vmhost1", "vmhost2", "vmhost3" ],
2         "user" : "system",
3          "repository" : "" ,
4          "resource" : "",
5          "job" : ""

Line 1: List of the matching VM Hosts that passed the <trigger> rule.

Line 2: The user object that is defined in the <context> XML. In this case, system.

Lines 3-5: These grid objects are not defined in the context. Their value is empty.

In this example, the dictionary is passed as a job argument to a scheduled job that triggers on the event or is passed to a callback method in a running job that has subscribed to the event.

Built-in Events

Built-in events occur when a managed object comes online or offline or when that object has a health status change. For built-in events, the dictionary contains the name of the grid object type. The value is the name of the grid object.

The PlateSpin Orchestrate built-in events are named as follows:








For example, when the resource xen1 comes online, the built-in event called RESOURCE_ONLINE is invoked. Any scheduled jobs are started and any running jobs that have subscribed are invoked. The context dictionary contains the following:

                   "resource" : "xen1"

The dictionary shown above is passed as a job argument to a scheduled job that triggers on the event or that is passed to a callback method in a running job that has subscribed to the event.

External Events

External events are events that are invoked by an outside process. In this case, the callback method context dictionary is free form and contains what was supplied to the external event.

For example, if the external event was invoked with a dictionary mapping of two elements like this:

               { "name" : "foo", "age" : 40 }

The corresponding JDL callback method receives the same dictionary.

Example: The following example of an external event subscribes to a previously deployed event named vmhost. This job continue running until the job is canceled or an error occurs.

1 EVENT = "vmhost"
3 class EventDaemon(Job):
5   def job_started_event(self):
7       self.setFact("job.autoterminate",False)
8       self.subscribeToEvent(EVENT,self.eventHandler)
9       print "Waiting for notification for event '%s'" % (EVENT)
12  def eventHandler(self,context):
13       print "Context:"
15       keys = context.keys()
16       keys.sort()
17       for k in keys:
18          v = context[k]
19          print "  key(%s) type(%s) value(%s)" % (k,type(v),str(v))

Line 7: Sets the autoterminate fact so that the job remains running upon completion of the job_started_event().

Line 8: Subscribes to the named event vmhost and passes in a reference to the Job method eventHandler() to callback on when the event notification occurs.

Line 12: Definition of the callback method to invoke when the event notification occurs.

Lines 15-19: prints out the context dictionary received upon event notification.