Subscribe

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.

             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.

Unsubscribe

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

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

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.

           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.5 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):
2
3   def job_started_event(self):
4       context = self.getFact("jobargs.context")
5
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))

The contents of EventResponse.policy are shown below:

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

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.

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

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" : ""
         }

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.

1 EVENT = "vmhost"
2
3 class EventDaemon(Job):
4
5   def job_started_event(self):
6
7       self.setFact("job.autoterminate",False)
8       self.subscribeToEvent(EVENT,self.eventHandler)
9       print "Waiting for notification for event '%s'" % (EVENT)
10
11
12  def eventHandler(self,context):
13       print "Context:"
14
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))