Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

Update API docs for time entries

Klaus Zandersdf7a2ea5744b
diff --git a/docs/api/apiv3/components/schemas/time_entry_collection_model.yml b/docs/api/apiv3/components/schemas/time_entry_collection_model.yml
index b3d204ece0d..66f15d4c53d 100644
--- a/docs/api/apiv3/components/schemas/time_entry_collection_model.yml
+++ b/docs/api/apiv3/components/schemas/time_entry_collection_model.yml
@@ -62,7 +62,7 @@ examples:
project:
href: "/api/v3/projects/1"
title: Some project
- workPackage:
+ entity:
href: "/api/v3/work_packages/1"
title: Some work package
user:
@@ -89,7 +89,7 @@ examples:
project:
href: "/api/v3/projects/42"
title: Some other project
- workPackage:
+ entity:
href: "/api/v3/work_packages/541"
title: Some other work package
user:
diff --git a/docs/api/apiv3/components/schemas/time_entry_model.yml b/docs/api/apiv3/components/schemas/time_entry_model.yml
index 4c4e676dcf7..1fe43546dd6 100644
--- a/docs/api/apiv3/components/schemas/time_entry_model.yml
+++ b/docs/api/apiv3/components/schemas/time_entry_model.yml
@@ -57,6 +57,7 @@ properties:
- project
- user
- activity
+ - entity
properties:
self:
allOf:
@@ -106,13 +107,13 @@ properties:
The project the time entry is bundled in. The project might be different from the work package's project once the workPackage is moved.
**Resource**: Project
- workPackage:
+ entity:
allOf:
- "$ref": "./link.yml"
- description: |-
- The work package the time entry is created on
+ The entity the time entry is created on
- **Resource**: WorkPackage
+ **Resource**: WorkPackage, Meeting
user:
allOf:
- "$ref": "./link.yml"
@@ -158,7 +159,7 @@ examples:
project:
href: "/api/v3/projects/11"
title: DeathStarV2
- workPackage:
+ entity:
href: "/api/v3/work_packages/77"
title: Build new hangar
user:
diff --git a/docs/api/apiv3/paths/time_entries.yml b/docs/api/apiv3/paths/time_entries.yml
index 3b66f27aa37..1635201f60a 100644
--- a/docs/api/apiv3/paths/time_entries.yml
+++ b/docs/api/apiv3/paths/time_entries.yml
@@ -19,7 +19,7 @@ get:
type: integer
- name: pageSize
description: Number of elements to display per page.
- example: '25'
+ example: "25"
in: query
required: false
schema:
@@ -28,15 +28,15 @@ get:
description: |-
JSON specifying sort criteria.
Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:
-
+
+ id: Sort by primary key
-
+
+ hours: Sort by logged hours
-
+
+ spent_on: Sort by spent on date
-
+
+ created_at: Sort by time entry creation datetime
-
+
+ updated_at: Sort by the time the time entry was updated last
example: '[["spent_on", "asc"]]'
in: query
@@ -48,42 +48,44 @@ get:
description: |-
JSON specifying filter conditions.
Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are:
-
- + work_package: Filter time entries by work package
-
- + project: Filter time entries by project
-
- + user: Filter time entries by users
-
- + ongoing: Filter for your ongoing timers
-
+
+ + entity_type: Filter time entries depending on the entity they are logged on. Can either be `WorkPackage` or `Meeting`.
+
+ + entity_id: Filter time entries for the specified entity IDs.
+
+ + project_id: Filter time entries by project
+
+ + user_id: Filter time entries by users
+
+ + ongoing: Filter to only recevie ongoing timers
+
+ spent_on: Filter time entries by spent on date
-
+
+ created_at: Filter time entries by creation datetime
-
+
+ updated_at: Filter time entries by the last time they where updated
-
- + activity: Filter time entries by time entry activity
- example: '[{ "work_package": { "operator": "=", "values": ["1", "2"] } }, { "project": { "operator": "=", "values": ["1"] } }]'
+
+ + activity_id: Filter time entries by time entry activity
+ example: '[{ "entity_type": { "operator": "=", "values": ["WorkPackage"] }}, { "entity_id": { "operator": "=", "values": ["1", "2"] } }, { "project": { "operator": "=", "values": ["1"] } }]'
in: query
required: false
schema:
type: string
responses:
- '200':
+ "200":
description: OK
content:
application/hal+json:
schema:
- $ref: '../components/schemas/time_entry_collection_model.yml'
- '400':
- $ref: '../components/responses/invalid_request_body.yml'
- '403':
+ $ref: "../components/schemas/time_entry_collection_model.yml"
+ "400":
+ $ref: "../components/responses/invalid_request_body.yml"
+ "403":
description: Returned if the client is not logged in and login is required.
content:
application/hal+json:
schema:
- $ref: '../components/schemas/error_response.yml'
+ $ref: "../components/schemas/error_response.yml"
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
@@ -102,17 +104,17 @@ post:
content:
application/json:
schema:
- $ref: '../components/schemas/time_entry_model.yml'
+ $ref: "../components/schemas/time_entry_model.yml"
responses:
- '201':
+ "201":
description: Created
content:
application/hal+json:
schema:
- $ref: '../components/schemas/time_entry_model.yml'
- '400':
- $ref: '../components/responses/invalid_request_body.yml'
- '403':
+ $ref: "../components/schemas/time_entry_model.yml"
+ "400":
+ $ref: "../components/responses/invalid_request_body.yml"
+ "403":
description: |-
Returned if the client does not have sufficient permissions.
@@ -120,18 +122,18 @@ post:
content:
application/hal+json:
schema:
- $ref: '../components/schemas/error_response.yml'
+ $ref: "../components/schemas/error_response.yml"
examples:
response:
value:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
- '406':
- $ref: '../components/responses/missing_content_type.yml'
- '415':
- $ref: '../components/responses/unsupported_media_type.yml'
- '422':
+ "406":
+ $ref: "../components/responses/missing_content_type.yml"
+ "415":
+ $ref: "../components/responses/unsupported_media_type.yml"
+ "422":
description: |-
Returned if:
@@ -139,7 +141,7 @@ post:
content:
application/hal+json:
schema:
- $ref: '../components/schemas/error_response.yml'
+ $ref: "../components/schemas/error_response.yml"
examples:
response:
value:
diff --git a/docs/api/apiv3/tags/time_entries.yml b/docs/api/apiv3/tags/time_entries.yml
index 9c56a9e172e..434a1b4f5cf 100644
--- a/docs/api/apiv3/tags/time_entries.yml
+++ b/docs/api/apiv3/tags/time_entries.yml
@@ -17,13 +17,14 @@ description: |-
| :-----------: | -------------------------------------------------------------- | ------------- | --------------------- | -------------------- | --------------------------------------------------------- |
| self | This time entry | TimeEntry | not null | READ | |
| project | The project the time entry is bundled in. The project might be different from the work package's project once the workPackage is moved. | Project | not null | READ / WRITE | |
- | workPackage | The work package the time entry is created on | WorkPackage | | READ / WRITE | |
+ | workPackage | **DEPRECATED** The work package the time entry is created on | WorkPackage | | READ / WRITE | |
+ | entity | The entity for which the time entry is created on | WorkPackage|Meeting | | READ / WRITE | |
| user | The user the time entry tracks expenditures for | User | not null | READ / WRITE | **Permission**: Log time for other users permission |
| activity | The time entry activity the time entry is categorized as | TimeEntriesActivity | | READ / WRITE | |
Depending on custom fields defined for time entries, additional links might exist.
- Time entries are either linked to a work package or to a project. If they are linked to a project, the work package reference is empty. If they are linked to a work package, the project reference is filled up automatically to point to the work package's project.
+ Time entries are either linked to a work package or a meeting, the project reference is filled up automatically to point to the entity's project.
## Local Properties