Raritan PX2/PX3 JSON-RPC API
Event Rules and Actions

Event rules and actions are configured with the EventEngine interface at the well-known URI /event_engine. Event rules select a subset of possible events and define one or more actions that should be executed for once for each matching event. Supported event actions include sending SNMP traps or emails, switching outlets or raising alarms.

Event Rules

Event rules are managed with the listRules, addRule, modifyRule, enableRule, disableRule and deleteRule methods. Rules connect a trigger condition (a subset of possible events) with one or more actions.

Note
The IDL interface was designed for defining complex rules that perform logical operations to combine multiple event conditions. However, as of now this is not supported by the firmware. Event rules can only have a single trigger conditions, possibly using wildcards to select entire subtrees.

Events are organized in a hierarchical structure and identified by path. Event IDs can contain dynamic components like user names, outlet numbers or sensor types. Event IDs can contain the wildcard * to match an aribtrary value for a single path element, or end with the ** wildcard to select a complete subtree of events. The list of supported event conditions strongly depends on the device model and configuration. The easiest way to find the event ID for a particular event is to configure a rule in the web GUI and then inspect it with JSON-RPC.

A few examples for event IDs are:

1 # Python example: Create a rule to invoke user-defined action 'Action_001' when
2 # any user logs in
3 
4 from raritan.rpc import event
5 
6 event_engine = event.Engine("/event_engine", agent)
7 
8 condition = event.Engine.Condition(
9  negate = False, # ignored
10  operation = event.Engine.Condition.Op.AND, # ignored
11  matchType = event.Engine.Condition.MatchType.ASSERTED, # only login, not logout
12  eventId = [ "UserActivity", "*", "LoggedIn" ],
13  conditions = [] # ignored
14 )
15 
16 rule = event.Engine.Rule(
17  id = "", # assigned upon successful creation
18  name = "Any user has logged in",
19  isSystem = False,
20  isEnabled = True,
21  isAutoRearm = True, # ignored
22  hasMatched = False, # ignored
23  condition = condition,
24  actionIds = [ "Action_001" ],
25  arguments = []
26 )
27 
28 ret, rule_id = event_engine.addRule(rule)
29 if ret != 0:
30  print("Creating rule failed, error code %d" % ret)
31 else:
32  print("Rule created successfully, new rule id: %s" % rule_id)

Event Actions

Event actions define what to do in case an emitted event matches a rule. There are many types of actions, all with specific configuration parameters. Action parameters are specified as key-value pairs in the arguments vector.

1 # Python example: Create action to send out an email notification
2 
3 from raritan.rpc import event
4 
5 event_engine = event.Engine("/event_engine", agent)
6 
7 action = event.Engine.Action(
8  id = "", # assigned upon successful creation
9  name = "Send mail to admin",
10  isSystem = False,
11  type = "SendSmtpMessage",
12  arguments = [
13  event.KeyValue("Recipient1", "admin@organization.example"),
14  event.KeyValue("OverrideSmtp", "0"),
15  event.KeyValue("UseCustomMessage", "0"),
16  event.KeyValue("CustomMessage", ""),
17  ]
18 )
19 
20 ret, action_id = event_engine.addAction(action)
21 if ret != 0:
22  print("Creating action failed, error code %d" % ret)
23 else:
24  print("Action created successfully, new action id: %s" % action_id)

The following sections list the most important action types and their parameters. The list is not complete; check the web GUI to see all supported actions.

Execute an Action Group (Action Type: "ActionGroup")

Executes up to 32 other actions

Raise and Alarm (Action Type: "Alarm")

Supported action types for notification and acknowledgment actions: SendSmtpMessage, SendSyslogMessage, SmsMessage, ExternalBeeper, SwitchBuzzer.

Enable/Disable PDU Load Shedding (Action Type: "SetPduLoadShedding")

Log Event Message (Action Type: "LogEventMessage")

This action has no parameters.

Send Email (Action Type: "SendSmtpMessage")

The following parameters are only required if OverrideSmtp is set to "1":

Send SNMP Notification (Action Type: "SendSnmpTrap")

Send Syslog Message (Action Type: "SendSyslogMessage")

Send SMS Message (Action Type: "SmsMessage")

Internal Beeper (Action Type: "SwitchBuzzer")

Switch Outlets (Action Type: "SwitchOutlet")

Switch Peripheral Actuator (Action Type: "SwitchPeripheralActuator")