Time
A worklog: minutes of work booked by one employee against one project on one calendar day, optionally attached to a task and a work item.
- Summary view
- TimeList, 23 fields. What a list returns by default.
- Detail view
- Time, 25 fields. The default for a single read and for every write.
- Read with
- api:
read: andhours::times read - Write with
- api:
write: times
Billability is inferred from the task, and overriding the inference needs a billable_change_reason. An entry that exceeds its budget, or whose billability was overridden, enters a reviewer's queue until a reviewer settles it; while it sits there, and forever after it has been invoiced, it is locked against changes.
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.
The project the hours are booked against, always expanded. Its customer_id is the customer to fetch with GET /api/v2/customers/{customer}; the customer itself is not nested.
Budget the hours are invoiced against. Derived from the task, never accepted on a write; null when no task is set or the budget is deleted.
The budget the hours are invoiced against. Expanding it with ?include=budget additionally requires the budgets::read permission and a token scope covering the budgets prefix.
Task the hours are booked on; null when the entry is not attached to one, or once that task is deleted.
The task the hours are booked on. Expanding it with ?include=task additionally requires the kanban::manage_self permission and a token scope covering the kanban prefix, and is limited to the tasks you can see on the tasks collection.
Work item the hours are attached to; null when the entry is not attached to one, or once that work item is deleted.
The work item the hours are attached to, always expanded.
Employee the hours belong to. Assigned on create (from the authenticated user, or from on_behalf_of_user_id) and never writable afterwards; reassigning a worklog is a DELETE plus a POST.
The employee the hours belong to. Expanding it with ?include=user additionally requires the users::read permission and a token scope covering the users prefix.
Whether these hours are excluded from invoicing. Inferred from the task's is_billable flag (false without a task) on create and again whenever task_id is sent. Sending a value that differs from the inferred or current one requires billable_change_reason and puts the entry in a reviewer's queue; without it the write is a 422 on /billable_change_reason.
Whether the hours count as overtime. Sending it without the times::write_overtime permission leaves it false and adds an input_ignored warning rather than failing the write.
Whether the entry was booked knowing it exceeds its budget. Set on create only, and true whenever a reason is sent; setting it puts the entry in a reviewer's queue.
Why the budget overrun was accepted. Sending it on create marks the entry as exceeding its budget. Once a reviewer has settled the entry it can no longer be changed: a PATCH that does answers 409 reason_reviewed.
Why the inferred billability was overridden. Required whenever is_not_billable is sent with a value that differs from the inferred or current one, on create and on PATCH alike; the override puts the entry in a reviewer's queue, reopening one a reviewer had already settled.
The reviewer who settled the entry, once one has. Set by the review queue in plnnrly; this API exposes no way to write it.
The invoice these hours were billed on, once they have been. While it is set, the entry is locked: a write answers 409 with conflict.reason locked_by_invoice.
The sales-invoice line these hours were billed on, once they have been. Set by the invoicing flow.
Variants
TimeList 23 fields
What a collection returns, and what ?view=summary returns on a single record.
Leaves out: reason, billable_change_reason
TimeSummary 3 fields
The embedded form: what you get when another resource carries this one and you did not include it.
Leaves out: description, project_id, project, budget_id, budget, task_id, task, work_item_id, work_item, user_id, user, is_not_billable, is_overtime, exceeded_budget, reason, billable_change_reason, reviewed_by, invoice_id, sales_invoice_row_id, created_at, updated_at, links
TimeLinks 1 field
The links object on this resource.
Keys: self
Something wrong or missing on this page? Tell us