Update the value of an existing worked-time, estimated-time, or available-capacity record.
The method can update one of the following fields:
hours_workedhours_estimatedhours_avaibleFor estimated-time records, the associated user_id can also be updated.
The {account_id} path parameter is the numeric identifier of the organization.
It must match the account associated with the supplied authentication credentials.
The endpoint supports:
GET — parameters are passed in the query stringPOST — parameters are passed in the request bodyBecause this method modifies an existing record, POST is recommended.
POST https://api.doboard.com/42/hours_update
Content-Type: application/json
{
"hour_id": 901,
"hours_worked": 9000,
"session_id": "abc123xyz"
}
POST https://api.doboard.com/42/hours_update
Content-Type: application/json
{
"hour_id": 902,
"hours_estimated": 18000,
"user_id": 5,
"session_id": "abc123xyz"
}
POST https://api.doboard.com/42/hours_update
Content-Type: application/json
{
"hour_id": 903,
"hours_avaible": 25200,
"session_id": "abc123xyz"
}
Time values are specified in seconds. For example,
9000represents 2 hours and 30 minutes.
Required
The request must contain valid authentication credentials associated with the account specified in the endpoint URL.
The current user must have access to the project associated with the time record.
This project access requirement applies to all supported record types.
Worked time can be updated only by the user associated with the time record.
Project administrators and project managers cannot update another user's worked-time record unless they are the user associated with that record.
The worked-time record must be linked to a comment created no more than five days before the update.
Estimated time can be updated only by:
The current user must also have access to the associated project.
Available capacity can be updated only by:
The current user must also have access to the associated project.
An invalid session or token returns HTTP 401 Unauthorized.
A regular user attempting to update estimated time or available capacity receives HTTP 403 Forbidden.
Some project access failures are returned as API error 2603 with HTTP status 200.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | Conditional | User session identifier. Required when another supported authentication mechanism is not used. |
token |
string | Conditional | API authentication token. |
project_token |
string | Conditional | Public project access token, where applicable. |
hour_id |
integer | Yes | Identifier of the time record to update. |
hours_worked |
integer | Conditional | New worked-time value in seconds. |
hours_estimated |
integer | Conditional | New estimated-time value in seconds. |
hours_avaible |
integer | Conditional | New available-capacity value in seconds. |
user_id |
integer | No | New associated user. Processed only when hours_estimated is updated. |
At least one of the following parameters must be present:
hours_workedhours_estimatedhours_avaibleEach time value is converted to an integer and must be between 0 and 4294967295, inclusive.
Unlike hours_add, this method accepts 0, allowing the existing time value to be reset to zero.
The parameter name
hours_avaibleintentionally uses this spelling and must be sent exactly as shown.
If more than one time field is included, the method updates only the first field found in this order:
hours_workedhours_estimatedhours_avaibleSelection is based on whether the parameter is present, including when its value is 0 or an empty value converted to zero.
Applications should include only one time field per request.
To update worked time, provide:
hour_idhours_workedThe update is allowed only when:
hours_estimated valuehours_avaible valueThe method updates:
hours_workedupdatedOther record fields remain unchanged.
The original submitted timestamp is not changed.
To update estimated time, provide:
hour_idhours_estimatedThe update is allowed only when:
hours_worked valuehours_avaible valueThe optional user_id parameter can be used to change the user associated with the estimate:
user_id is set to null.user_id is omitted, the current association remains unchanged.The user association can only be changed in a request that also contains hours_estimated.
The method updates:
hours_estimateduser_id, when suppliedupdatedThe original submitted timestamp remains unchanged.
To update available capacity, provide:
hour_idhours_avaibleThe update is allowed only when:
hours_worked valuehours_estimated valueThe method updates:
hours_avaibleupdatedThe associated user, track, and project cannot be changed through this operation.
The original submitted timestamp remains unchanged.
The method does not clear the other time fields when updating a record.
An update is rejected when another time field already contains a non-zero value.
| Requested update | Rejected when the record contains |
|---|---|
hours_worked |
Non-zero hours_estimated or hours_avaible |
hours_estimated |
Non-zero hours_worked or hours_avaible |
hours_avaible |
Non-zero hours_worked or hours_estimated |
This prevents a regular time record from being changed directly into another type when its existing value is greater than zero.
A successful update returns the identifier of the updated record.
{
"data": {
"operation_status": "SUCCESS",
"hour_id": 901
}
}
The updated hours object is not included in the HTTP response.
The following fields can be modified:
| Field | When updated |
|---|---|
hours_worked |
When the request selects worked time. |
hours_estimated |
When the request selects estimated time. |
hours_avaible |
When the request selects available capacity. |
user_id |
When supplied together with hours_estimated. |
updated |
On every successful update. |
The following relationship fields cannot be changed through this endpoint:
comment_idtask_idtrack_idproject_idThe submitted timestamp also remains unchanged.
After a successful update, the method:
updated timestamp to the current timeUPDATE eventRecalculation is performed even if the submitted time value is equal to the current value.
Validation and business-rule errors are generally returned with HTTP status 200 and operation_status: "FAILED".
| HTTP status | Description |
|---|---|
401 Unauthorized |
The session or token is missing or invalid. |
403 Forbidden |
A user without administrator or project manager permissions attempted to update estimated time or available capacity. |
| Error number | Message | Description |
|---|---|---|
2601 |
hour_id is required |
The time record identifier was not supplied. |
2602 |
Hour Not Found |
No time record was found with the specified identifier. |
2603 |
Access is denied |
The current user does not have access to the associated project or attempted to update another user's worked time. |
2604 |
hours_estimated is not empty |
Worked time cannot be updated because the record contains a non-zero estimated-time value. |
2605 |
hours_avaible is not empty |
Worked time cannot be updated because the record contains a non-zero available-capacity value. |
2606 |
hours_worked is not empty |
Estimated time cannot be updated because the record contains a non-zero worked-time value. |
2607 |
hours_avaible is not empty |
Estimated time cannot be updated because the record contains a non-zero available-capacity value. |
2608 |
hours_worked is not empty |
Available capacity cannot be updated because the record contains a non-zero worked-time value. |
2609 |
hours_estimated is not empty |
Available capacity cannot be updated because the record contains a non-zero estimated-time value. |
2610 |
hours_worked or hours_estimated or hours_avaible is required |
No supported time field was included in the request. |
2617 |
Varies by field | The submitted time value is outside the supported range. |
2618 |
Track time within 5 days from time of commenting. |
Worked time can no longer be updated because the associated comment is more than five days old. |
{
"data": {
"operation_status": "FAILED",
"operation_message": "Access is denied"
},
"error_message": "Access is denied",
"error_no": 2603
}
0 is valid for update operations.user_id.user_id does not change the task, track, or project relationship.hour_id but does not contain the updated hours object.hours_avaible; hours_available is not processed by this method.