Filtering Requests (LP Classic)
This documentation is for LiquidPlanner Classic: app.liquidplanner.com
When requesting Treeitems, Tasks, Events, Partial Day Events, Milestones, Folders, Projects, or Packages, you can filter or restrict the set of results returned to those matching the criteria you specify.
There are two reasons to filter on the server (rather than iterating over the records client-side):
- you can reduce the size of the response by including only matching records
- logic is identical to that used by the web application
To filter, provide a parameter named ‘filter’ whose value is an array of one or more valid filter strings.
The query string should look like:
?filter[]=filter_string_1&filter[]=filter_string_2&...
By default, the filter conjunction is assumed to be AND, such that only those items matching all supplied filters will be returned. If you specify filter_conjunction=OR
, then items matching any of the supplied filters will be returned.
Each filter string has three parts:
- attribute
- operator
- value
Examples of filter strings:
owner_id = 23
is_done is false
is_on_hold is false
name starts_with BUG REPORT
You only need a space between the parts if they would otherwise “run together”, and any extra spaces are ignored. If the value has a significant leading or trailing whitespace, throw single or double-quotes around it.
The best practice is to always put a space between the parts, and always put quotes around the value part. But if you forget, we try to be forgiving.
For example, these are all valid and mean the same thing:
owner_id=23
owner_id =23
owner_id= 23
owner_id = 23
But the following are invalid:
namestarts_withBugReport
name starts_withBugReport
namestarts_with BugReport
and require whitespace:
name starts_with BugReport
Single or double-quote the value if it contains significant leading or trailing whitespace. For example:
name contains "Bug Report "
will only match items whose name contains "Bug Report " (where it is followed by two spaces). Without the quotes, the trailing spaces would be ignored (and you'd match any "Bug Report", with or without spaces after it).
If your search string contains double quotes, enclose it in single quotes and if it contains single quotes, use double quotes around it. You can also escape your quotes with a backslash, for example:
name contains "Don't"
name contains 'Don\'t'
ID Filters
Use the operators =
and !=
to match those items that do or do not have a specific ID set. The value should be an ID number or a comma separated list of ID numbers. In the case of owner_id
, created_by
, and updated_by
, you can also use the magical value me
. The values everyone
and unassigned
are usable for owner_id
.
id
- Can use comma-separated multiple Item IDs like this: filter[]=id=1111,2222,3333activity_id
- Also has the operator “none” for nothing assigned.client_id
created_by
owner_id
package_id
- Matches tasks that are packaged in a package with this id.parent_id
project_id
updated_by
Boolean Filters
The operator for boolean filters is always is
, and the value is either true
or false
.
all_dependencies_satisfied
has_alert
has_an_activity
has_broken_dependencies
has_comments
has_dependencies
has_dependents
has_documents
has_reference
is_done
is_in_a_project
is_on_hold
is_packaged
shared
needs_update
String Filters
Available Operators
Operator | Description |
---|---|
= | exact match, case sensitive |
starts_with | case-insensitive prefix match |
does_not_start_with | case-insensitive prefix match |
contains | case-insensitive substring match |
Attributes
name
reference
Number Filters
Operators are =
, !=
, >
, <
, >=
, <=
.
Attribute | Meaning |
---|---|
expected_remaining | expected remaining time |
uncertainty | difference between the high and low remaining time estimates |
Item Type Filters
If you make a request that returns multiple types of items, such as getting treeitems, tasks, or events, you can filter to show only one type.
Operators are =
(exact match on the type), and is
(also includes subclass types, ex: includes partial day events when filtering on event).
item_type
- Options are: "Package", "Project", "Folder", "Task", "Event", "Milestone"
Date Filters
The are several operators available for date attributes; not all are available for all attributes.
Operators
Operator | Description |
---|---|
within | attr is within N days of now, in the past or future |
not_within | attr is not within |
in_next | attr falls before N days after now |
never | attr is not set; value is ignored |
before | attr is before a specific date |
after | attr is after a specific date |
Attributes
Attribute | Available Operators |
---|---|
last_estimated | all |
date_done | all |
expected_finish | all |
earliest_start | all |
last_updated | before, after, within, not_within |
created | before, after, within, not_within |
promise_by | before, after, in_next, never |
delay_until | before, after, in_next, never |
The
promise_by
date attribute corresponds to the Deadline date field in the application UI.
% curl https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems?filter[]=promise_by after 2018-04-07
The date filters are an exception from ISO 8601 date format; they use yyyy-mm-dd format for the dates and default to the midnight of the API user's timezone.
Pick List Custom Fields
The attribute for Pick List Custom fields is custom_field:id
or custom_field:name
Available Operators:
is_set
is_not_set
=
!=
Example:
% curl https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems?filter[]=custom_field:foo=bar
Pick List Custom fields can also be filtered with URL parameters custom_field[Field Name]=Value
, for example:
% curl https://app.liquidplanner.com/api/v1/workspaces/:id/tasks?custom_field[foo]=bar
Text Custom Fields
The attribute for Text Custom fields is custom_field:id
or custom_field:name
Available Operators:
is_set
is_not_set
=
contains
starts_with
does_not_start_with
Example:
% curl https://app.liquidplanner.com/api/v1/workspaces/:id/tasks?filter[]=custom_field:foo starts_with bar
Date Custom Fields
The attribute for Text Custom fields is custom_field:id
or custom_field:name
Example:
% curl https://app.liquidplanner.com/api/workspaces/:id/tasks?filter[]=custom_field:‘contract date’ within 7
Operator | Description |
---|---|
is_set | attr has a value |
is_not_set | attr has no value |
within | attr is within N days of now, in the past or future |
not_within | attr is not within N days of now, in the past of future |
in_next | attr falls before N days after now |
before | attr is before a specific date |
after | attr is after a specific date |
Tag Filters
The operator for tag filtering is include
. You may provide a single tag, as in:
filter[]=tags include Alpha
or multiple tags, as in:
filter[]=tags include Bravo, Charlie, Delta
If you provide multiple tags, the set of items returned will consist of all items tagged with any of the provided tags. In the previous filter, all items returned will be tagged with at least one of "Bravo", "Charlie", or "Delta".
To filter items such that every item is tagged with all specified tags, you must specify the tag filter multiple times- as in:
filter[]=tags include Echo&filter[]=tags include Foxtrot&filter[]=tags include Golf
With this filter, all items returned will be tagged with all three tags.
Updated about 2 years ago