Legrand / Raritan / Server Technology Xerus™ JSON-RPC API: Event Rules and Actions

Legrand / Raritan / Server Technology Xerus™ JSON-RPC API

Loading...
Searching...
No Matches
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:

- `Device.SystemStartup`: Emitted after the device firmware has booted
- `UserActivity.admin.LoggedIn`: The `admin` user has logged in
- `Inlet.I1.Sensor.current.AboveUpperWarning`: The inlet current reading exceeds the upper warning threshold
- `Outlet.*.PowerControl.**`: Any outlet has been switched or power-cycled

# Python example: Create a rule to invoke user-defined action 'Action_001' when
# any user logs in
from raritan.rpc import event
event_engine = event.Engine("/event_engine", agent)
condition = event.Engine.Condition(
negate = False, # ignored
operation = event.Engine.Condition.Op.AND, # ignored
matchType = event.Engine.Condition.MatchType.ASSERTED, # only login, not logout
eventId = [ "UserActivity", "*", "LoggedIn" ],
conditions = [] # ignored
)
rule = event.Engine.Rule(
id = "", # assigned upon successful creation
name = "Any user has logged in",
isSystem = False,
isEnabled = True,
isAutoRearm = True, # ignored
hasMatched = False, # ignored
condition = condition,
actionIds = [ "Action_001" ],
arguments = []
)
ret, rule_id = event_engine.addRule(rule)
if ret != 0:
print("Creating rule failed, error code %d" % ret)
else:
print("Rule created successfully, new rule id: %s" % rule_id)
event::Engine
There is a single event engine instance reachable by a well known reference.
Definition EventEngine.idl:53
event::Engine::Condition
Condition is a logical combination of multiple events.
Definition EventEngine.idl:210
event::Engine::Rule
A Rule binds an action to a condition.
Definition EventEngine.idl:246

# 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.

# Python example: Create action to send out an email notification
from raritan.rpc import event
event_engine = event.Engine("/event_engine", agent)
action = event.Engine.Action(
id = "", # assigned upon successful creation
name = "Send mail to admin",
isSystem = False,
type = "SendSmtpMessage",
arguments = [
event.KeyValue("Recipient1", "admin@organization.example"),
event.KeyValue("OverrideSmtp", "0"),
event.KeyValue("UseCustomMessage", "0"),
event.KeyValue("CustomMessage", ""),
]
)
ret, action_id = event_engine.addAction(action)
if ret != 0:
print("Creating action failed, error code %d" % ret)
else:
print("Action created successfully, new action id: %s" % action_id)
event::Engine::Action
An action is a tuple of 'id' (unique within the scope of this event engine), 'name' which is unique a...
Definition EventEngine.idl:114
event::KeyValue
Helper that is used wherever key/value pairs are required.
Definition EventEngine.idl:18

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

- Action1 .. Action32: IDs of actions to execute

## Raise an Alarm (Action Type: "Alarm")

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

- AlarmNotfActions: IDs of notification actions, separated by semicolons
- AlarmReNotfEnabled: Enable re-scheduling of alarm notifications ("true"/"false")
- AlarmReNotfPeriod: Re-scheduling period in minutes (1..1440)
- AlarmReNotfMaxNum: Re-scheduling limit (1..1000, -1 for unlimited)
- AlarmAckActions: IDs of acknowledgement notification actions, separated by semicolons

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

- Operation: "on" to enable load shedding, "off" to disable it.
- LinkIds: Optional comma-separated list of PDU IDs, defaults to "1" (primary unit) if missing.

## Log Event Message (Action Type: "LogEventMessage")

- UseCustomMessage: "1" to use a custom log message
- CustomMessage: Custom message text for log message

## Send Email (Action Type: "SendSmtpMessage")

- Recipient: Recipient email address
- OverrideSmtp: "1" to use custom SMTP server, "0" to use the default server
- UseCustomMessage: "1" to use a custom mail text
- CustomMessage: Custom message text for notification message
- UseCustomMailSubject: "1" to use a custom mail subject
- CustomMailSubject: Custom subject for notification message

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

- SmtpHost: SMTP server name
- SmtpPort: SMTP server port
- SmtpFrom: SMTP sender mail address
- SmtpRetryCount: Number of sending retries (0..10)
- SmtpRetryInterval: Retry interval in minutes (1..60)
- SmtpUseAuth: "1" to use authentication, "0" otherwise
- SmtpUsername: SMTP user name
- SmtpPassword: SMTP password
- SmtpUseTls: "1" to enable SMTP over TLS (StartTLS)
- SmtpCaCertChain: CA certificate (TLS only)
- SmtpAllowOffTimeRangeCerts: "1" to allow certificates outside of their validity period

## Send SNMP Notification (Action Type: "SendSnmpTrap")

- SnmpNotfType: Notification type. One of "v2Trap", "v2Inform", "v3Trap", "v3Inform"
- SnmpTrapDest1: Primary trap destination, format: "<host>:<port>:<community>"
- SnmpTrapDest2: Optional second destination (SNMPv2 only)
- SnmpTrapDest3: Optional third destination (SNMPv2 only)
- SnmpNotfTimeout: Timeout in seconds for SNMPv2/SNMPv3 informs
- SnmpNotfRetries: Number of retries for SNMPv2/SNMPv3 informs
- SnmpNotfV3SecName: SNMPv3 security/user name
- SnmpNotfV3SecLevel: SNMPv3 security level. One of: "noAuthNoPriv", "authNoPriv", "authPriv"
- SnmpNotfV3AuthProto: SNMPv3 authentication protocol. One of: "md5", "sha", "sha224", "sha256", "sha384", "sha512"
- SnmpNotfV3AuthKey: SNMPv3 authentication passphrase
- SnmpNotfV3PrivProto: SNMPv3 privacy protocol. One of: "des", "aes", "aes192", "aes256", "aes192-3des", "aes256-3des"
- SnmpNotfV3PrivKey: SNMPv3 privacy passphrase

## Send Syslog Message (Action Type: "SendSyslogMessage")

- SyslogServerName: Syslog server name
- SyslogServerUseTcp: "1" to use TCP instead of UDP
- SyslogServerUseTls: "1" to use TLS encryption (TCP only)
- SyslogServerNoBsdCompat: "0" to use legacy BSD protocol (UDP only)
- SyslogServerPort: Syslog server UDP port
- SyslogServerTcpPort: Syslog server TCP port
- SyslogServerTlsPort: Syslog server TCP+TLS port
- SyslogServerCaCertChain: CA certiicate (TLS only)
- SyslogServerAllowOffTimeRangeCerts: "1" to allow certificates outside of their validity period

## Send SMS Message (Action Type: "SmsMessage")

- Destination: Recipient phone number
- UseCustomMessage: "1" to use a custom SMS text
- CustomMessage: Custom message text for SMS

## Internal Beeper (Action Type: "SwitchBuzzer")

- Operation: "on" to enable beeper, "off" to disable it
- LinkIds: Optional comma-separated list of PDU IDs, defaults to "1" (primary unit) if missing.

## Switch Outlets (Action Type: "SwitchOutlet")

- Operation: One of "on", "off", "cycle"

- OutletIndex: Comma-separated list of outlet indices (0-based) to switch. Items can be prefixed with a link ID (1 for primary unit, 2-8 for link units) to switch outlets in a cascade.

  Example: "0,2,2:4" switches outlets 1 and 3 of the primary unit and outlet 5 of the link unit with link ID 2.

## Switch Peripheral Actuator (Action Type: "SwitchPeripheralActuator")

- Operation: One of "on", "off", "cycle"

- SlotIndex: Comma-separated list of peripheral device slot indices (0-based). Items can be prefixed with a link ID (1 for primary unit, 2-8 for link units) to switch actuators in a cascade.

  Example: "2,2:0,2:8" switches actuator 3 of the primary unit and actuators 1 and 9 of the link unit with linkd ID 2.