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 change",
    "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:

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.

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",
  "change": {
    "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": "4me",
  "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 /changes/:change_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 change, it can be inserted at any position in the change’s 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 -u "api-token:x" -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.4me.com/v1/changes/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

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
category
Required enum — The Category field is used to select the category of the task. Risk & impact tasks are used to help plan changes. Approval tasks are used to collect approvals for changes. These can be used at various stages in the life of the change. Implementation tasks are added to changes for development, installation, configuration, test, transfer and administrative work that needs to be completed for the implementation of the change. Valid values are:
  • risk_and_impact: Risk & Impact
  • approval: Approval
  • implementation: Implementation
change
Required reference to Change — The Change field shows the ID and subject of the change to which the task belongs.
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.
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 Degraded
  • low: Low - Service Degraded for One User
  • medium: Medium - Service Down for One User
  • high: High - Service Degraded for Several Users
  • top: 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.
manager
Readonly reference to Person — The Manager field shows the person who is selected in the Manager field of the change 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.

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.
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”.
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: Registered
  • declined: Declined
  • assigned: Assigned
  • accepted: Accepted
  • in_progress: In Progress
  • waiting_for: Waiting for…
  • failed: Failed
  • rejected: Rejected
  • completed: Completed
  • approved: Approved
  • canceled: 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 to true.
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 to assigned. This field is available only when the Status field is set to waiting_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.