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:
| targetStart | custom fields (except notes) |
| targetFinish | description |
| targetFinishType | scheduleDirective |
| workType | lowEffort (enter value in seconds. ex: 3600 for 1 hour) |
| highEffort (enter value in seconds. ex: 3600 for 1 hour) | doneDate |
| folderStatus | packageStatus |
| taskStatusId | relativePriority |
| 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:
| name | targetStart |
| targetFinish | targetFinishType |
| custom fields (except notes) | description |
| scheduleDirective | workType |
| lowEffort (enter value in seconds. ex: 3600 for 1 hour) | highEffort (enter value in seconds. ex: 3600 for 1 hour) |
| doneDate | packageStatus |
| folderStatus | taskStatusId |
| relativePriority | workLimitHours |
💡 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 attribute | Field type | Description | Filter string | Note |
|---|---|---|---|---|
| id | number | Pull details about specific plan items by their ID | ?id[is]="487273" | |
| name | string | Look for plan items by their name | ?name[is]="Sample Task" | |
| itemType | enum string (packages, projects, folders, tasks, assignments) | Pull only the specified type of items | ?itemType[is]="projects" | Values are case sensitive |
| late | boolean | Pull a list of scheduled items that have Target Finish < Expected Finish | ?late[is]="true" | |
| parentId | number | Pull items from the same parent | ?parentId[is]="423260" | |
| expectedStart | dateTime | Provide the date in the UTC date time format | ?expectedStart[after]="2022-11-09T00:00:00Z" | Example: 2022-08-16T14:33:25Z |
| expectedFinish | dateTime | Provide the date in the UTC date time format | ?expectedFinish[after]="2022-11-09T00:00:00Z" | Example: 2022-08-16T14:33:25Z |
| targetStart | dateTime | Provide the date in the UTC date time format | ?targetStart[after]="2022-11-09T00:00:00Z" | Example: 2022-08-16T14:33:25Z |
| targetFinish | dateTime | Provide the date in the UTC date time format. | ?targetFinish[before]="2022-11-01T00:00:00Z" | Example: 2022-08-16T14:33:25Z |
| taskStatusId | number | Pull a list of tasks based on their custom task status | ?taskStatusId[is]=”123” | |
| packageStatus | enum string (archived, backlog, template, scheduled) | Pull Packages from a specific collection | ?packageStatus[is]="scheduled" | Values are case sensitive |
| folderStatus | enum string (active, onHold, done) | Pull Projects or Sub Folders by their scheduling state | ?folderStatus[is]="active" | Values are case sensitive |
| taskStatusGroup | enum string (scheduled, unscheduled, done) | Pull Tasks by their scheduling state | ?taskStatusGroup[is_not]="scheduled" | Values are case sensitive |
| createdAt | dateTime | Pull a list of items based on when they were created | ?createdAt[after]="2022-08-15T00:00:00Z" | |
| doneDate | dateTime | Pull a list of items based on their done date | ?doneDate[after]="2022-08-03T00:00:00Z" | |
| updatedAt | dateTime | Pull a list of items that were last updated in a given date time stamp | ?updatedAt[before]="2022-08-15T17:43:47.99Z" | |
| scheduleDirective | enum 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 |
| scheduleDirective | enum 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 |
| clippedHours | number | Pull 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” | |
| workLimitRisk | boolean | Pull 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 |
| hasFiles | boolean | Pull 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 |
Updated over 1 year ago