Add more details in api docs regarding progress values

opf · May 28, 2024 · f130245 · f130245
1 parent 49ca55e
commit f130245
Showing 1 changed file with 8 additions and 5 deletions.
diff --git a/docs/api/apiv3/tags/work_packages.yml b/docs/api/apiv3/tags/work_packages.yml
@@ -59,11 +59,14 @@ description: |-
   | 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           | Time a work package likely needs to be completed excluding its descendants                                                                                                    | Duration    |                                                                                                                                                                                              | READ / WRITE         |                                  |
-  | derivedEstimatedTime    | Time a work package likely needs to be completed including its descendants                                                                                                    | Duration    |                                                                                                                                                                                              | READ                 |                                  |
+  | 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                 |                                  |
   | spentTime               | The time booked for this work package by users working on it                                                                                                                  | Duration    |                                                                                                                                                                                              | READ                 | **Permission** view time entries |
-  | percentageDone          | Amount of total completion for a work package                                                                                                                                 | Integer     | 0 <= x <= 100                                                                                                                                                                                | READ                 |                                  |
+  | 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                 |                                  |
@@ -84,15 +87,15 @@ description: |-
   * `dueDate` is the latest finish date from its children if manual 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 to
-  replace the work package's attachments by providing an array of already uploaded [Attachment resources](https://www.openproject.org/docs/api/endpoints/attachments/) 
+  replace 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.
 name: Work Packages