Automations API

Get, create, update, delete, and attach Intelligent Automations.

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

Automations apply changes (such as approve, sign-off, or add a note) 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.

For more information about this feature see Intelligent Automations.

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": "e48dd2c8-3633-463b-a477-0177a942b5a6",
  "name": "Reject and sign-off source names starting with A",
  "description": "Reject and sign-off source names that start with the letter A",
  "priority": 0,
  "attachment_behavior": {
    "attach_to_new_workflows": true,
    "opt_in": true
  },
  "criteria": {
    "filter": "source.name sw \"A\"",
    "mutable_filter": ""
  },
  "action": {
    "decision": "REJECTED",
    "signed_off_state": "SIGNED_OFF",
    "notes": "Rejected because the name started with A",
    "reviewer_assignment": null
  }
}

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. Example: "source.is_active eq false"

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

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.

List Automations

• Endpoint: /api/preview/awf/automations

• Method: GET

• Description: Returns all Automations and configuration details.

curl -X GET "{base_url}/api/preview/awf/automations" \
-H "Authorization: Bearer {token}" \
-H "accept: application/json"

The response will contain all Automations in a values array:

{
  "values": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      ...
    },
    {
      "id": "string",
      "name": "string",
      "description": "string",
      ...
    }
  ]
}

Update Automation

• Endpoint: /api/preview/awf/automations

• Method: PUT

• Description: Updates an existing Automation.

Update an existing Automation with a new configuration. The full Automation object is required, including the id of the Automation to update.

Example request:

curl -X PUT "{base_url}/api/preview/awf/automations" \
-H "Authorization: Bearer {token}" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"value":{"id":"string","name":"string","description":"string","priority":0,"attachment_behavior":{"attach_to_new_workflows":false,"opt_in":false},"criteria":{"filter":"string","mutable_filter":"string"},"action":{"decision":0,"signed_off_state":0,"notes":"string","reviewer_assignment":{"users_manager":false,"resource_managers":false,"reviewers":[{"user_type":"string","id":"string","email":"string","name":"string"}],"fallback_reviewers":[{"user_type":"string","id":"string","email":"string","name":"string"}]}}}}' \

A successful response will be empty.

Create Automation

• Endpoint: /api/preview/awf/automations

• Method: POST

• Description: Creates a new Automation.

Example request:

curl -X POST "{base_url}/api/preview/awf/automations" \
 -H "Authorization: Bearer {token}" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"name":"string","description":"string","priority":0,"attachment_behavior":{"attach_to_new_workflows":false,"opt_in":false},"criteria":{"filter":"string","mutable_filter":"string"},"action":{"decision":0,"signed_off_state":0,"notes":"string","reviewer_assignment":{"users_manager":false,"resource_managers":false,"reviewers":[{"user_type":"string","id":"string","email":"string","name":"string"}],"fallback_reviewers":[{"user_type":"string","id":"string","email":"string","name":"string"}]}}}'

A successful response returns the Automation id:

{
"id": "string"
}

Get Automation

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

• Method: GET

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

Example request:

curl -X GET "{base_url}/api/preview/awf/automations/{id}" \
-H "Authorization: Bearer {token}" \
-H "accept: application/json"

A successful response contains a value object with an Automation definition.

Delete Automation

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

• Method: DELETE

• Description: Deletes a specific Automation by its ID.

Example request:

curl -X DELETE "{base_url}/api/preview/awf/automations/{id}" \
-H "Authorization: Bearer {token}" \
-H "accept: application/json"

A successful response will be empty.

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.

Example request:

curl -X POST "{base_url}/api/preview/awf/automations:attach" \
-H "Authorization: Bearer {token}" \
-H "accept: application/json"\
-H "content-type: application/json" \
-d '{"id":"string","workflow_id":"string","all":false,"opt_in":false}'

A successful response will be empty.

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.

Example request:

curl -X GET "{base_url}/api/preview/awf/automations:attached/" \
-H "Authorization: Bearer {token}" \
-H "accept: application/json"

The response is a values array containing all attached Automations:

{
  "values": [
    {
      "automation": {
        "id": "string",
        "name": "string",
        ...
      },
      "opt_in": false
    }
  ]
}

Detach Automations

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

• Method: POST

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

Detaching Automations requires the:

• id (String): Automation ID.

• workflow_id (String): ID of Workflow to detach from.

• all (boolean): If true, remove all attached Automations.

Example request:

curl -X POST "{base_url}/api/preview/awf/automations:detach" \
-H "Authorization: Bearer {token}" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"id":"string","workflow_id":"string","all":false}'

A successful response will be empty.