Python Scripts for Event Manager Actions

The Event Manager defines events that can occur. Each event can be associated with one or more actions that run when the event is triggered. Similarly, each action can be associated with one or more events. That association is called an event-action.

When an event is triggered, the associated event-actions are queued to run. We call this queued event-action an event-action instance. Conceptually, the event-action instance begins when the event triggers and it is complete when the action finishes running.

If the action is a Python script, the script defines an EventHandlerState class. A new EventHandlerState class object instance is created for each event-action that is defined. When an event-action instance is run, the do_event_action() method is run. If the same event-action triggers again, the same EventHandlerState object instance is used and the do_event_action() method is run again.

  • If the same action is used in a different event, that is a different event-action and a different EventHandlerState class object instance is created for that event-action.
  • If the same script is used in a different action, that is a different event-action and a different EventHandlerState class object instance is created for that event-action.

EventHandlerState lifecycle:

  • The first time an instance of this event-action is queued to run, the script is loaded as a module if it hasn’t already been loaded.
  • An EventHandlerState object instance is created for this event-action. The object instance will be used for all the event-action instances that run.
  • The __init__() method is called when the object is created.
  • The do_event_action() method is run repeatedly for each event-action instance. The CimEMEvent parameter has information about the event that triggered this event-action instance.
  • When the Event Manager is shutdown or when it reloads the script, the do_shutdown() method is run and then the EventHandlerState object instance reference is released and the script/module is unloaded.

The script is loaded as a module. This has the following implications:

  • The script is loaded once, when the first event-action instance that uses it is performed.
  • Each EventHandlerState class is in its own module.
  • You can define module level variables in the script, outside of the class. All event-actions that use this script share those variables.
  • One script can import another script and access its variables and functions using the module name prefix.

The EventHandlerState class has the following methods that you can implement:

def __init__(self, event_action_context: cimplicity.EMEventActionContext)

This method is called by Python when the class object instance is created. The EMEventActionContext parameter has information such as the event ID and the action ID of the event-action of the object instance. If the event-action was defined as part of a CIMPLICITY class, the object ID and attributes are also available.

In this method, you can do any initialization that should happen for each defined event-action.

def do_event_action(self, event_data: cimplicity.CimEMEvent)

This method is called by the Event Manager when an event-action instance is run. The Cim parameter has information about the event that triggered the action. There are also special members for the different event types: alarm events, point events, or the shutdown event.

def do_shutdown(self, event_data: cimplicity.CimEMEvent)

This method is called by the Event Manager when the Event Manager is shutting down or is reloading the scripts. (Script reload happens for changed scripts when you press the Update button in the Event Editor.)

In this method you can, for example, do any cleanup for things that you did in the __init__ method.