WorkItem
A work item: the unit of work a project's backlog and board are made of, addressed by numeric id or by its human-readable issue key (ACM-123) on the same path.
- Summary view
- WorkItemList, 39 fields. What a list returns by default.
- Detail view
- WorkItem, 44 fields. The default for a single read and for every write.
It carries a title, a rich-text description, an estimate, a priority and a position in its project's workflow, and it is the parent of comments, checklist subtasks, attachments, links to other work items and its own child work items. Moving it to another workflow status is not a PATCH: the move is validated against the project workflow, so it lives at POST work-items/{work_item}/actions/transition.
Used by
Fields
- Detail only
- Only in the detail view.
- Only with include
- Only when you ask for it with include.
- Server-assigned
- Set by plnnrly, never by a request.
Human-readable key, e.g. ACM-123, allocated by the server from the project's customer code and a per-customer sequence. It also works in the path: GET work-items/ACM-123 works. This is one of the two fields ?q= searches.
Work item description. HTML from the rich editor, sanitised on read and on write. Mention spans are preserved verbatim, so pass them back unchanged. Detail view only.
Relative priority. Defaults to normal on create; null only on a legacy item that was never prioritised.
highesthighnormallowlowest
New values may be added.
Remaining estimate, in minutes. Null where none was entered, in which case plnnrly derives one from the estimate and the logged time.
Name of the place the work happens, as picked from the address search in plnnrly. Null when no location was set. Send it together with location_latitude and location_longitude; null all three to clear the location. Detail view only.
Formatted address of the location, when the place has one. Detail view only.
Latitude of the location in decimal degrees, -90 to 90. Detail view only.
Longitude of the location in decimal degrees, -180 to 180. Detail view only.
Position within the sprint or backlog, and the default sort. Not writable through PATCH: move an item with POST work-items/{work_item}/actions/move and list: backlog.
Position within the board column. Not writable through PATCH: move a card with POST work-items/{work_item}/actions/move and list: board.
Revision counter, bumped once per write. It is the ETag's revision: send it back as If-Match to detect a concurrent edit, which answers 412.
Project this work item belongs to. It cannot change: the issue key was allocated from the project's customer code.
Kanban task this work item is booked against, when it is booked against one. It must belong to the item's project. A sprint project books the running sprint's hours through it, so an item in that project's running sprint needs one; a simple-mode project does not. Setting it also makes the task's owner the assignee. Follow it to /api/v2/tasks/{task}.
Current workflow status. Not writable through PATCH: moving between statuses is POST work-items/{work_item}/actions/transition, because the move is validated against the project workflow.
User the work is assigned to. Null on an unassigned item. On a sprint project, setting it also moves the item to that user's only open task in the same budget, or in the project when the item has no task yet; with several or no candidates the task is left as it is.
User who filed the work item. Always the authenticated user at create time; there is no way to file on somebody else's behalf.
Absolute URL that opens this work item in plnnrly, on the organisation's own hostname. It is a stable link, safe to store: it redirects to the first of the project's backlog, all-work list or board the signed-in user may open, and opens the item there; it lands on the project page when none of them applies. Read-only.
The workflow status this item currently sits in. Always present.
The parent work item, on a sub-issue.
The user the work is assigned to. Expanding it additionally requires the users prefix's read grant and a token scope covering it.
The user who filed the work item. Expanding it additionally requires the users prefix's read grant and a token scope covering it.
The work type of this item. Expanding it additionally requires the work_types prefix's read grant and a token scope covering it.
The sprint this item sits in, when it is not in the backlog.
Number of linked drive documents the caller may open. Archived documents are not counted.
Show 8 child fields
Every label on this work item, paginated. Present only while the Sprints feature is enabled, as GET /labels is.
Labels on this work item. label_ids takes at most 50 ids and replaces the whole set: a label you leave out is removed. Build it from links.labels, which lists every label while the Sprints feature is enabled, not from include=labels, which stops at 25.
Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.
Drive documents linked to this work item that you may open. drive_item_ids takes at most 25 ids and replaces the whole set: a document you leave out is unlinked, and so is every linked document you cannot open. Build it from links.drive_items, not from include=drive_items, which stops at 25. Expanding it additionally requires the project_drive prefix's access grant and a token scope covering it.
Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.
Show 5 child fields
The kind of record owner points at; it says which branch of owner applies.
projectcustomerorganizationuser
New values may be added.
The project, customer, organisation or user whose drive this item lives in.
Which form you get depends on owner_type.
projectRefcustomerReforganizationRefuserRef
Comments on this work item, newest first, capped at 25. Follow links.comments for the rest.
Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.
Checklist subtasks on this work item, capped at 25. Follow links.subtasks for the rest.
Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.
Variants
WorkItemList 39 fields
What a collection returns, and what ?view=summary returns on a single record.
Leaves out: description, location_name, location_address, location_latitude, location_longitude
WorkItemSummary 3 fields
The embedded form: what you get when another resource carries this one and you did not include it.
Leaves out: description, priority, due_date, estimation, remaining_estimate, location_name, location_address, location_latitude, location_longitude, order, column_order, version, created_at, updated_at, project_id, task_id, workflow_status_id, work_type_id, sprint_id, parent_id, assignee_id, reporter_id, web_url, workflow_status, parent, assignee, reporter, work_type, sprint, labels, drive_items, comments, subtasks, comments_count, subtasks_count, attachments_count, child_work_items_count, labels_count, drive_items_count, links_count, links
WorkItemLinks 8 fields
The links object on this resource.
Keys: self, comments, subtasks, links, attachments, child_work_items, labels, drive_items
Something wrong or missing on this page? Tell us