Tasks API
List tasks
List all tasks for an account:
GET /tasks
Response
Status: 200 OK
[
{
"created_at": "2016-03-14T03:14:17-06:00",
"category": "implementation",
"finished_at": null,
"sourceID": null,
"updated_at": "2016-03-14T03:14:17-06:00",
"member": {
"name": "Barney Turban",
"id": 58
},
"subject": "Inform approvers and requesters of the completion of the workflow",
"id": 95,
"impact": "none",
"team": {
"name": "Windows Servers",
"id": 14
},
"status": "registered",
"completion_target_at": "2016-03-15T16:33:00-06:00"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of tasks.
Predefined Filters
The following predefined filters are available:
/tasks/finished
: List all finished tasks/tasks/open
: List all open tasks/tasks/managed_by_me
: List all tasks that are part of a workflow which manager is the API user/tasks/assigned_to_my_team
: List all tasks that are assigned to one of the teams that the API user is a member of/tasks/assigned_to_me
: List all tasks that are assigned to the API user/tasks/approval_by_me
: List all approval tasks that are assigned to the API user and which status in different from ‘Registered’
Collection Fields
By default the following fields will appear in collections of tasks:
id
sourceID
subject
impact
category
status
team
member
completion_target_at
finished_at
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Filtering
Filtering is available for the following fields:
id
source
sourceID
subject
impact
category
status
team
member
completion_target_at
finished_at
created_at
updated_at
template
workflow
Sorting
By default a collection of tasks is sorted descending by id
.
The following fields are accepted by the ?sort= parameter:
id
sourceID
subject
impact
category
status
team
member
completion_target_at
finished_at
created_at
updated_at
Response
The response is similar to the response in List tasks
Get a single task
GET /tasks/:id
Response
Status: 200 OK
{
"created_at": "2016-03-14T03:14:13-06:00",
"category": "approval",
"sourceID": null,
"finished_at": "2009-02-04T08:51:00-06:00",
"anticipated_assignment_at": null,
"updated_at": "2016-03-14T03:14:13-06:00",
"supplier": null,
"new_assignment": false,
"member": null,
"manager": {
"name": "Carla Cluster",
"id": 54
},
"instructions": null,
"assigned_at": "2009-02-03T03:08:00-06:00",
"workflow": {
"id": 238,
"subject": "Install new rack"
},
"supplier_requestID": null,
"subject": "Service owner approval and floor space assignment for new rack",
"start_at": null,
"id": 2,
"planned_duration": 720,
"planned_effort": null,
"required_approvals": 3,
"impact": null,
"team": null,
"status": "approved",
"source": "R-Service",
"completion_target_at": null,
"template": {
"id": 28,
"subject": "Service owner approval"
},
"custom_fields": null,
"waiting_until": null
}
The response contains these fields.
Create a task
POST /workflows/:workflow_id/tasks
When creating a new task these fields are available.
Response
Status: 201 Created
{
"anticipated_assignment_at": "...",
"...": "..."
}
The response contains all fields of the created task and is similar to the response in Get a single task
Predecessors and Successors
When a new task is added to an existing workflow, it can be inserted at any position in the workflow. To do this, the predecessor(s) and successor(s) can be specified for the new task. The following is a CURL example for creating a new task with two predecessor relations and one successor relation:
$ curl -H "Authorization: Bearer <oauth-token>" \ -H "X-4me-Account: wdc" \ -X POST \ -d '{"subject":"Perform extra manual test","category":"implementation","planned_duration":600,"team_id":128,"impact":"none","predecessor_ids":[21126,21127],"successor_ids":[21128]}' \ https://api.r-service.tech/v1/workflows/5694/tasks
Update a task
PATCH /tasks/:id
When updating a task these fields are available.
Response
Status: 200 OK
{
"anticipated_assignment_at": "...",
"...": "..."
}
The response contains all fields of the updated task and is similar to the response in Get a single task
Fields
- agile_board
- Optional reference to Agile Board — The Agile board on which the task is placed.
- agile_board_column
- Optional reference to Agile Board Column — The column of the agile board on which the task is placed.
- agile_board_column_position
- Optional integer — The Position field is used to specify the position of the task, relative to the other items within the column of the agile board. The topmost item has position 1.
- anticipated_assignment_at
- Readonly datetime — The Anticipated assignment field shows the date and time at which the task is currently expected to be assigned.
- assigned_at
- Optional datetime — The Assigned field is automatically set to the current date and time when the task is assigned.
- attachments
- Readonly aggregated Attachments
- Use Tasks - Notes API to get note attachments.
- category
- Required enum — The Category field is used to select the category of the task. Risk & impact tasks are used to help plan workflows. Approval tasks are used to collect approvals for workflows. These can be used at various stages in the life of the workflow. Implementation tasks are added to workflows for development, installation, configuration, test, transfer and administrative work that needs to be completed for the implementation of the workflow. Valid values are:
-
risk_and_impact
: Risk & Impactapproval
: Approvalimplementation
: Implementationautomation
: Automation
- checked_items
- Optional array of string — The names of the checklist items that are checked within the instructions field.
- completion_target_at
- Readonly datetime — The Completion target field shows the date and time at which the task is expected to be completed.
- created_at
- Readonly datetime — The date and time at which the task was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the task template that was used to register the task.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- failure_task
- Optional reference to Task — The task that will be assigned in case this task is failed or rejected.
- finished_at
- Optional datetime — The Finished field is automatically set to the date and time at which the task is saved with the status “Failed”, “Rejected”, “Completed”, “Approved” or “Canceled”.
- id
- Readonly integer — The unique ID of the task.
- impact
- Optional enum — The Impact field is used to select the extent to which the Service Instances related to the task will be impacted by the completion of the task. Valid values are:
-
none
: None - Service Not Degradedlow
: Low - Service Degraded for One Usermedium
: Medium - Service Down for One Userhigh
: High - Service Degraded for Several Userstop
: Top - Service Down for Several Users
- instructions
- Optional text (max 64KB) — The Instructions field is used to provide instructions for the person to whom the task will be assigned.
- instructions_attachments
- Writeonly attachments The attachments used in the Instructions field.
- manager
- Readonly reference to Person — The Manager field shows the person who is selected in the Manager field of the workflow that this task belongs to.
- member
- Optional reference to Person — The Member field is used to select the person to whom the task is to be assigned. This field’s value is
null
in case of an approval task with multiple approvers (see Approvals). - new_assignment
- Readonly boolean — default:
false
- note
- Optional text (max 64KB) — The Note field is used to provide information for the person to whom the task is assigned. It is also used to provide a summary of the actions that have been taken to date and the results of these actions.
-
The Note field cannot be specified in the ?fields= parameter.
- note_attachments
- Writeonly attachments The attachments used in the Note field.
- phase
- Optional reference to Phase — The Phase field is used to select the phase of the workflow to which the task belongs.
- planned_duration
- Required integer (max 600000) — The Planned duration field is used to enter the number of minutes it is expected to take for the task to be completed following its assignment, or following its fixed start date and time if the Start no earlier than field is filled out.
- planned_effort
- Optional integer (max 600000) — The Planned effort field is used to specify the number of minutes the member is expected to spend working on the task.
- provider_not_accountable
- Readonly boolean — The Provider not accountable field value is used to indicate whether the provider is not to be accountable for the affected SLAs linked to the requests that are linked to the workflow of the task, as long as the task is active.
- rejection_count
- Readonly integer — The Rejection count field is incremented on (each) rejection of an approval task.
- request
- Optional reference to Request — The Request field is visible only after a request has been generated by the task. This field shows the Request that was generated. As soon as this request has been completed with the completion reason “Solved”, the task’s status is set to “Completed”.
- request_template
- Optional reference to Request Template — The Request template field is used to select the Request template that must be used to generate a new request when the status of the task is set to “Assigned”, “Accepted” or “In Progress”.
- request_service_instance
- Optional reference to Service Instance — The Service instance field is used to select the Service instance that must be applied to the new request that is generated when the status of the task is set to “Assigned”, “Accepted” or “In Progress”.
- required_approvals
- Optional integer, default:
1
— The Required approvals field is used in approval tasks to specify the number of approvers who need to have provided their approval before the status of the task gets updated to “Approved”. - resolution_duration
- Readonly integer — The number of minutes it took to complete this problem, which is calculated as the difference between the
assigned_at
andfinished_at
values. - skill_pool
- Optional reference to Skill Pool — The Skill Pool field is used to select the skill pool to whom the task is to be assigned.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- start_at
- Optional datetime — The Start no earlier than field is only used when work on the task may not start before a specific date and time.
- status
- Optional enum, default:
registered
— The Status field is used to select the current status of the task. Valid values are: -
registered
: Registereddeclined
: Declinedassigned
: Assignedaccepted
: Acceptedin_progress
: In Progresswaiting_for
: Waiting for…waiting_for_customer
: Waiting for Customerrequest_pending
: Request Pendingfailed
: Failedrejected
: Rejectedcompleted
: Completedapproved
: Approvedcanceled
: Canceled
- subject
- Required string (max 255) — The Subject field is used to enter a short description of the objective of the task.
- supplier
- Optional reference to Organization — The Supplier field is used to select the supplier organization that has been asked to assist with the completion of the task.
- supplier_requestID
- Optional string (max 255) — The Supplier request ID field is used to enter the identifier under which the request to help with the execution of the task has been registered at the supplier organization.
- team
- Required reference to Team — The Team field is used to select the Team to which the task is to be assigned.
- template
- Required reference to Task Template — The Template field contains the link to the task template that was used to register the task.
- time_spent
- Optional integer — The Time spent field is used to enter the time that you have spent working on the task since you started to work on it or, if you already entered some time for this task, since you last added your time spent in it.
-
This field cannot be specified in the ?fields= parameter.
- time_spent_effort_class
- Optional reference to Effort Class — The Effort class field is used to select the effort class that best reflects the type of effort for which time spent is being registered.
-
This field cannot be specified in the ?fields= parameter.
- updated_at
- Readonly datetime — The date and time of the last update of the task. If the task has no updates it contains the
created_at
value. - urgent
- Optional boolean, default:
false
— When the task has been marked as urgent, the Urgent field is set totrue
. - waiting_until
- Optional datetime — The Waiting until field is used to specify the date and time at which the status of the task is to be updated from
waiting_for
toassigned
. This field is available only when the Status field is set towaiting_for
. - work_hours_are_24x7
- Optional boolean, default:
false
— When set to true, the completion target of the task is calculated using a 24x7 calendar rather than normal business hours. - workflow
- Required reference to Workflow — The Workflow field shows the ID and subject of the workflow to which the task belongs.