# 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

# Example Filter

To best illustrate how to apply, JSONPath syntax, is sometimes helpful to have an example. 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"
      }
  ]
}

While the example here is using an identity changed event, the same principles can apply other events as well. Their syntax may be a little different. Please refer to each event's documentation around example values they can show, and what they mean.

Below is a chart of what example JSONPath filters might return with the event payload above.

JSONPath Result
$.identity The identity object in the event
$.identity.name The name of the identity in the event
$[?($.identity.name == "john.doe")] If the object contains an identity name of "john.doe"
$.changes All of the identity attribute change objects in the event
$.changes[*].attribute A list attribute names which changed in the event
$.changes[?(@.attribute == "department")] Contains specific change object(s) relating to the "department" attribute
$.changes[?(@.attribute == "cloudLifecycleState")].newValue The new value of the change to the "cloudLifecycleState" attribute
$.changes[?(@.attribute == "cloudLifecycleState" && @.newValue == "terminated")] Contains specific change object(s) relating to the "department" attribute and have a new valyue with "terminated"

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