Items

This documentation is for LiquidPlanner New: next.liquidplanner.com

Use the Items endpoint to interact with the different plan items in your workspace.

The data returned is a list of items and does not include the descendants (if any). For example, a list of tasks does not include the assignments. Those are pulled separately by walking the tree.

To learn more about how to walk the tree and return the complete tree listing, please see API Tree Structure

https://next.liquidplanner.com/api/workspaces/<workspace id>/items/v1

Supported Methods

POST

Create new plan items in the workspace. Use the itemType field to specify the type of item that needs to be added.

Add a new item in your workspace by sending a POST request including the following fields in the request body:
“workspaceId” - ID of the workspace in which the item must be created
“name” - name for the item being created
“itemType”- specify the type of item being created. E.g., packages or projects or folders or tasks or assignments
“parentId” - specify the ID of the parent item in which the new item will be created. The newly created item is added to the bottom of the list in the specified parent item.

Specify the relative position when creating or updating plan items (Package, Project, Sub-Folder, Tasks) in the workspace. Items can be added at the top or bottom of the container or before/after a specific item in a container. The item is added at the bottom by default.

The example below adds a new task at the top of the task list in a project.

curl --location --request POST 'https://next.liquidplanner.com/api/workspaces/<workspace id>/items/v1' \
--header 'Authorization: Bearer <API Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Sample Task",
            "itemType": "tasks",
            "parentId": <project id>,
            “workspaceId": <workspace id>,
            “relativePriority”: {
            “type”: ”top”
              }

              }'

Other optional parameters that can be included in a POST request where applicable include:

targetStartcustom fields (except notes)
targetFinishdescription
targetFinishTypescheduleDirective
workTypelowEffort (enter value in seconds. ex: 3600 for 1 hour)
highEffort (enter value in seconds. ex: 3600 for 1 hour)doneDate
folderStatuspackageStatus
taskStatusIdrelativePriority
workLimitHours

UPDATE

Send a PUT request to make certain types of updates to an existing plan item in the workspace.

The example below updates Task B with changes to its Task Status, Custom Field value, removes the work limit and moves it above Task A.

curl --location --request PUT 'https://next.liquidplanner.com/api/workspaces/<workspace id>/items/v1/<id of Task B> \
--header 'Authorization: Bearer <API Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
                "taskStatusId":"2467",
                “workLimitHours”:”null”,
                "relativePriority": {
                  "id": <id of Task A>,
                  "type": "before"
                 },  

                "customFieldValues": [
        {
          "name": "Color",
          "value": "Green"
        }]
        }'

Optional parameters that can be included in a PUT request where applicable:

nametargetStart
targetFinishtargetFinishType
custom fields (except notes)description
scheduleDirectiveworkType
lowEffort (enter value in seconds. ex: 3600 for 1 hour)highEffort (enter value in seconds. ex: 3600 for 1 hour)
doneDatepackageStatus
folderStatustaskStatusId
relativePriorityworkLimitHours

💡 To remove Custom field values on a plan item, see the examples here.

💡 When providing estimates on an assignment, send the value in seconds. For example, to add a low estimate of 1 hour, send 3600 like this -> "lowEffort":"3600"

GET

Pull a list of all the plan items from your workspace in a JSON format. Use filters to restrict the set of results returned to those matching the specified criteria.

If the response data includes a value for the doneDate field, this indicates that the item has been marked done. Similarly if the response data includes a value for the expectedStart field, this indicates that the item is active.

Some fields that are included in the response for the items endpoint are: Target Start and Finish dates set on the item and inherited from its container, custom field values set on the item and inherited from its parent container, dependencies, roll up of hours logged and hours remaining, clipped hours, work limit hours, work limit risk and a lot more.

When a custom field value is inherited from a parent container, the API response will also include the id of the parent container along with the settable field which indicates if the custom field value can be overwritten on the item.

When there’s a dependency on the item, the API response will include the ID of the dependency, dependency type (i.e., predecessor or successor), id of the dependency item, wait (days), and the dependency status.

When the fileCount returned on an item is greater than 0, use the files endpoint to pull a list of files and their IDs from the plan item and then download a single file at a time by passing the file id as explained here.

Sample Response

{
    "recordLimit": 500,
    "recordCount": 1,
    "data": [
        {
            "id": 425000,
            "name": "Active Task",
            "color": null,
            "itemType": "tasks",
            "scheduleDirective": "asapInProject",
            "workType": "independently",
            "lowEffort": null,
            "highEffort": null,
            "workLimitHours": 40.0,
            "workLimitRisk": true,
            "doneDate": null,
            "packageStatus": null,
            "folderStatus": null,
            "targetStart": null,
            "targetFinish": "2022-08-10T00:00:00Z",
            "targetFinishType": "stopScheduling",
            "description": "sample description text",
            "rateSheetId": null,
            "costCodeId": null,
            "userId": null,
            "taskStatusId": 496,
            "parentId": 422658,
            "workspaceId": 21,
            "customFieldValues": [
                {
                    "name": "Special Task Type",
                    "value": "Functional Documentation"
                },
                {
                    "name": "Color",
                    "inheritedFromId": 440981,
                    "settable": true,
                    "value": "Orange"
                }
            ],
            "fileCount": 5,
            "loggedHoursRollup": 3.0,
            "lowRemainingHoursRollup": 7.0,
            "highRemainingHoursRollup": 53.0,
            "expectedStart": "2022-08-10T00:00:00Z",
            "expectedFinish": "2022-08-10T00:00:00Z",
            "latestFinish": "2022-08-10T00:00:00Z",
            "inheritedTargetStartDate": null,
            "inheritedTargetFinishDate": "2022-10-27T00:00:00Z",
            "late": true,
            "clippedHours": 30.0,
            "createdAt": "2022-08-03T22:20:02.732007Z",
            "updatedAt": "2022-08-24T19:30:57.659Z",
            "createdById": 10702,
            "updatedById": 10702,
            "lastStatusChange": "2022-08-24T19:30:57.625788Z",
            "dependencies": [
                {
                    "id": 57987,
                    "dependencyType": "predecessor",
                    "dependencyItemId": 422662,
                    "waitDays": 2,
                    "itemId": 416758,
                    "dependencyStatus": "active",
                    "createdAt": "2022-10-10T22:34:49.848419Z",
                    "updatedAt": "2022-10-10T22:34:54.206894Z",
                    "createdById": 185,
                    "updatedById": null
                }
            ]

        }
    ]
}

Filter Options

Apply the filter string to the endpoint URL. Values are case sensitive for enum strings as noted below.

Filter attributeField typeDescriptionFilter stringNote
idnumberPull details about specific plan items by their ID?id[is]="487273"
namestringLook for plan items by their name?name[is]="Sample Task"
itemTypeenum string (packages, projects, folders, tasks, assignments)Pull only the specified type of items?itemType[is]="projects"Values are case sensitive
latebooleanPull a list of scheduled items that have Target Finish < Expected Finish?late[is]="true"
parentIdnumberPull items from the same parent?parentId[is]="423260"
expectedStartdateTimeProvide the date in the UTC date time format?expectedStart[after]="2022-11-09T00:00:00Z"Example: 2022-08-16T14:33:25Z
expectedFinishdateTimeProvide the date in the UTC date time format?expectedFinish[after]="2022-11-09T00:00:00Z"Example: 2022-08-16T14:33:25Z
targetStartdateTimeProvide the date in the UTC date time format?targetStart[after]="2022-11-09T00:00:00Z"Example: 2022-08-16T14:33:25Z
targetFinishdateTimeProvide the date in the UTC date time format.?targetFinish[before]="2022-11-01T00:00:00Z"Example: 2022-08-16T14:33:25Z
taskStatusIdnumberPull a list of tasks based on their custom task status?taskStatusId[is]=”123”
packageStatusenum string (archived, backlog, template, scheduled)Pull Packages from a specific collection?packageStatus[is]="scheduled"Values are case sensitive
folderStatusenum string (active, onHold, done)Pull Projects or Sub Folders by their scheduling state?folderStatus[is]="active"Values are case sensitive
taskStatusGroupenum string (scheduled, unscheduled, done)Pull Tasks by their scheduling state?taskStatusGroup[is_not]="scheduled"Values are case sensitive
createdAtdateTimePull a list of items based on when they were created?createdAt[after]="2022-08-15T00:00:00Z"
doneDatedateTimePull a list of items based on their done date?doneDate[after]="2022-08-03T00:00:00Z"
updatedAtdateTimePull a list of items that were last updated in a given date time stamp?updatedAt[before]="2022-08-15T17:43:47.99Z"
scheduleDirectiveenum string

For itemType Tasks: normal, asapInProject, asapInPackage, asapInWorkspace
Pull a list of tasks that have an ASAP priority override?scheduleDirective[is]="asapInWorkspace"Values are case sensitive
scheduleDirectiveenum string

For itemType Assignments: trackingOnly
Pull a list of assignments that are tracking only?scheduleDirective[is]="trackingOnly"Values are case sensitive
customFieldValues.All custom data field types (except Notes)Pull a list of items that have custom field value matching the filter criteria?customFieldValues.Color[is]=”Blue”Values are case sesitive
clippedHoursnumberPull a list of items that have clipped hours (hover text: hours that are removed from the schedule because they can’t complete by the Target Finish)?clippedHours[gt]=”0”
workLimitRiskbooleanPull a list of items that have a Work Limit risk (i.e., Total Work (E) is greater than the Work Limit set on the item)?workLimitRisk[is]="true"Note: Total Work (E) = loggedHoursRollup+ (lowRemainingHoursRollup + highRemainingHoursRollup)/2
hasFilesbooleanPull a list of items that have files uploaded on them?hasFiles[is]=”true”The result will include only those items that have a fileCount > 0