Custom Ticket Query Filters

A query string,query, can be added to define a query based filter for GetTicketList endpoint (https://www.3drepo.io/docs/#/Tickets/GetTicketList).

i.e.:

/teamspaces/{teamspace}/projects/{project}/{type}/{model}/tickets?query='query string value'

The query string should be wrapped around single quotes and consists of a list of query params separated by &&. Each query param consists of at least 2 parts:

1. Property
2. The operator
3. (If required by the operator) the values

Thses parts should be delimited by ::

URL Encoding

The query string should be URL encoded as per standard practice. For readability, this guide will display the query string decoded.

e.g. the following query:

tickets?query='Status::is::Open,Closed&&Custom Clash template:txtProp::ss::one'

Should be sent as follows:

tickets?query=%27Status%3A%3Ais%3A%3AOpen%2CClosed%26%26Custom%20Clash%20template%3AtxtProp%3A%3Ass%3A%3Aone%27

Properties

The property name specifies which property the filter is refering to. They can be any one of the following:

• A member of the base property: A property that can be found within the properties field within a ticket (e.g. Description, status)
• A member of a module property: A property that resides within a module. The module and its property should be delimited by a : (e.g. safetibase::Location)
• Special field: Additional fields that are not part of the standard ticket properties are denoted by a prefix $. The following fields are supported:
  1. $title - The title of the ticket
  2. $ticketCode - The ticket code (e.g. CSH:1)
  3. $template - The template the ticket is based on, represented by its ticket code.

Unsupported property types

The following property types cannot be filtered:

• view
• image
• imageList
• position

Operators

A list of operators can be included in the query string. The operators are displayed below:

Operator	Description	Supported Types	Symbol	allow multiple values	Example
Exists	The property has a value	all	ex	N/A	assignees::ex
Not Exists	The property does not have a value	all	nex	N/A	assignees::nex
Is	The property value matches the provided value(s)	text, longText, oneOf, manyOf	is	yes	assignees::is::janeDoe
Not Is	The property value does not match the provided value(s)	text, longText, oneOf, manyOf	nis	yes	assignees::nis::janeDoe
Equals	The property value equals the provided value(s)	number, date, boolean	eq	yes	width::eq::500
Not Equals	The property value does not equal the provided value(s)	number, date, boolean	neq	yes	width::neq::500
Contains	The property value contains the provided value(s)	text, longText, oneOf, manyOf	ss	yes	description::ss::safety
Not Contains	The property value does not contain the provided value(s)	text, longText, oneOf, manyOf	nss	yes	description::nss::safety
Range	The property value is within the range	number, date	rng	yes	cost::rng:[0,100]
Not in Range	The property value is not within the range	number, date	nrng	yes	cost::rng:[0,100]
Greater or equal to	The property value is greater or equal to the provided number	number, date	gte	no	cost::gte:10
Lesser or equal to	The property value is less than or equal to the provided number	number, date	lte	no	cost::lte:10

Property Value

The property value defies what is the expected value for each filter.

As shown in the table above some operators allow multiple values. Multiple values they should be delimited by a comma without any spaces before or after. In the event of a value containing a comma, it should be wrapped around by double quotes, for e.g.

description::ss::"one, two, three",safety,rails

Denotes that the description should contain one, two, tree orsafety or rails

Query examples

The following query will select tickets that satisfies ALL of the following conditions:

• Status is either Open or Closed
• txtProp within Custom Clash template contains the term one

?query='Status::is::Open,Closed&&Custom Clash template:txtProp::ss::one'

The following query will select tickets that has a height range between 1-10, and 20-30.

?query='height::rng::[1,10],[20,30]

The following query will select tickets that satisfies ALL of the following conditions:

• The title of the ticket contains the term A or 1
• txtProp is not empty

?query='$title::ss::A,1&&txtProp::ex