The following lists definitions for the Rule Engine that is built into the Sequence Controller. For Identity Authority Manager (IdAM) specific concepts and key terms, see IdAM Concepts and for more information on general PKI definitions and EJBCA specific concepts, refer to the EJBCA Documentation on EJBCA Concepts.

Rule Engine

The Identity Authority Manager Rule Engine is a highly customizable and configurable system for complex event processing. The rule engine allows you to filter, enrich, and transform incoming messages from the adapter. You are also able to trigger various actions, for example, notifications or communication with external systems.

The Rule Engine framework for building event-based workflows includes the following main components:

  • Message: Any incoming event, for example, incoming data from the Device Adapter or Trust-Service Adapter.
  • Rule Node: A function executed on an incoming message. Different Rule Node types can filter, transform, enrich, or execute actions on incoming messages.
  • Rule Chain: A chain of nodes, connected with each other with relations, allowing the outbound message from a rule node to be sent to the next connected rule node.

Examples of use cases that can be configured using Rule Chains are data validation and modification for attributes before saving to a database, triggering actions based on device life-cycle events, or load additional data required for processing. 

Rule Engine Message

The Rule Engine Message is a serializable, immutable data structure that represents various messages in the system. For example:

A Rule Engine Message consists of the following fixed parameters: 

  • msg: The actual message.
  • method: The method that is triggered by this message. Mandatory).
  • params: Status information about the sender. Mandatory. This section can be followed by a variable list of parameters.
  • metadata: List of key-value pairs with additional data about the message.

The following displays an example message format.

{
   "method": "request_status",
   "params": {
      "rule_chain": "demo",
      "payload": {
         "status_code": "200",
         "status_message": "Status Idle, waiting for requests."
      },
      "error": false,
      "error_code": null,
      "error_message": null,
      "error_text": null
   }
}
CODE

Rule Node

A Rule Node is a basic component of Rule Engine that processes a single incoming message at a time. The Rule Node the main logical unit of the Rule Engine and can filter, enrich, and transform incoming messages, and perform actions or communicate with external systems like the CA Service. 

Rule Chain

Rule Chain is a logical group of rule nodes and their relations. The rule nodes are connected to each other with relations, allowing the outbound message from a rule node to be sent to the next connected rule node.

A rule chain can be configured to, for example, save messages to the database, raise an alarm if triggered, and log failure to the console in case of errors. 

Rule Node Configuration

Rule Nodes may have specific configuration parameters depending on their implementation. For example, the Filter - script rule node is configurable via a custom JS function that processes incoming data, and the External - send email node configuration allows specifying mail server connection parameters.

To open the Rule Node configuration panel, double-click the node in the Rule Chain editor.

Test JavaScript Functions

Some rule nodes have specific UI features that allow users to test JS functions. Click Test Filter Function to open the JS Editor that allows you to substitute input parameters and verify the output of the function.

You can define the following:

  • Message Type in the top-left field.
  • Message payload in the Message section.
  • Metadata in the Metadata section.
  • The actual JS script in the Filter section.

To test a function, click Test to display the test output in the Output section.