Automations API

Use these operations to manage Access Review Automations and associate them with individual workflows.

Automations apply changes (such as approve, sign-off, add a note, or apply visual indicators) to Certification rows based on historical certification data, or a filter on the current results. They can run by default or on an opt-in basis when a certification is created.

Example Automations

{
  "id": "e48dd2c8-3633-463b-a477-0177a942b5a6",
  "name": "Highlight inactive sources",
  "description": "Highlight rows where the source account is inactive",
  "priority": 0,
  "attachment_behavior": {
    "attach_to_new_workflows": true,
    "opt_in": true
  },
  "criteria": {
    "filter": "source.is_active eq false",
    "mutable_filter": ""
  },
  "action": {
    "display_style": "HIGHLIGHT",
    "display_text": "Source account is inactive",
    "highlight_color": "#FF6B35"
  }
}

{
  "id": "f59ee3d9-4744-574c-b588-1288b0942c7c",
  "name": "Reject privileged account access",
  "description": "Suggest reject for admin or root accounts",
  "priority": 0,
  "attachment_behavior": {
    "attach_to_new_workflows": true,
    "opt_in": true
  },
  "criteria": {
    "filter": "(destination.name eq \"admin\") OR (source.name eq \"root\")",
    "mutable_filter": ""
  },
  "action": {
    "display_style": "SUGGEST_REJECT",
    "display_text": "Privileged account detected - review carefully"
  }
}

For more information about this feature see Intelligent Automations.

You will need an API token with root team or administrator permissions to manage Automations.

Key Concepts

When working with the Automations API, it is important to understand the relationship between three identifiers:

At an API level,

• An Automation is a reusable rule that can be attached to one or more Workflows

• A Workflow (review configuration) defines how reviews are created and can have multiple Certifications over time

• A Certification is a single instance of a review where Automations run against the results

The following rules apply when an Automation run encounters an issue:

• If Automation processing fails for any result, the Automation run stops and no further Automations are applied.

• When Automations fail, the Certification is still considered complete and non-errored. The Automation run will have an error status and message.

Results are considered the same when the entities and relationships are exactly equal (including data source IDs). If a conflict occurs with Automations trying to change the same mutable field:

• Each change must update the field to the same value. The action log entry will contain notes (if supplied) for each action.

• Automations changing a field to differing values are unresolvable conflicts and skipped, but will not interrupt the Automation run.

An Automation consists of attachment_behavior rules, filter criteria, and an action to apply:

Each Automation object has the fields:

• id (String): Unique identifier for the Automation.

• name (String): Name of the Automation.

• description (String): A brief description of the Automation.

Defines if the Automation is available for all workflows, and whether it is optional:

• attach_to_new_workflows (Boolean): Indicates whether to automatically attach to new and existing workflows.

• opt_in (Boolean): If true Operators can pick the automation when creating a Workflow. If false the automation is enabled by default.

Specifies filters for conditionally updating results:

• filter (String): A SCIM filter specifying a source or destination attribute with support for complex expressions using AND, OR, and parentheses for grouping. Examples:

  • Simple filter: source.is_active eq false

  • Complex filter: (source.name sw "A" OR source.name sw "B") AND destination.is_active eq true

Similarly to Smart Actions, Automations can update results based on a source or destination attribute (such as activity status). Filters use the syntax source.attribute or destination.attribute.

The filter field in an Automation's criteria accepts a SCIM-style expression. Each filter field referenced in the expression is either a bare field or a two-part endpoint.field. Filter fields with three or more dot-separated segments (for example, source.tags.value, reviewers.id, or decision.by) are invalid and are rejected at parse time.

A filter that fails to parse prevents the Automation from running. When multiple Automations are attached to a Certification, a single unparseable filter on any one of them blocks every attached Automation from running on that Certification.

The endpoint must be one of the following:

Notes on two-part form:

• tags matches on the tag key only, never the value. For example, source.tags eq "owner" matches any source node carrying a tag whose key is owner, regardless of that tag's value.

• Use the exact property key as stored on the node. Built-in properties use their own name (for example, source.is_active). Customer-ingested custom properties carry the customprop_ prefix that is applied during ingest (for example, source.customprop_attribute_code

Bare fields refer to attributes of the Certification result row itself, not to the source, destination, waypoint, or path-summary nodes. The field must be exactly one of the following:

These fields are bare-only. Dotted forms such as reviewers.id, decision.by, or signed_off_state.id are not supported and are rejected at parse time.

The following filter expressions do not conform to the grammar and are rejected when an Automation is created or updated:

When an Access Review configuration includes , you can filter on enriched entity attributes in Automations. Reference joined nodes by their alias directly (e.g., idp.attribute), not using joined_nodes.idp.attribute.

For complete guidance on finding aliases, filter syntax, and examples, see .

Mutable filters in Automations use the syntax previous.decision, previous.notes and previous.signed_off_state to refer to historical row data. The possible values are:

• decision:

  • "RESULT_DECISION_UNKNOWN"

  • "RESULT_DECISION_NONE"

Action the Automation will apply to matching results:

• decision (String): Decision code for the action.

• signed_off_state (String): Sign off state code.

• notes (String): Notes the automation will apply.

Note: When using display_style actions, you cannot set decision, signed_off_state, notes, or reviewer_assignment fields.

Possible decisions and numeric codes are:

• UNKNOWN (0)

• NONE (1)

• ACCEPTED (2

Signed Off State can be:

• UNKNOWN_SIGNED_OFF = 0;

• NOT_SIGNED_OFF = 1;

• SIGNED_OFF = 2;

The preview API does not currently support Reviewer assignment.

Use the endpoints documented below to create and manage automations:

• Endpoint: /api/preview/awf/automations

• Method: GET

• Description: Returns all Automations and configuration details.

Returns all in a values array.

• Endpoint: /api/preview/awf/automations

• Method: PUT

• Description: Updates an existing Automation. The full Automation object is required.

• Endpoint: /api/preview/awf/automations

• Method: POST

• Description: Creates a new Automation.

• Endpoint: /api/preview/awf/automations/{id}

• Method: GET

• Description: Get details for a single Automation by ID.

• Endpoint: /api/preview/awf/automations/{id}

• Method: DELETE

• Description: Deletes a specific Automation by its ID.

• Endpoint: /api/preview/awf/automations:attach

• Method: POST

• Description: Enable an Automation for a specific workflow, or all workflows.

Attach one or all Automations to a single workflow by specifying the:

• id (String): Single Automation ID.

• workflow_id (String): ID of the workflow to associate Automations with.

• all (boolean): If True, attaches all existing Automations to the Workflow.

• Endpoint: /api/preview/awf/automations:attached/{workflow_id}

• Method: GET

• Description: Returns all Automations eligible to run on Certifications for a given Workflow id.

• Endpoint: /api/preview/awf/automations:detach

• Method: POST

• Description: Detach one or all Automations from an Access Review Workflow.