Items and Containers

We use the term item or treeitem to refer to the things that you can arrange in your 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.

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 that if you both:

a. specify a filter and b. do not specify that you want context

then 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).

Including Ancestors and Children

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

depth

0 (default, only the item itself), -1 (for all depths), or a positive number N (for depths no greater than N)

leaves

false (the default, including only structure / containers) or true (including everything)

% curl https://app.liquidplanner.com/api/workspaces/:workspace_id/treeitems/:container_id?depth=-1 … the container, and the container structure within that container …

% curl https://app.liquidplanner.com/api/workspaces/:workspace_id/treeitems/:container_id?depth=-1&leaves=true … everything above, plus tasks, events, and milestones …

item_context

false (the default, only the specified item), or true (include the ancestors of the item, up to the root)

filter_context

false (the default, only the specified filter matches), or true (include the ancestors of the filter matches, up to the root)

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

A Few Simple Rules for Arranging Items in the Tree

Actually, it’s arguable whether they are simple or few… but here there are.

• 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 it its parent is not a package (i.e. its parent must be a project or a folder)

Ordering of Items in Containers

Every item has a ‘global_priority’ attribute.

Packaged items additionally have a ‘global_package_priority’ attribute. For scheduling purposes, this overrides the item’s global_priority.

The values of these attributes are arrays of numbers specifying relative positions in the tree. The values of these attributes are comparable or sortable, but otherwise arbitrary; e.g. you cannot infer the quantity of a project’s items from the global_priority of its lowest priority item.

Two items with the same parent will have identical values for global_priority in all but the last position in the array, and the value in this last position indicates their relative order within the container itself (lesser value first, greater value second). The same principles apply to two items packaged in the same package and the values of their global_package_priority attributes.

Moving Items

Every item (except the root) has a parent container.

To move an item into a container without specifying its position in the container, simply update the item’s parent_id. This will move the item into the specified container in last position.

To specify an item’s position within a container, POST to one of the following:

• move_before
• move_after

with a parameter:

other_id

the ID of the other item, before or after which to move this item

for example:

POST /api/workspaces/:workspace_id/tasks/:id/move_before?other_id=:id
POST /api/workspaces/:workspace_id/tasks/:id/move_after?other_id=:id

or, where applicable:

packaged_other_id

the ID of the other item (in its packaged location!), before or after which to move this item

for example:

POST /api/workspaces/:workspace_id/tasks/:id/move_before?packaged_other_id=:id
POST /api/workspaces/:workspace_id/tasks/:id/move_after?packaged_other_id=:id

Packaging Items

Leaf items may be both moved and packaged, while container items may only be moved (but not packaged).

When you package an item, its package_id is set to that of the containing package, but its parent_id remains the same. Its effective priority for scheduling becomes that of its packaged location (whether this is higher or lower than the priority of its “real” location).

You can only package an item if its parent is not a package (i.e. when its parent is a folder or a project).

To specify an item’s packaged position within a container, POST to one of the following:

• package_before
• package_after

other_id

the ID of the other item, before or after which to package this item

POST /api/workspaces/:workspace_id/tasks/:id/package_before?other_id=:id POST /api/workspaces/:workspace_id/tasks/:id/package_after?other_id=:id

Note that you never use the packagedother_id_ here, because it is unambiguous which other you mean (either its package_id is set, or its parent_id is that of a package – but never both).