Assignments (LP Classic)

Retrieving Assignments

Assignments can be retrieved by retrieving a treeitem on which they exist.

Example: List assignments on a treeitem

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems/:id
{
  ...
  "name": "Task Name",
  "assignments": [
    {
      "person_id": ###,
      "team_id": null,
      "low_effort_remaining": 2,
      "high_effort_remaining": 6,
      "treeitem_id": ###,
      "space_id": ###,
      "activity_id": ###,
      "is_done": false,
      "daily_limit": null,
      "position": 1,
      "hours_logged": 3,
      "expected_finish": "2015-01-19T20:00:00+00:00",
      "expected_start": "2015-01-19T16:00:00+00:00",
      "can_destroy": false,
      "type": "Assignment",
      "id": ###
    },
    {
      "person_id": ###,
      "team_id": null,
      "low_effort_remaining": 1,
      "high_effort_remaining": 2,
      "treeitem_id": ###,
      "space_id": ###,
      "activity_id": ###,
      "is_done": false,
      "daily_limit": null,
      "position": 2,
      "hours_logged": 0,
      "expected_finish": "2015-01-19T21:30:00+00:00",
      "expected_start": "2015-01-19T20:00:00+00:00",
      "can_destroy": true,
      "type": "Assignment",
      "id": ###
    }
  ],
  ...
  "type": "Task",
  "id": ###
}

Updating, Creating, Removing Assignments

Instead of sending a PUT or POST request to the relevant Treeitem to directly update assignment attributes, use the special /update_assignment endpoint (e.g. /api/v1/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.
You can create, update or delete only one assignment at a time via the API, except on Events, PartialDayEvents, and Milestones where you can add multiple person_ids and team_ids like this: {"person_ids": [12345,67890]} .

Reassignment example:

% curl -X POST -g https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems/:id/update_assignment -d '{ "assignment_id": ###, "person_id": ### }'

Update assignment's estimate example:

% curl -X POST -g https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems/:id/update_assignment -d '{ "assignment_id": ###, "low_effort_remaining": ###, "high_effort_remaining": ### }'

To update an estimate, use the keys “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:

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

Removing Assignments

If you want to remove an assignment you can DELETE as follows.

% curl -X DELETE -g https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems/:id/assignments/:id
{
  ...
  "name": "Unestimated",
  "assignments": [
    {
      "person_id": ####,
      "team_id": null,
      "low_effort_remaining": 4,
      "high_effort_remaining": 31,
      …
      "type": "Assignment",
      "id": ####,
      "estimates": [
        {
          …
          "owner_id": ####,
          "low": 4,
          "high": 31,
          "…
          "type": "Estimate",
          "id": ####
        }
      ]
    },
    {
      "person_id": ####,
      "team_id": null,
      "low_effort_remaining": 0,
      "high_effort_remaining": 0,
…
      "type": "Assignment",
      "id": ####,
      "estimates": []
    }
  ],
  ...
  "type": "Task",
  "id": ####
}

🚧
Before trying to delete an assignment, take note of the “can_destroy” property of the assignment. If can_destroy is false, you can’t remove the assignment. Assignments with logged time can’t be removed. You must also have at least one assignment on an item.

Estimates on Assignments

Example: retrieving the estimate history for an assignment

You can retrieve the estimate history for a given assignment by including it as follows:

% curl https://app.liquidplanner.com/api/workspaces/:
id/treeitems/:id?include=estimates
{
...
"name": "Unestimated",
"assignments": [
{
"person_id": ####,
"team_id": null,
"low_effort_remaining": 4,
"high_effort_remaining": 31,
...
"type": "Assignm
ent",
"id": ####,
"estimates": [
{
...
"owner_id": ####,
"low": 4,
"high": 31,
"...
"type": "Estimate",
"id": ####
}
]
},
{
"person_id": ####,
"team_id": null,
"low_effort_remaining": 0,
"high_effort_remaining": 0,
...
"type": "Assignment",
"id": ####,
"estimates": []
}
],
...
"type": "Task",
"id": ####
}

Setting Daily Limits on Projects

To set or update a Daily Limit on a Project, POST the assignment id and the daily limit to /update_assignment endpoint.

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/projects/:id/update_assignment 
{"assignment_id": "448719","daily_limit":"3"}

To remove the daily_limit, set it to null.

An assignment on the project level is the member’s assignment to the Project Team. It can be found on the api/workspaces/:id/projects/:id/assignments endpoint.