LiquidPlanner Classic Forum

Posted by LiquidPlanner Support on 2014-09-15

API Changes for Multi-Owner Tasks

Summary

As you have heard, we are planning to support multiple owners on tasks. This new feature will require a significant breaking change to the Treeitem (Task, Event, Package, Project, etc.) entity in our API, and a smaller breaking change to certain uses of the track_time endpoint and the Estimates entity. If you have an internal script or other integration with the LiquidPlanner API, it will most likely need to be migrated. The Treeitem-to-Owner relationship, which has to date been one-to-one, will become one-to-many.

New code was made available on: October 4, 2014

Your code must be updated by: January 10, 2015

Reading Assignments

The Treeitem entity, returned from a request to

/api/workspaces/:workspace_id/treeitems

or

/api/workspaces/:workspace_id/treeitems/:treeitem_id

or in the payload of Treeitem Webhooks currently has an attribute “owner_id”, which corresponds to the Person in the workspace who owns that task.

With the new feature set, this attribute will be deprecated and replaced with “assignments”, which will be an array of Assignment entities with (tentatively and non-exhaustively) the following attributes:

• id: integer, unique identifier for this assignment
• person_id: integer, identifies a person who owns the assignment
• treeitem_id: integer, identifies the Treeitem to which the assignment belongs
• is_done: boolean, true if the assignment is Done, otherwise false
• low_effort: float, the low end of the estimate range in hours
• high_effort: float, the high end of the estimate range in hours
• activity_id: integer, identifies the activity to apply to the remaining work

Note the presence of low_effort and high_effort at the Assignment level – these fields will also remain on Treeitems, representing the rolled-up efforts of the Assignments on that particular item. This allows consumers of the API to look at estimates and scheduling in aggregate at the Treeitem level if they wish to do so.

The big breaking change here is that, in order to determine ownership of a Treeitem, consumers will now need to iterate over an array of Assignments.

Updating, Creating, Removing Assignments

Updating ownership, estimates, and done state on Treeitems will change significantly as well.

Instead of sending a PUT or POST request to the relevant Treeitem to directly update attributes, consumers will now send a request to a special update_assignment endpoint. Example:

/api/workspaces/:workspace_id/treeitems/:treeitem_id/update_assignment

• To create a new assignment, send a POST request to that URL and include whatever attributes you want to set. Note that an exception will be raised if the person is already assigned.
• To update an existing assignment, you will first need the assignment_id (from a GET request on the Treeitem). Then, send a POST with the assignment_id and whichever attributes you want to change.
• Updating an assignment, especially changing the person_id, can cause changes to other assignment rows. See the detailed update_assignment spec document (attached to this post) for more details.
• To unassign a person, send a null person_id.
• To update an assignment's estimate, send the values as low_effort_remaining and high_effort_remaining.

Reordering assignments

Users can also reorder the assignments on a given Treeitem via the API. To do this, POST to the reorder_assignments endpoint for the given treeitem, and pass a hash with an "assignment_ids" key and an array of all the item's assignment ids in the order you would like them to be. For example (using the same curl setup as in the API help guide),

curl -X POST -g "https://app.liquidplanner.com/api/workspaces/####/treeitems/####/reorder_assignments" -d 
'{"assignment_ids": [####, ####, ####] }'

(replace all the #### with the appropriate item IDs)

Re-estimating via Track Time

Users can update the estimate on a Treeitem by POSTing to the track_time endpoint for the item. This will still work, but the person_id parameter will now be mandatory, since we will need to know which assignment’s estimate to update. If the person does not have an assignment, a new one will be created to hold the new estimate.

Re-estimating via POST to estimates

Users can no longer create or update item estimates by POSTing or PUTting to the Estimates resource on a Treeitem, since Estimates no longer exist at the Treeitem level. The recommended migration path is to use the track_time endpoint, which will allow users to use the same parameters.

Setting and getting daily limits

Daily limits are now properties of assignments. They will show up in the “assignments” attribute on a GET request to a treeitem, and can be set via update_assignment just like is_done, etc.

Creating a treeitem and setting ownership in one request

Note: This feature was added as a result of feedback during this current "beta" phase of the API changes. As such, it will not be available until we release the final version of the new API in January (specific date subject to change).

Since there is no longer, an owner_id attribute on Treeitems, you will need to update the way you set ownership when creating a Treeitem. Instead of setting “owner_id”, you can set the “assignments” to an array of hashes with “person_id” keys. Like this:

(...)

“name”: “Task Name”,

“assignments”: [ { “person_id”: 5} ]

(...)

Setting one or more assignments is supported.

Creating a treeitem and estimating it in one request

The ability to simultaneously create a treeitem and estimate it will no longer work. Instead, you should create the task as normal, then issue a separate request to update_assignments and set the low_effort_remaining and high_effort_remaining fields as normal.

Questions?
Please post in this forum and we’ll get back to you with an answer as quickly as possible to keep you moving forward with your updates. Thanks!