User-Defined Actions

User defined actions are created using the defaction keyword. The defaction keyword closely follows the syntax of functions. User-defined actions allow for data preprocessing and the execution of one or more actions. User-defined actions are useful for wrapping actions to allow for composite actions or a cleaner syntax surrounding existing actions for a common use case.

defaction(<parameters>) {
  <declaration0>
  ...
  <declarationN>

  <action block>
}

The parameters are a possibly empty, comma-separated list of variable names. All parameters can be assigned a default value. Zero or more declarations can be included to prepare data for the action block.

The action block is the same as the action block in a rule. Any action, including a user-defined action, can be used in the action block. Actions can be simple or compound. A simple action is a valid action block. For example, the following defines an action called send_warning using the event:send action:

send_warning = defaction(msg, eci) {
  event:send({"eci":eci, "domain":"message", "type":"warning", "attrs": {"warning":"Warning!" + msg}});
}

Compound actions work the same as a rule. Suppose, for example, that in addition to putting up a notification, you wished to use send_directive:

send_warning = defaction(msg, eci) {

  every {
    event:send({"eci":eci, "domain":"message", "type":"warning", "attrs": {"warning":"Warning!" + msg}});

    send_directive("a_warning_was_given", {"message":"msg"})
  }
}

The variable send_warning only has meaning in an action context within a rule. Because user-defined actions are first-class values (i.e., they can be returned as the result of executing an expression), they can be passed into functions or other user-defined actions and returned as the result from a function. You can thus write recursive actions.