Treeitem Data Model (LP Classic)

Items and Containers

We use the term item or treeitem to refer to the things that you can arrange in your LiquidPlanner Classic workspace tree – treeitems include Tasks, Events, Milestones, Packages, Projects, and Folders.

We use the term container to refer to items that may contain other items – containers include Roots, Packages, Folders, and Projects.

We use the term leaf to refer to items that cannot contain other items – leaves includes Tasks, Events, and Milestones.

Scoping / Nesting of Resources

Resources (except for your account and workspaces themselves) are scoped by or nested within a workspace. This scoping is represented in the request path, so to list the tasks in a given workspace, do:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/tasks

🚧

Warning about getting all tasks in the workspace:

While it is OK to do in a small sandbox, we do not recommend listing all tasks in your production workspace. This request may take a long time to execute and even time out. Instead, try filtering, for example by "created" dates.

To show a single task, do:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/tasks/:task_id

This nesting pattern may be repeated, as with the comments for a task:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/tasks/:task_id/comments

Example: Retrieve all Projects in a Workspace

You can retrieve items of any type following the tree organization of a workspace. For example, to retrieve just the project items:

% curl https://app.liquidplanner.com/api/workspaces/:id/projects

📘

Note

When you retrieve all tasks using the api/v1/workspaces/:id/tasks resource, you will also get back all events, partial day events and milestones in addition to the tasks. If you only want tasks returned, use the Item Type filter.
Similarly, when you retrieve events from api/v1/workspaces/:id/events, you will get partial day events and milestones in addition to events, so to only get the full day events, filter for event item type.

Tree Representation in JSON

The tree hierarchy is represented in JSON using a children attribute, whose value is an array of child hashes. Each child hash may (if it is a container) also have a ‘children’ attribute.

{ 
  "children": [ 
    { ... },
    { 
      "children": [
        { ... },
        { ... },
        { ... }
      ]
    },
    { ... }
  ]
}

This is the default behavior for listing the tree via the treeitems resources. If you want only a flat array (with the parent / child relationship indicated solely by corresponding IDs and not by the nested hash structure of the data), specify flat=true as a query parameter.

📘

Note

If you:
a) Specify a filter AND
b) Do not specify that you want context

We automatically force flat=true because we cannot return a tree if your filter matches a child but not its parent, and you don’t want context)

Rules for Arranging Items in the Tree

• Every item has a parent (except the root).
• A package’s parent must be a package or the root.
• A project’s parent must be a package or the root
• A folder’s parent must be a project or a folder.
• A leaf’s parent must be a package, a project, or a folder.
• Only leaf items may be packaged (have their package_id and package_priority set)
• A leaf may be packaged only if its parent is not a package (i.e. its parent must be a project or a folder)

Treeitems Resource

There is a special resource for treeitems; you can use it to “blindly” show, update, or nest into any sort of item without knowing its type in advance (but not to create new items – use the standard type-specific resources).

GET /api/v1/workspaces/:workspace_id/treeitems/:item_id
PUT /api/v1/workspaces/:workspace_id/treeitems/:item_id
GET /api/v1/workspaces/:workspace_id/treeitems/:item_id/comments
etc.

Example: List the contents of the workspace

The contents of a workspace are organized in a tree. Every workspace has a root. The root may be empty (in which case you have an empty workspace), or it may contain projects and packages. In turn, these projects and packages may contain other items.

To fetch only the root, request treeitems with a depth of 0:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems?depth=0
{
   "work": 6,
   "alerts": [],
   "created_at": "2014-06-13T17:31:28+00:00",
   "created_by": 433779,
   "description": "This is the root for the workspace.",
   "earliest_finish": "2014-07-16T16:35:00+00:00",
   "earliest_start": "2014-07-03T19:41:00+00:00",
   "expected_finish": "2014-07-18T19:41:00+00:00",
   "expected_start": "2014-07-03T19:41:00+00:00",
   "p98_finish": "2014-07-24T19:46:00+00:00",
   "high_effort_remaining": 128.40604,
   "is_done": false,
   "latest_finish": "2014-07-23T17:08:00+00:00",
   "low_effort_remaining": 88.59397,
   "name": "Liquid Planner",
   "updated_at": "2014-06-13T17:31:28+00:00",
   "updated_by": 433779,
   "type": "Root",
   "id": 15539434
}
Status: 200

If you want the entire tree, you do:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems?depth=-1&leaves=true
{ …
   "type": "Root",
   "id": 15539434,
   "children": [
      {
         "work": 0,
         "alerts": [],
         "created_at": "2014-06-13T17:31:28+00:00",
         "created_by": 433779,
         "done_on": null,
         "started_on": null,
         "delay_until": null,
         "description": "",
         "earliest_finish": null,
         "earliest_start": null,
         "expected_finish": null,
         "expected_start": null,
         "p98_finish": null,
         "global_priority": [
            1,
            1
         ],
         "has_note": false,
         "high_effort_remaining": 0,
         "is_done": false,
         "is_on_hold": false,
         "latest_finish": null,
         "low_effort_remaining": 0,
         "manual_alert": "",
         "max_effort": null,
         "name": "INBOX",
         "assignments": [
         { 
             "person_id":43779,
             "team_id":null,
             "low_effort_remaining":0.0,
             "high_effort_remaining":0.0,
             "treeitem_id":15539434,
             "space_id":1,
             "activity_id":null,
             "is_done":false,
             "daily_limit":null,
             "position":0,
             "hours_logged":0.0,
             "expected_finish":null,
             "expected_start":null,
             "can_destroy":false,
             "type":"Assignment",
             "id":59366 
           } 
         ],
         "parent_id": 15539434,
         "parent_ids": [
            15539434
         ],
         "parent_crumbs": [],
         "promise_by": null,
         "external_reference": null,
         "updated_at": "2014-06-13T17:31:28+00:00",
         "updated_by": 433779,
         "type": "Inbox",
         "id": 15539435,
         "children": [
            { …
               "type": "Task",
               "id": 15899326
            }
         ]
      },
      { …
         "name": "Events",
         "type": "Package",
         "id": 15539436,
         "children": [
            { …
               "type": "Task",
               "id": 15882502
            }
         ]
      },
      { …
         "name": "Sample Project Three",
         "type": "Project",
         "id": 15539447,
         "children": [
            { …
               "name": "Task 7",
               "type": "Task",
               "id": 15539448
            }
         ]
      }
   ]
}
Status: 200

Including Ancestors and Children

When fetching a treeitem by ID from the treeitems resource, you may specify these optional parameters:

📘

Use false for the context parameters where you are “zoomed to” or have “opened” the item and only need information about the item itself, and true for rendering the placement of the item in the tree.

Including Associated Records

Specify an include parameter with a comma separated list of things to include. Valid things to include are:

• activities
• comments
• dependencies
• dependents
• documents
• estimates
• links
• note
• snapshots
• tags
• timer
• checklist_items

For example, getting a specific task with its comment, documents, links, and note (roughly the information needed for the Projects tab):

% curl https://app.liquidplanner.com/api/workspaces/:id/tasks/:id?include=comments,documents,links,note