Monitor Workflow Runs

< All Topics

Overview

The BLAM API can provide a list of all the workflow runs of a specified workflow Blueprint up to a maximum of 28 days after the individual workflow runs were triggered. The WorkflowRunStatus provides the overall state of the workflow run whilst the individual nodes of the blueprint (each BLidget in the workflow) also have their own RunNodeStatus. In this way, each workflow run can be monitored down to the individual steps the workflow has triggered, and the number of items passed into and out of each node or BLidget. The possible workflow statuses are:

  • Running
  • Complete
  • Failed

For workflow blueprints that have one or more branches, it is possible for a workflow run to have an overall status of Running but have errors reported on individual nodes (BLidgets). The workflow status will update to Failed if all possible branches in the workflow have completed and the Failed node has not been restarted and the error resolved.

Listing Workflow Runs

You can list the workflow runs for a given BlueprintId through the BLAM API by a GET request to /api/workflows/blueprints/{blueprintId}/runs. Providing an additional parameter SinceHours to the BLAM API as an integer number of hours will return all the workflow runs triggered up to the number of hours specified. BLAM automatically truncates workflow runs over 28 days old.

curl -H "Authorization: Bearer ${TOKEN}" https://yourblam.bluelucy.com/api/workflows/blueprints/1/runs?SinceHours=24

Example Response:

[
    {
        "id": 1,
        "name": "bbb_sunflower_1080p_30fps_normal.mp4",
        "blueprintName": "Ingest: Register Watchfolder Files",
        "status": "Complete",
        "errors": 0,
        "dateTriggered": "2020-07-01T09:42:43.3896719",
        "dateFinished": "2020-07-01T09:42:43.3896719",
        "blueprintId": 1,
        "triggeringUserId": null
    },
    {
        "id": 2,
        "name": "PAL_720p_DVCPRO_HD_colorbar_XDCAM HD.mxf",
        "blueprintName": "Ingest: Register Watchfolder Files",
        "status": "Failed",
        "errors": 1,
        "dateTriggered": "2020-07-17T17:29:41.352394",
        "dateFinished": "2020-07-17T17:30:05.8490927",
        "blueprintId": 1,
        "triggeringUserId": null
    }
]

A more detailed of a workflow run, including the individual node (BLidget) statuses, can be obtained by a GET request to /api/workflows/runs/{id} where {id} is the Id number of the workflow run.

curl -H "Authorization: Bearer ${TOKEN}" https://yourblam.bluelucy.com/api/workflows/runs/1

Example Response:

{
    "id": 1,
    "name": "bbb_sunflower_1080p_30fps_normal.mp4",
    "status": "Complete",
    "errors": 0,
    "dateTriggered": "2020-07-01T09:42:43.3896719",
    "dateFinished": "2020-07-01T09:43:09.5421904",
    "blueprintId": 1,
    "triggeringUserId": null,
    "input": {
        "data": "{\"files\":[{\"assetId\":null,\"fileName\":\"bbb_sunflower_1080p_30fps_normal.mp4\"}]}"
    },
    "nodes": [
        {
            "id": 1,
            "status": "Completed",
            "polling": false,
            "progress": 100,
            "message": null,
            "dateStarted": "2020-07-01T09:42:44.1439186",
            "dateFinished": "2020-07-01T09:42:47.3285074",
            "lastProgressDate": "2020-07-01T09:42:47.328559",
            "workflowRunId": 1,
            "compositeRunNodeId": null,
            "itemCount": 1,
            "connectionTo": null,
            "connectionsFrom": [
                {
                    "toId": 2,
                    "path": "Primary",
                    "itemCount": 1
                }
            ],
            "blueprintNode": {
                "name": "",
                "priority": 0,
                "xPos": 168,
                "yPos": 221,
                "blidget": {
                    "id": "ba9903fc-6330-4d8b-a2d6-d04c79c5158e",
                    "name": "Register Files",
                    "icon": ...,
                    "iconName": "generic-icon.svg",
                    "keywords": null,
                    "documentation": ...,
                    "inputType": 1,
                    "outputType": 4,
                    "available": true,
                    "hasSecondaryPath": false,
                    "hasFailurePath": false,
                    "parameters":  ...
                },
                "arguments": null
            }
        },
        {
            "id": 2,
            "status": "Completed",
            "polling": false,
            "progress": 100,
            "message": null,
            "dateStarted": "2020-07-01T09:42:49.4783137",
            "dateFinished": "2020-07-01T09:43:09.5421904",
            "lastProgressDate": "2020-07-01T09:43:09.8509345",
            "workflowRunId": 1,
            "compositeRunNodeId": null,
            "itemCount": 1,
            "connectionTo": {
                "fromId": 1,
                "itemCount": 1
            },
            "connectionsFrom": [],
            "blueprintNode": {
                "name": "",
                "priority": 0,
                "xPos": 373,
                "yPos": 221,
                "blidget": {
                    "id": "e9af0292-343f-49ed-a052-be157ffa59cb",
                    "name": "Get Technical Data",
                    "icon": ...,
                    "iconName": "generic-icon.svg",
                    "keywords": null,
                    "documentation": ...,
                    "inputType": 4,
                    "outputType": 4,
                    "available": true,
                    "hasSecondaryPath": false,
                    "hasFailurePath": false,
                    "parameters": "{}"
                },
                "arguments": null
            }
        }
    ]
}

Understanding the RunNodeStatus

Each workflow run node (BLidget) has a RunNodeStatus which can be used to denote what stage a workflow has reached whilst the workflow is running:

  • 0 – Pending
  • A pending node has yet to be triggered by its preceding node. If the node is on a branch that has no items passed to it, the node will remain ‘Pending’ even if the WorkflowRunStatus is complete. A pending node cannot be cancelled.

  • 1 – Running
  • The node (BLidget) is currently being executed. A running node can be cancelled.

  • 2 – Completed
  • The node has completed and the connected downstream node(s) have been triggered. A completed node cannot be cancelled.

  • 3 – Failed
  • The node has failed and thrown an exception. A failed node can resume execution retaining its run state by setting the status to Queued and Polling to ‘true’ or restarted and clearing its run state by setting its status to Queued and Polling to ‘false’.

  • 4 – Queued
  • The node is in the queue and awaiting execution. A queued node with Polling set to ‘true’ signifies the node has completed execution and saved its run state but its task is not complete. A polling node is generally found when work is passed to a 3rd party service and polls the service to check when the work is complete. A queued node can be cancelled.

  • 5 – Cancelled
  • A cancelled node has been manually cancelled by a user. A cancelled node can resume execution retaining its run state by setting the status to Queued and Polling to ‘true’ or restarted and clearing its run state by setting its status to Queued and Polling to ‘false’.

  • 6 – Idle
  • An idle node is a reserved status for node’s waiting for another BLAM process to be completed. BLidget’s that raise a BLAM Task use the Idle status until the Task is completed by a BLAM user. An idle node cannot be cancelled.