Workflows : Events Subscriptions Strategies

Updated July 10, 2024 14:58

Introduction

A Workflow is a template, and a Workflow Instance is a workflow in progress (dispatch task created, task time has workflow attached.)

An external integrator/partner isn’t currently permissions enabled to create a Workflow Instance from a Workflow, but the instance is created from the Dispatch Task (via the task type that can be configured to have an associated workflow) so they don’t need to.

Two Approaches

The progression through the steps of the workflow is subscribable using our /events-subscriptions endpoint. Once the ID of a Workflow Instance is known (perhaps as separate events subscription for /workflow-instances ), it can either be targeted separately as its own events-subscription (with userDefinedFilters) section and disable the subscription once the flow ends, or without it so that a connected system can see ALL workflow instance logs for all workflow instances, and choose to filter on the ID of the Workflow Instance on their end (and not need to end the subscription).

A-Events Subscription management (if only seeking to follow one Workflow Instance)

Subscribe to workflow-instances to receive the ID number of new instances.
POST a new events-subscriptions entry for workflow-instance-logs with a "userDefinedFilters": {"workflowInstance": nnn} section that only follows that one instance.
Watch for the last status of the workflow instance
Disable the events-subscription for that workflow instance via /events-subscriptions/{id}/actions/archive

Events-subscription for a single Workflow Instance

{
        "customId": "WFI-480",
        "name": "Steps progression of a Workflow Instance",
        "events": [
            "entity:workflow-instance-logs:created",
            "entity:workflow-instance-logs:updated"
        ],
        "entityResponse": {
            "include": [
                "status",
                "user",
                "workflowInstance"
            ]
        },
        "contextFilters": {
            "filters": [
                {
                    "tag": "context.region.2",
                    "includeChildren": true
                }
            ]
        },
        "userDefinedFilters": {
            "workflowInstance": 480
        },
        "url": "https://webhook.site/fd152...",
        "failureEmail": "fd152...@email.webhook.site",
        "secretHeaderName" : "TrackTik-subscription-secret-without-spaces",
        "secret" : "B2C60..."
    }

This produces call-outs of the following format, that enables the narrative:

“Dispatch task 541 which is assigned to employee ID 1002 has just hit the 'On the way' workflow status, at this date and time.“

{
  "context": "context.region.2",
  "eventName": "entity:workflow-instance-logs:created",
  "entity": {
==> "createdOn": "2022-12-15T19:24:53+00:00",
    "id": 1983,
    "status": {
 ==>  "name": "On The Way",
      "tag": "en_route",
      "workflow": 2,
      "formatBackgroundColor": "#EC8123",
      "formatTextColor": "WHITE",
      "warningThresholdInMinutes": 15,
      "alertThresholdInMinutes": 20,
      "id": 15
    },
    "user": {
      "jobTitle": "Support Team",
      "region": 2,
      "employmentProfile": 3,
      "address": 6,
 ==>  "id": 1002,
      "customId": "111123",
      "firstName": "TrackTik",
      "lastName": "Support",
      "name": "TrackTik Support",
      "primaryPhone": "18884545606",
      "secondaryPhone": "",
      "email": "support@TrackTik.com",
      "status": "ACTIVE",
      "avatar": "https://innovation.staffr.net/rest/v1/avatar/employees/1002/80c72916284381243b91abcd186a8cf3"
    },
    "workflowInstance": {
      "currentStatus": 15,
      "workflow": 2,
      "modifiedOn": "2022-12-15T19:24:53+00:00",
      "startedOn": "2022-12-14T21:56:56+00:00",
==>   "dispatchTask": 541,
      "id": 480
    }
  },
  "arguments": {
    "resource": "workflow-instance-logs"
  }
}

B-Events Subscription management (if seeking to follow ALL Workflow Instances)

Subscribe to workflow-instance-logs, or workflow-instances (the latter if you need to map to the dispatch task ID)
On the receiving end, track the history of unique IDs of workflow-instances or dispatch tasks with a task type that has a known workflow attached
When a new workflow instance ID is obtained, wait for payloads from workflow-instance-logs and match on the unique ID of choice
Aggregate all new log entries on that unique ID in the other system

Events-subscription for a any Workflow Instance

{
        "customId": "WFI-ANY",
        "name": "Steps progression of any Workflow Instance",
        "events": [
            "entity:workflow-instance-logs:created",
            "entity:workflow-instance-logs:updated"
        ],
        "entityResponse": {
            "include": [
                "status",
                "user",
                "workflowInstance"
            ]
        },
        "contextFilters": {
            "filters": [
                {
                    "tag": "context.region.2",
                    "includeChildren": true
                }
            ]
        },
        "url": "https://webhook.site/fd152...",
        "failureEmail": "fd152...@email.webhook.site",
        "secretHeaderName" : "TrackTik-subscription-secret-without-spaces",
        "secret" : "B2C6011...."
    }