OpenProject Work Packages API

The work packages endpoints return collections or single entities of type `WorkPackage`. The following tables list the different propertiesof `WorkPackage` entities.## Actions| Link | Description | Condition ||:-------------------:|--------------------------------------------------------------------------| ---------------------------------------|| addAttachment | Attach a file to the WP | **Permission**: edit work package || addComment | Post comment to WP | **Permission**: add work package notes || addRelation | Adds a relation to this work package. | **Permission**: manage wp relations || addWatcher | Add any user to WP watchers | **Permission**: add watcher || customActions | Collection of predefined changes that can be applied to the work package | || logTime | Log time on the work package | **Permission**: Log time, Log own time || previewMarkup | Post markup (in markdown) here to receive an HTML-rendered response | || removeWatcher | Remove any user from WP watchers | **Permission**: delete watcher || unwatch | Remove current user from WP watchers | logged in; watching || update | Form endpoint that aids in preparing and performing edits on a WP | **Permission**: edit work package || updateImmediately | Directly perform edits on a work package | **Permission**: edit work package || watch | Add current user to WP watchers | logged in; not watching || delete | Delete this work package | **Permission**: delete work package |## Linked Properties| Link | Description | Type | Constraints | Supported operations | Condition || :--------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------------------------- | --------------------- | ----------------------------------------- || self | This work package | WorkPackage | not null | READ | || schema | The schema of this work package | Schema | not null | READ | || ancestors | Array of all visible ancestors of the work package, with the root node being the first element | Collection | not null | READ | **Permission** view work packages || attachments | The files attached to this work package | Collection | not null | READ / WRITE | || author | The person that created the work package | User | not null | READ | || assignee | The person that is intended to work on the work package | User | | READ / WRITE | || availableWatchers | All users that can be added to the work package as watchers. | User | | READ | **Permission** add work package watchers || budget | The budget this work package is associated to | Budget | | READ / WRITE | **Permission** view cost objects || category | The category of the work package | Category | | READ / WRITE | || children | Array of all visible children of the work package | Collection | not null | READ | **Permission** view work packages || parent | Parent work package | WorkPackage | Needs to be visible (to the current user) | READ / WRITE | || priority | The priority of the work package | Priority | not null | READ / WRITE | || project | The project to which the work package belongs | Project | not null | READ / WRITE | || projectPhase | The project phase this work package is assigned to | ProjectPhase | | READ / WRITE | **Permission** view project phases. There has to be a project phase active in the project. || projectPhaseDefinition | The project phase definition for the project phase of this work package. | ProjectPhaseDefinition | | READ | **Permission** view project phases. The associated project phase has to be active. || responsible | The person that is responsible for the overall outcome | User | | READ / WRITE | || relations | Relations this work package is involved in | Relation | | READ | **Permission** view work packages || revisions | Revisions that are referencing the work package | Revision | | READ | **Permission** view changesets || status | The current status of the work package | Status | not null | READ / WRITE | || sprint | The sprint the work package is planned in | Sprint | | READ / WRITE | **Permission** view sprints || subject | The subject of the work package | String | not null; 1 0 | READ | || lockVersion | The version of the item as used for optimistic locking | Integer | | READ | || subject | Work package subject | String | not null; 1 <= length <= 255 | READ / WRITE | Is write protected if the type has automatic subject generation configured. || status | Name of the work package's status | String | not null | READ | || type | Name of the work package's type | String | not null | READ | || description | The work package description | Formattable | | READ / WRITE | || scheduleManually | Uses manual scheduling mode when true (default). Uses automatic scheduling mode when false. Can be automatic only when predecessors or children are present. | Boolean | | READ / WRITE | || startDate | Scheduled beginning of a work package | Date | Cannot be set for parent work packages unless it is scheduled manually; must be equal or greater than the earliest possible start date; Exists only on work packages of a non milestone type | READ / WRITE | || dueDate | Scheduled end of a work package | Date | Cannot be set for parent work packages unless it is scheduled manually; must be greater than or equal to the start date; Exists only on work packages of a non milestone type | READ / WRITE | || date | Date on which a milestone is achieved | Date | Exists only on work packages of a milestone type | READ / WRITE | || derivedStartDate | Similar to start date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate. | Date | | READ | || derivedDueDate | Similar to due date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate. | Date | | READ | || duration | The amount of time in hours the work package needs to be completed. | Duration | Not available for milestone type of work packages. | READ / WRITE | || estimatedTime | Corresponds to work. Time a work package likely needs to be completed. | Duration | | READ / WRITE | || derivedEstimatedTime | Corresponds to total work. Time a work package likely needs to be completed including itself and its descendants. | Duration | | READ | || remainingTime | Corresponds to remaining work. Remaining time a work package likely needs to be completed. | Duration | | READ / WRITE | || derivedRemainingTime | Corresponds to total remaining work. Remaining time a work package likely needs to be completed including itself and its descendants. | Duration | | READ | || ignoreNonWorkingDays | When scheduling, whether or not to ignore the non working days being defined. A work package with the flag set to true will be allowed to be scheduled to a non working day. | Boolean | Cannot be set for parent work packages unless it is scheduled manually | READ | || position | The rank this work package has in a sprint or product backlog | Integer | | READ | The Backlogs module needs to be active in the project and the work package's type configured to be used with backlogs. || spentTime | The time booked for this work package by users working on it | Duration | | READ | **Permission** view time entries || storyPoints | The story points the work package is estimated to take to complete | Integer | | READ / WRITE | The Backlogs module needs to be active in the project and the work package's type configured to be used with backlogs. || percentageDone | Corresponds to % complete. Amount of total completion for a work package. | Integer | 0 <= x <= 100; can be null | READ | || derivedPercentageDone | Corresponds to total % complete. Amount of total completion for a work package and its descendants. | Integer | 0 <= x <= 100; can be null | READ | || readonly | If true, the work package is in a readonly status so with the exception of the status, no other property can be altered. | Boolean | | READ | Enterprise edition only || createdAt | Time of creation | DateTime | | READ | || updatedAt | Time of the most recent change to the work package | DateTime | | READ | |Note that the properties listed here only cover the built-in properties of the OpenProject Core.Using plug-ins and custom fields a work package might contain various additional properties.A client can consult the schema information to which the work package links. The schema will contain information aboutall properties of the linking work package, including properties added by plug-ins and custom fields.Custom fields are identified by a key in the form of `customFieldN`, where `N` is an integer. Depending on their type,they can occur as properties or as linked properties. A client has to consult the schema to resolvethe human readable name of custom fields.Properties that cannot be set directly on parent work packages are inferred from their children instead:* `startDate` is the earliest start date from its children if automatic scheduling is activated.* `dueDate` is the latest finish date from its children if automatic scheduling is activated.* `derivedEstimatedTime` is the sum of estimated times from its children and the work package's own estimated time.* `derivedRemainingTime` is the sum of remaining times from its children and the work package's own remaining time* `derivedPercentageDone` is computed by the work package's derivedEstimatedTime and derivedRemainingTime.`startDate` can also not be earlier than a finish date of any predecessor.While attachments are returned as a link whose content is to be fetched separately, clients can choose toreplace the work package's attachments by providing an array of already uploaded [Attachment resources](https://www.openproject.org/docs/api/endpoints/attachments/)on [create](https://www.openproject.org/docs/api/endpoints/work-packages/#create-work-package)and [update](https://www.openproject.org/docs/api/endpoints/work-packages/#update-a-work-package). The attachments the work package has had prior to the request will be removed.