Initiate a Trigger Test Invocation

You can test a trigger invocation with a request to /trigger-invocations/test endpoint.

Example request to start a dry run of test:fire-and-forget trigger invocation:

POST https://<org>.api.cloud.sailpoint.com/beta/trigger-invocations/test
  • triggerId (required): Trigger ID
  • input (optional): Mock trigger input, subject to follow input schema of the trigger; if not provided, the example input specified in trigger definition is used instead
  • contentJson (required): JSON map of metadata about the invocation (empty map is sufficient)
  • subscriptionIds (optional): List of subscriptions to send the test invocation to; if not provided, test invocation is sent to all subscriptions to a trigger
{
  "triggerId": "test:fire-and-forget",
  "input": {
    "approved": true,
    "identityId": "201327fda1c44704ac01181e963d463c"
  },
  "contentJson": {},
  "subscriptionIds": [
    "d44c2f42-a8bb-41fd-a7ca-b5996a46c27f",
    "4fd682bd-3595-4cff-9f65-6ad746c606cb"
  ]
}

Response

  • id: Invocation ID
  • triggerId: Trigger ID
  • contentJson: JSON map of metadata about the invocation
  • secret: Unique invocation secret that must accompany the output payload to complete the invocation

200 OK

[
  {
    "id": "a6de292d-1def-4e9f-a15a-23348a4ba0f3",
    "contentJson": {},
    "triggerId": "test:fire-and-forget",
    "secret": "99a4de81-e311-4f45-95b0-6be269b474c7"
  },
  {
    "id": "eb0fb93d-ced8-4228-81bb-369858e4618c",
    "contentJson": {},
    "triggerId": "test:fire-and-forget",
    "secret": "c05f54fe-ea21-40fd-9f5f-431e630e4bb7"
  }
]

Receiving Trigger Invocation Request

The custom application will receive a POST request from the trigger service at the URL specified in trigger subscription.

Example SYNC test:request-response trigger invocation from the trigger service:

  • identityId: test:request-response trigger’s input payload (fields as specified in the trigger’s input schema)
{
  "identityId": "201327fda1c44704ac01181e963d463c"
}

Example ASYNC test:request-response trigger invocation from the trigger service:

  • _metadata
    • callbackURL: URL to post output payload to complete the invocation
    • secret: Unique invocation secret that must accompany the output payload to complete the invocation
  • identityId: test:request-response trigger’s input payload (fields as specified in the trigger’s input schema)
{
  "_metadata": {
    "callbackURL": "https://{org}.api.identitynow.com/beta/trigger-invocations/{id}/complete",
    "secret": "16ddc0c4-8bcc-489d-8f47-4dfb2ebf4dff"
  },
  "identityId": "201327fda1c44704ac01181e963d463c"
}

Note: identityId field is included as a field specific for the test:request-response trigger. Other triggers may include other fields specific for those triggers.

Responding to a Trigger Invocation (REQUEST_RESPONSE only)

When a REQUEST_RESPONSE trigger invocation request is received by the custom application, it must respond to the request with the output payload as specified in the trigger’s output schema.

SYNC

The custom application responds to the trigger invocation with the output payload.

ASYNC

The custom application only needs to acknowledge (200 OK) that it has received the trigger invocation request and complete the invocation at a later time.

DYNAMIC

The custom application determines arbitrarily whether to respond to the trigger invocation as SYNC or ASYNC. In the case of ASYNC, the custom application only needs to acknowledge (202 Accepted) that it has received the trigger invocation request and complete the invocation at a later time.

Note: Content type of the response body MUST be application/json (including empty responses for ASYNC).


Custom Application Response

The following is an example of how the custom application may respond to the trigger invocation request for the test:request-response trigger:

  • SYNC

    • 200 OK
    {
      "approved": true
    }
    
  • ASYNC

    • 200 OK
    {}
    
    • At a later time but within the invocation deadline, respond to the given completion URL with a secret and output payload:
    POST https://{org}.api.identitynow.com/beta/trigger-invocations/{id}/complete
    
    {
      "secret": "16ddc0c4-8bcc-489d-8f47-4dfb2ebf4dff",
      "output": {
        "approved": true
      }
    }
    
  • DYNAMIC (SYNC)

    • Same as SYNC
  • DYNAMIC (ASYNC)

    • 202 Accepted
    {}
    
    • At a later time but within the invocation deadline, respond to the given completion URL with a secret and output payload:
    POST https://{org}.api.identitynow.com/beta/trigger-invocations/{id}/complete
    
    {
      "secret": "16ddc0c4-8bcc-489d-8f47-4dfb2ebf4dff",
      "output": {
        "approved": true
      }
    }
    

Trigger Invocation Status

The status of the invocation, from the start of the invocation to its completion, can be tracked with the following request:

GET https://<org>.api.cloud.sailpoint.com/beta/trigger-invocations/status
  • type: Invocation type - TEST or REAL_TIME
  • id: Invocation ID
  • created: UTC timestamp of when the invocation has started
  • completed: UTC timestamp of when the invocation has completed (null represents the invocation has not yet completed)
  • triggerId: Trigger ID
  • startInvocationInput
    • input: Trigger input (payload sent to external application)
    • triggerId: Trigger ID
    • contentJson: Content produced to Kafka when invocation is completed
  • completeInvocationInput
    • output: Trigger output (payload received from external application)
    • localizedError: Any error during completion
  • subscriptionId: Tenant’s subscription ID
{
    "type": "TEST",
    "id": "1210e59e-f52b-4368-89f6-bd15d34c3a87",
    "created": "2020-04-08T12:32:59.712Z",
    "completed": null,
    "triggerId": "test:request-response",
    "startInvocationInput": {
        "input": {
            "identityId": "201327fda1c44704ac01181e963d463c"
        },
        "triggerId": "test:request-response",
        "contentJson": {}
    },
    "completeInvocationInput": {
        "output": null,
        "localizedError": null
    },
    "subscriptionId": "d43401b6-e8c9-4ab3-a475-c067e7411f29"
}

Note: The status endpoint works for both REQUEST_RESPONSE and FIRE_AND_FORGET triggers. However, the status of FIRE_AND_FORGET trigger invocation will contain null values in its completeInvocationInput as FIRE_AND_FORGET trigger is not expected be completed.