Task Status API

Name taskStatus
URI /api/taskStatus
URL Example http://localhost:2468/api/taskStatus
Description This API makes it possible to retrieve and set the completion date for a particular task.
Context Personal dashboard only, for a leaf task within the hierarchy
HTTP Methods
  • GET - retrieves the current completion date for a leaf task
  • POST - sets or clears the completion date for a leaf task

HTTP GET

Retrieves the current completion date for a task in the personal hierarchy.

By default, invocations of this GET method will be rejected unless they originate from the same computer where the Process Dashboard is running. This policy can be disabled by setting an advanced preference with the name api.taskStatus.allowRemote and the value true.

Request Parameters

FieldTypeDescription
hierarchyPath (optional) String The full dashboard hierarchy path to the project and component/task whose status should be returned. (Example: /Project/My Team Project/Component A/Code).

The path must name a leaf task in the dashboard hierarchy.

This parameter is optional. If omitted, the default is to use the task which is currently selected in the Process Dashboard toolbar.

Errors

Error CodeDescription
personal-only Returned if this request is made against a team dashboard instead of a personal dashboard.
no-such-task The hierarchyPath parameter names a task that does not exist in the dashboard hierarchy.
not-leaf-task The hierarchyPath parameter names a task that has children (rather than a leaf task).

Results

application/json - successful completion examples

{
    "stat" : "ok",
    "taskPath" : "/Project/Team Project/Component/Task 1",
    "completionDate" : "2015-01-02 13:45:56"
}
{
    "stat" : "ok",
    "taskPath" : "/Project/Team Project/Component/Task 2",
    "completionDate" : null
}

application/json - error example

{
    "stat" : "fail",
    "err" : {
        "code" : "no-such-task",
        "msg" : "The task '/Foo/Bar/Baz' was not found."
    }
}

HTTP POST

Sets or clears the completion date for a task in the personal hierarchy.

By default, invocations of this POST method will be rejected unless they originate from the same computer where the Process Dashboard is running. This policy can be disabled by setting an advanced preference with the name api.taskStatus.allowRemote and the value true.

Request Parameters

FieldTypeDescription
hierarchyPath (optional) String The full dashboard hierarchy path to the project and component/task whose completion status should be altered. (Example: /Project/My Team Project/Component A/Code).

The path must name a leaf task in the dashboard hierarchy.

This parameter is optional. If omitted, the default is to use the task which is currently selected in the Process Dashboard toolbar.

completionDate Date The date to store for the given task. The following legal values are recognized:
  • null - to mark this task incomplete
  • now - to mark this task complete with the current date/time
  • YYYY-MM-DD HH:MM:SS - the completion date/time to store for this task, recorded in the local time zone.

Errors

Error CodeDescription
personal-only Returned if this request is made against a team dashboard instead of a personal dashboard.
no-such-task The hierarchyPath parameter names a task that does not exist in the dashboard hierarchy.
not-leaf-task The hierarchyPath parameter names a task that has children (rather than a leaf task).
date-not-editable The completion date cannot be set for the given task. For example, this could occur if the given task is the root node of a team project, for an individual who has not been assigned any tasks. Because no tasks are present, the node happens to be a leaf in the dashboard hierarchy; but it still represents a container for future project work and cannot be marked complete itself.
parameter-invalid The completionDate parameter is not in the expected format.

Results

application/json - successful completion

{
    "stat" : "ok"
}

application/json - error example

{
    "stat" : "fail"
    "err" : {
        "code" : "parameter-invalid",
        "msg" : "The 'completionDate' parameter value 'foo' is not a valid date",
        "param" : "completionDate"
    }
}