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"
  }
}

{
  "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"
  }
}

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

Error handling and conflicts

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.

Automation Object Schema

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

{
  "id": "string",
  "name": "string",
  "description": "string",
  "priority": 0,
  "attachment_behavior": {
    "attach_to_new_workflows": boolean,
    "opt_in": boolean
  },
  "criteria": {
    "filter": "string",
    "mutable_filter": "string"
  },
  "action": {
    // For modification actions:
    "decision": "string",
    "signed_off_state": "string",
    "notes": "string",
    "reviewer_assignment": null,

    // OR for display actions:
    "display_style": "string",
    "display_text": "string"
  }
}

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.

• priority (Integer): Priority value of the Automation (not currently supported).

attachment_behavior (Object)

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.

criteria (Object)

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

• mutable_filter (String): A filter on a previous result mutable field using the syntax previous.attribute. Example: "previous.decision eq "RESULT_DECISION_ACCEPTED""

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.

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"

  • "RESULT_DECISION_ACCEPTED"

  • "RESULT_DECISION_REJECTED"

  • "RESULT_DECISION_FIXED"

• notes: string

• signed_off_state:

  • "UNKNOWN"

  • "NOT_SIGNED_OFF"

  • "SIGNED_OFF"

action (Object)

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.

• display_style (String): Visual indicator to apply to matching rows:

  • HIGHLIGHT: Highlight the row

  • SUGGEST_ACCEPT: Mark the row as suggested for acceptance

  • SUGGEST_REJECT: Mark the row as suggested for rejection

• display_text (String): Custom message to show when display_style is set

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)

• REJECTED (3)

• FIXED (4)

Signed Off State can be:

• UNKNOWN_SIGNED_OFF = 0;

• NOT_SIGNED_OFF = 1;

• SIGNED_OFF = 2;

reviewer_assignment (Object)

The preview API does not currently support Reviewer assignment.

Preview API Documentation

Use the endpoints documented below to create and manage automations:

List Automations

• Endpoint: /api/preview/awf/automations

• Method: GET

• Description: Returns all Automations and configuration details.

Update Automation

• Endpoint: /api/preview/awf/automations

• Method: PUT

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

Create Automation

• Endpoint: /api/preview/awf/automations

• Method: POST

• Description: Creates a new Automation.

Get Automation

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

• Method: GET

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

Delete Automation

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

• Method: DELETE

• Description: Deletes a specific Automation by its ID.

Attach Automations

• 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.

• opt_in (boolean): If False the Automation can be selected when creating a certification. Otherwise, operators can enable it when creating certifications.

List attached Workflow Automations

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

• Method: GET

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

Detach Automations

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

• Method: POST

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