Project Tasks API

• List project tasks
• Get a single project task
• Create a project task
• Update a project task
• Delete a project task
• Fields

List project tasks

List all project tasks for an account:

GET /project_tasks

Response

status: 200 OK

[
  {
    "id": 24554,
    "sourceID": null,
    "phase": {
      "completed_at": null,
      "created_at": "2016-12-23T05:09:06-06:00",
      "id": 314,
      "name": "Implementation",
      "position": 3,
      "started_at": "2016-12-23T05:09:06-06:00",
      "status": "in_progress",
      "updated_at": "2016-12-23T05:09:06-06:00"
    },
    "subject": "Go-live",
    "category": "milestone",
    "status": "registered",
    "completion_target_at": "2017-03-01T09:43:00-06:00",
    "finished_at": null,
    "created_at": "2017-01-18T09:42:39-06:00",
    "updated_at": "2017-01-18T09:42:39-06:00"
  },
  {
    "id": 24553,
    "sourceID": null,
    "phase": {
      "completed_at": null,
      "created_at": "2016-12-23T05:09:06-06:00",
      "id": 314,
      "name": "Implementation",
      "position": 3,
      "started_at": "2016-12-23T05:09:06-06:00",
      "status": "in_progress",
      "updated_at": "2016-12-23T05:09:06-06:00"
    },
    "subject": "Training",
    "category": "activity",
    "status": "in_progress",
    "completion_target_at": "2017-03-01T09:43:00-06:00",
    "finished_at": null,
    "created_at": "2017-01-18T09:42:39-06:00",
    "updated_at": "2017-02-23T10:18:52-06:00"
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of project tasks.

Predefined Filters

The following predefined filters are available:

• /project_tasks/finished: List all finished project tasks
• /project_tasks/open: List all open project tasks
• /project_tasks/managed_by_me: List all project tasks which manager is the API user
• /project_tasks/assigned_to_me: List all project tasks that are assigned to the API user
• /project_tasks/open_to_me: List all project tasks that are assigned to the API user and which status is ‘Assigned’, ‘Accepted’, ‘In Progress’ or ‘Waiting for…’

Collection Fields

By default the following fields will appear in collections of Tasks:

id sourceID subject category status 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 category status completion_target_at finished_at created_at updated_at

Sorting

By default a collection of project tasks is sorted descending by id.

The following fields are accepted by the ?sort= parameter:

id sourceID subject category status completion_target_at finished_at created_at updated_at

Response

The response is similar to the response in List project tasks

Get a single project task

GET /project_tasks/:id

Response

status: 200 OK

{
  "anticipated_assignment_at": "2017-02-23T09:43:00-06:00",
  "assigned_at": "2017-02-23T09:04:17-06:00",
  "attachments": [],
  "category": "activity",
  "completion_target_at": "2017-03-01T09:43:00-06:00",
  "created_at": "2017-01-18T09:42:39-06:00",
  "custom_fields": null,
  "deadline": null,
  "finished_at": null,
  "id": 24553,
  "instructions": "Conduct the training for all participants.",
  "manager": {
    "id": 156,
    "name": "Ellen Brown",
    "account": {
      "id": "widget",
      "name": "Widget International"
    }
  },
  "phase": {
    "completed_at": null,
    "created_at": "2016-12-23T05:09:06-06:00",
    "id": 314,
    "name": "Implementation",
    "position": 3,
    "started_at": "2016-12-23T05:09:06-06:00",
    "status": "in_progress",
    "updated_at": "2016-12-23T05:09:06-06:00"
  },
  "planned_duration": 1920,
  "project": {
    "id": 4021,
    "subject": "Best in Customer Satisfaction (BICS)"
  },
  "required_approvals": null,
  "source": null,
  "sourceID": null,
  "start_at": null,
  "status": "in_progress",
  "subject": "Training",
  "supplier": null,
  "supplier_requestID": null,
  "template": {
    "id": 822,
    "subject": "Training"
  },
  "updated_at": "2017-02-23T10:18:52-06:00",
  "urgent": false,
  "waiting_until": null
}

The response contains these fields.

Create a Project Task

POST /projects/:project_id/tasks

When creating a new project task these fields are available.

Response

status: 201 Created

{
  "anticipated_assignment_at": "...",
  "...": "..."
}

The response contains all fields of the created project task and is similar to the response in Get a single project task

Predecessors and Successors

When a new project task is added to an existing project, it can be inserted at any position in the project’s workflow. To do this, the predecessor(s) and successor(s) can be specified for the new project task. The following is a CURL example for creating a new project 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":[24551,24552],"successor_ids":[24554]}' \
       https://api.4me.com/v1/projects/4021/project_tasks

Update a Project Task

PATCH /project_tasks/:id

When updating a project task these fields are available.

Response

status: 200 OK

{
  "anticipated_assignment_at": "...",
  "...": "..."
}

The response contains all fields of the updated project task and is similar to the response in Get a single project task

Delete a Project Task

DELETE /project_tasks/:id

Response

status: 204 No Content

Fields

agile_board

Optional reference to Agile Board — The Agile board on which the project task is placed.

agile_board_column

Optional reference to Agile Board Column — The column of the agile board on which the project task is placed.

agile_board_column_position

Optional integer — The Position field is used to specify the position of the project 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 project 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 project task is assigned.

attachments

Readonly aggregated Attachments

Use Project tasks - Notes API to get note attachments.

category

Required enum — The Category field is used to select the category of the project task. Activity tasks are used to assign project-related work to people. Approval tasks are used to collect approvals for projects. Milestones are used to mark specific points along a project’s implementation plan. Valid values are:

• activity: Activity
• approval: Approval
• milestone: Milestone

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 project task is expected to be completed.

created_at

Readonly datetime — The date and time at which the project task was created.

custom_fields

Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the project task template that was used to register the project task.

custom_fields_attachments

Writeonly attachments The attachments used in Custom fields.

deadline

Optional datetime — The Deadline field is used to specify the date and time at which the milestone needs to have been reached.

finished_at

Optional datetime — The Finished field is automatically set to the date and time at which the project task is saved with the status “Failed”, “Rejected”, “Completed”, “Approved” or “Canceled”.

id

Readonly integer — The unique ID of the project task.

instructions

Optional text (max 64KB) — The Instructions field is used to provide instructions for the person(s) to whom the project 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 project that this project task belongs to.

note

Optional text (max 64KB) — The Note field is used to provide information for the person to whom the project 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

Readonly reference to Phase — The Phase field is used to select the phase of the project to which the project 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 project 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 team is expected to spend working on the project task.

project

Required reference to Project — The Project field shows the ID and subject of the project to which the project task belongs.

required_approvals

Optional integer, default: 1 — The Required approvals field is used to specify the number of assignees who need to have provided their approval before the status of the project 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 and finished_at values.

skill_pool

Optional reference to Skill Pool — The Skill Pool field is used to select the skill pool to whom the project 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 project 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 project task. Valid values are:

• registered: Registered
• 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 project 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 project 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 project task has been registered at the supplier organization.

team

Optional reference to Team — The Team field is used to select the Team to which the project task is to be assigned.

template

Required reference to Task Template — The Template field contains the link to the project task template that was used to register the project task.

time_spent

Optional integer — The Time spent field is used to enter the time that you have spent working on the project task since you started to work on it or, if you already entered some time for this project 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 project task. If the project task has no updates it contains the created_at value.

urgent

Optional boolean, default: false — The project task can be marked as urgent by setting the Urgent field to true.

waiting_until

Optional datetime — The Waiting until field is used to specify the date and time at which the status of the project task is to be updated from waiting_for to assigned. This field is available only when the Status field is set to waiting_for.

The Waiting until field cannot be specified in the ?fields= parameter.

work_hours_are_24x7

Optional boolean, default: false — When set to true, the completion target of the project task is calculated using a 24x7 calendar rather than normal business hours.