Follow

Filtering

When requesting items such as folders, packages, or tasks 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 match ing 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).

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’ and ‘created_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,3333
  • activity_id => Also has the operator “none” for nothing assigned.
  • client_id
  • created_by
  • owner_id
  • package_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”.

  • has_alert
  • has_an_activity
  • has_comments
  • has_dependencies
  • has_documents
  • has_reference
  • is_done
  • is_in_a_project
  • is_on_hold
  • is_packaged
  • shared
  • needs_update

String Filters

Operators are "=" (exact match, case sensitive), "starts_with" (case-insensitive prefix match), "does_not_start_with" (case-insensitive prefix match) and "contains" (case-insensitive substring match).

  • name
  • reference

Number Filters

Operators are “=”, “!=“, “>”, “<“, “>=”, “<=“.

Key

Meaning

expected_remaining

expecting 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, you get filter to show only one type.

Operators are “=” (exact match on the type), “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.

For the before and after operators, you can specify one of several magical values: yesterday, today, tomorrow, and infinity.

These are the operators:

Operator Meaning
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

and these are the attributes along with their applicable operators:

Attribute 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

Custom Field Filters

Pick List Custom fields

The attribute for Pick List Custom fields is custom_field:id or custom_field:name

Operators:

  • is_set
  • is_not_set
  • =
  • !=

Example:

% curl https://app.liquidplanner.com/api/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/workspaces/:id/tasks?custom_field[foo]=bar

Text Custom Fields

The attribute for Text Custom fields is custom_field:id or custom_field:name

Operators:

  • is_set
  • is_not_set
  • =
  • contains
  • starts_with
  • does_not_start_with

Example:

% curl https://app.liquidplanner.com/api/workspaces/:id/tasks?custom_field:id starts_with foo

Date Custom Fields

The attribute for Text Custom fields is custom_field:id or custom_field:name

Operator

Meaning

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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request