Introduction

When a Dispatch Task is created, its purpose is to parent the possible steps that a dispatcher and guard(s) can execute, known as a Workflow.

A Workflow is a template of steps that are permitted to be executed, and transitioned between. A Workflow Instance is an instance of a Workflow as the name suggests. Every new Dispatch Task created instances a Workflow as a Workflow Instance.

As a Workflow Instance progresses, the execution of its defined steps (known as transitions) are logged as records of another data entity called Workflow Instance Logs.

The status of a Dispatch Task is a snapshot in time, while Workflow Instance Logs are a chronology. Therefore for integrations that are interested in everything that has occurred in a Dispatch Task, they should look to records captured in Workflow Instance Logs. 

For a Dispatch Task termination or Cancellation event, it may be tempting to only monitor the Dispatch Task, but context and sequence (FROMs and TOs of transitions) can hold a lot of business value. Therefore Workflow Instance Logs are the most valuable source of signaling and auditing data.

TrackTik's Events Subscription service is a cloud based queue that you can set up (via the /events-subscriptions endpoint) so that you can receive REST API POST method calls to a webhook that you own. There are various triggers behind the timings that you can set yourself like created, updated.

Two Approaches

When a Dispatch Task is created, and an associated Workflow Instance, your Events Subscription can either be:

1. To the Worklow Instance Logs of that single Workflow Instance where you turn the subscription off after the instance ends (reaches the end, or transitions to cancelled)
   
   PROS: Allows you to pause/resume the subscription to the logs of that Workflow Instance/Dispatch. Smaller payloads per webhook call-out received.
   
   CONS: More calls to your webhook, and more subscriptions to manage in case of missed events (by your system or TrackTik's). More data joins.
   
   
2. To any/all Workflow Instance Logs entries and manage the IDs of each and functional separation on your end exclusively.
   
   PROS: One single subcription to manage
   
   CONS: Less granularity, larger payloads and more data aggregation on our end.

First approach: Events Subscription to the logs of a single Workflow Instance

Steps:

1. POST a new events-subscriptions entry for workflow-instances so that your webhook can receive the ID number of new workflow instances, and any of its status updates (using events triggers of "created" and "updated").
2. Any time you receive a new ID of a new Workflow Instance, POST a new events-subscriptions entry for workflow-instance-logs with a filter for that ID: a "userDefinedFilters": {"workflowInstance": nnn} section that only follows that one workflow instance.
3. Watch for the last status of the workflow instance (as defined by the Workflow, which can be keyed with keywords your system can recognized like "completed" or "cancelled").
4. Disable the events-subscription for that workflow instance via /events-subscriptions/{id}/actions/archive

An Events subscription for Workflow Instances

POST /events-subscriptions

{
            "customId": "WI-Event",
            "name": "Workflow Instances Events",
            "events": [
                "entity:workflow-instances:created",
                "entity:workflow-instances:updated"
            ],
            "contextFilters": {
                "filters": [
                    {
                        "tag": "context.*",
                        "includeChildren": true
                    }
                ],
                "exclusions": []
            },
            "url": "https://www.yourdomain.site/path/receive",
            "failureEmail": "support@yourdomain.site",
            "secretHeaderName" : "TrackTik-subscription-secret-without-spaces",
            "secret" : "B2C60..."
        }

Your webhook will receive a payload with a lot of identifiers, including that of the Workflow Instance (the id value):

{
   "currentStatus": 23,
   "workflow": 3,
   "modifiedOn": "2022-12-15T19:24:53+00:00",
   "startedOn": "2022-12-14T21:56:56+00:00",
   "dispatchTask": 662,
==>"id": 596
}

An Events Subscription for the logs of a single Workflow Instance

POST /events-subscriptions

{
	"customId": "WFI-596",
	"name": "Logs of Workflow Instance 596",
	"events": [
		"entity:workflow-instance-logs:created",
		"entity:workflow-instance-logs:updated"
	],
	"entityResponse": {
		"include": [
		"status",
		"user",
		"workflowInstance"
	]
	},
	"contextFilters": {
	"filters": [
		{
		   "tag": "context.*",
		   "includeChildren": true
		}
	]
	},
	"userDefinedFilters": {
==>	   "workflowInstance": 596
	},
	"url": "https://www.yourdomain.site/path/receive", 
	"failureEmail": "support@yourdomain.site",
	"secretHeaderName" : "TrackTik-subscription-secret-without-spaces",
	"secret" : "AFE32..."
}

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

“Dispatch task 662 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": 3,
		"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": 3,
               "modifiedOn": "2022-12-15T19:24:53+00:00",
	       "startedOn": "2022-12-14T21:56:56+00:00",
               "dispatchTask": 662,
               "id": 596
           }
	},
	"arguments": {
	   "resource": "workflow-instance-logs"
	}
}

Second approach: Events Subscription to the logs of any/all Workflow Instances

1. Subscribe to workflow-instance-logs.
2. 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.
3. When a new workflow instance ID is obtained, wait for payloads from workflow-instance-logs and match/aggregate on its unique ID.

Events-subscription for a any Workflow Instance

POST /events-subscriptions

{
	"customId": "WFI-ANY",
	"name": "Logs of any Workflow Instance",
	"events": [
		"entity:workflow-instance-logs:created",
		"entity:workflow-instance-logs:updated"
	],
	"entityResponse": {
		"include": [
		"status",
		"user",
		"workflowInstance"
	]
	},
	"contextFilters": {
	"filters": [
		{
		"tag": "context.*",
		"includeChildren": true
		}
	]
	},
	"url": "https://www.yourdomain.site/path/receive", 
	"failureEmail": "support@yourdomain.site",
	"secretHeaderName" : "TrackTik-subscription-secret-without-spaces",
	"secret" : "AFE32..."
}

If you'd like to learn more by using a business case where a camera system identifies events/triggers that warrant the dispatching of a guard, have a look at our handy guide: Camera and Alarms Triggered Dispatches and Workflow Executions