# 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://{tenant}.api.identitynow.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

HTTP Status Code: 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"
  }
]

# Invocation Response Modes

Specify how the custom application interacts with the trigger service with the invocation response mode. There are three response modes to choose from: SYNC, ASYNC, and DYNAMIC.

  • SYNC: This type of response creates a synchronous flow between the trigger service and the custom application. Once a trigger has been invoked, the custom application is expected to respond within 10 seconds before timeout.
  • ASYNC: This type of response creates an asynchronous flow between the trigger service and the custom application. When a trigger is invoked, the custom application does not need to respond immediately. The trigger service will provide an URL and a secret that the custom application can use to complete the invocation if the custom application wishes to handle the invocation at a later time.
  • DYNAMIC: This type of response gives the custom application the ability to choose on the fly whether it handles the invocation request synchronously or asynchronously. In some cases, SYNC mode may be chosen because it is able to respond quickly. In other cases, it may choose ASYNC because it needs to run some long, blocking task before responding to the invocation.

Note: Above response modes only apply when HTTP is specified as subscription type.

# 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://{tenant}.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

HTTP Status Code: 200 OK

{
  "approved": true
}

ASYNC

HTTP Status Code: 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://{tenant}.api.identitynow.com/beta/trigger-invocations/{id}/complete
{
  "secret": "16ddc0c4-8bcc-489d-8f47-4dfb2ebf4dff",
  "output": {
    "approved": true
  }
}

DYNAMIC (SYNC): Same as SYNC

DYNAMIC (ASYNC)

HTTP Status Code: 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://{tenant}.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://{tenant}.api.identitynow.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.