# Filtering Event Triggers

SailPoint activities can invoke many event triggers for all sorts of changes. However, sometimes we don't want all events to be triggered, rather we only want specific events to be launched in response to only specific event data.

As a common example, is the identity change event, where there can be many types of changes to identities on many types of attributes. With thousands of identities, and many attributes, this can lead to a lot of identity attribute change events triggered. We may only really be interested in changes to certain attributes, like manager, department, or lifecycle states. We may not care if other attributes change, and those may not necessitate triggering of the identity change event. For this we want to be able to control the event trigger subscription to filter and trigger only certain interested events.

When an event trigger is subscribed, it can optionally include a filter attribute. As an event is potentially triggered, it is matched against this filter. If the filter matches, then the event is triggered. If the filter does not match, then the event is not triggered.

# Filter Syntax

The filter that is configured uses Goessner JSONPath (opens new window) syntax. The filter is considered a matching filter, whereas any events which match the JSONPath filter will get triggered. Events in the subscription which do not match the filter would be excluded, and would not get triggered.

Here is a summary of Goessner JSONPath syntax:

JSONPath Description
$ The root object / element
@ The current object / element
. Child operator. Selects a child
.. Recursive descent. JSONPath borrows this syntax from E4X
* Wildcard. All objects / elements regardless their names
[] Subscript operator. In Javascript and JSON it is the native array operator
[,] Union operator. JSONPath allows alternate names or array indices as a set
[start:stop:step] Array slice operator borrowed from ES4
?() Applies a filter (script) expression
() Applies a filter (script) expression
&& Logical AND operator that evaluates true only if both conditions are true
|| Logical OR operator that evaluates true if at least one condition is true

# Example Filter

In this example, we'll use an example JSON payload sent from an identity attribute change event:

{
  "identity": {
      "id": "ee769173319b41d19ccec6cea52f237b",
      "name": "john.doe",
      "type": "IDENTITY"
  },
  "changes": [
      {
          "attribute": "department",
          "oldValue": "Sales",
          "newValue": "Marketing"
      },
      {
          "attribute": "manager",
          "oldValue": {
              "id": "ee769173319b41d19ccec6c235423237b",
              "name": "robert.brown",
              "type": "IDENTITY"
          },
          "newValue": {
              "id": "ee769173319b41d19ccec6c235423236c",
              "name": "mary.johnson",
              "type": "IDENTITY"
          }
      },
      {
          "attribute": "cloudLifecycleState",
          "oldValue": "active",
          "newValue": "terminated"
      }
  ]
}

Below is a chart of example JSONPath filters and what they will return. You can test these yourself using a JSON path evaluator tool (opens new window). Paste the example JSON above into the tool, make sure to select Goessner as the output type, and then try out each JSONPath listed below.

JSONPath Result
$.identity The identity object
$.identity.name The name of the identity
$[?($.identity.name == "john.doe")] The entire event if the identity name equals john.doe
$.changes All of the identity attribute change objects
$.changes[*].attribute A list of just the attribute names
$.changes[?(@.attribute == "department")] A list of change objects that have an attribute named department
$.changes[?(@.attribute == "cloudLifecycleState")].newValue The new value of the change to the cloudLifecycleState attribute
$.changes[?(@.attribute == "cloudLifecycleState" && @.newValue == "terminated")] A list of change objects that have an attribute name of cloudLifecycleState and a new value of terminated
$.changes[?(@.attribute == "cloudLifecycleState" || @.attribute == "department")] A list of change objects that have an attribute name of cloudLifecycleState or an attribute name of department

Ultimately, the JSONPath filter that you choose to apply depends on several factors:

  1. Event(s) being subscribed to
  2. Tenant configurations (identity attributes, sources, schema, etc.)
  3. Tenant data values for objects (identities, accounts, access, etc.)

For examples which allow you to test JSONPath syntax, see the References section.

# Configuration

The filter can be configured in the administrative user interface (coming Q4 2020) as well as the REST APIs. When configuring these via REST APIs, these are done during event-trigger subscription creation (opens new window) or updates (opens new window). The end result might look something like this (notice the filter property):

{

   "id": "90d6a04b-2dc6-4253-aaf0-cf3e3cd4e28e",
   "name": "Example Event",
   "description": "Example Event",
   "triggerName": "Identity Attributes Changed",
   "triggerId": "idn:identity-attributes-changed",
   "filter": "$.changes[?(@.attribute == \"department\")]",
   "type": "HTTP",
   "enabled": false,
   "responseDeadline": "PT1H",
   ...
}

# References