Task Status API

The Task Status API is a websocket-based interface that allows developers to receive real-time updates on the status of tasks currently being performed by a d3 service instance. In some cases calling an API will result in a long task being performed, such as copying and downloading files, and rather than waiting a long time for a response we provide a task ID that allows users to subscribe to its progress.

Using the Interface

An API which expects to take a long time may return a websocket task URI and in this case it can be immediately requested to get all progress on the related task or tasks without any additional setup. The connection can be closed upon receiving a message saying the tasks have been completed.

In some cases it may be desired to run the API manually. Some examples would be to do system wide monitoring, monitoring a certain type of task, or combine open network connections.

d3 service does not store any historic data of tasks, if this is desired then it is the duty of the API consumer to store or log all task status messages.

Opening a Connection

To open a connection go to ws://HOSTNAME:80/api/service/task/status, once connected an acknowledgement will be sent showing the current policies. There are no policies set up by default meaning that no updates will be sent.

{
    "tasks": [],
    "acknowledgement": {
        "ignoringPolicies": false,
        "policies": []
    }
}

It is possible to send an initial message when the websocket opens by using query arguments e.g. ws://HOSTNAME:80/api/service/task/status?ignorePolicies=true.

Listening to all tasks

To monitor all task statuses that are happening on that d3 service instance, send the following message:

{
    "ignorePolicies": true
}

This will ignore any previously sent policies and will send all updates including state, informational and progress.

Specifying Policies

A list of policies can be provided to filter the types of information from particular tasks. For instance we can listen only to task state events and ignore progress completely.

An example of setting a policy to listen to a specific task is below:

{
    "ignorePolicies": false,
    "op": "Set",
    "policies": [
        {
            "uid": "task-uid",
            "reports": ["State", "Informational"]
        }
    ]
}

It is possible to set an initial policy by encoding JSON to base64 and using URI arguments: ws://HOSTNAME:80/api/service/task/status?json=base64<DATA> where <DATA> should be replaced by the encoded string.

Policy Operations

When sending a message with a list of policies it is required to send an “op” type so that the API knows what to do with the new list.

Op Type	Description
Set	Replaces all policies with the new list
Add	Adds these policies to the existing list of policies
Remove	Removes this list of policies by UID or type

It is also possible to filter tasks by a specific type (see task types):

{
    "op": "Add",
    "policies": [
        {
            "type": "DownloadTask",
            "reports": ["All"]
        }
    ]
}

Reports

It is possible to filter the types of messages received by specifying a list of reports. The available options are:

Report	Description
All	Receives all of the messages, a convenient replacement for ["State", "Informational", "Progress"]
State	Receives task state messages, such as queued, started, and completed
Informational	Some tasks report useful information periodically
Progress	Most tasks report progress, this can result in a lot of received messages

Response Example

Whenever a task state changes and matches a policy then it will be sent over the connection. If any task updates are sent, all of the fields are populated with the latest information for that task.

{
    "tasks": [
        {
            "info": "",
            "name": "Media provisioning download task",
            "progress": 1.0,
            "state": {
                "state": "Completed",
                "completionReason": "Success"
            },
            "type": "DownloadTask",
            "uid": "task-uid"
        }
    ],
    "acknowledgement": {}
}

Field	Description
name	The name of the task.
type	The type of the task.
uid	A unique identifier for the task.
info	The last info message reported by the task.
state	The last state of the task, see below.
progress	The progress of the task, as a float from 0 to 1.

Task States

The task can be in the following states:

State	Description
Queued	The task has been submitted but has not started yet.
Started	The task has started its work.
Completed	The task is no longer running

There are many reasons a task may be completed, these are:

Completion Reason	Description
Unknown	The task may not have finished yet
Success	The task has completed successfully
Failed	The task had an error and aborted
Cancelled	The user cancelled the task

Task Types

The current task types are:

Task Type	Description
DownloadTask	A task which downloads a file over HTTP to a local path
CopyTask	A task which copies a file, locally or over a network, to a specified local path