Query Parameters
The ServiceMobility Query APIs are designed for querying the system data, and therefore may potentially return a large number of results.
As a result, the APIs all support a common set of parameters which can be used to:
- Filter the results on the basis of their field values;
- Limit the fields returned for each object, to ensure only the fields of interest are returned;
- Limit the total number of results returned by the query and/or skip a defined number of results; and
- Define the sort order that should be used for the results.
| Parameter | Description |
|---|
filters | The filters parameter allows the query to return only those results where the specified field or fields match the given criteria for those field(s). | Note |
|---|
Not all fields of an object support filtering via the filters parameter. See details below for which fields support the use of the filters parameter for this Query API. |
Filters expression consists of one or more comparison operations , which are joined by logical operators - Logical AND (; or and) and Logical OR (, or or). Each comparison operation
comparison = A selector, a comparison-op, | Code Block |
|---|
selector = Identified the field name of the object to filter against
comparison-op = Currently supported comparison operators are listed in "Operators" table below
arguments = Identifies the value(s) to be matched against the field. Multiple values are represented in parenthesis separated by comma |
and one or more arguments. selector - Identifies the field name of the object to filter against;
comparison-op - Currently supported comparison operators are listed in "Operators" table below;
arguments - Identifies the value(s) to be matched against the field. Multiple values are represented in parenthesis separated by comma.
Example: The filters parameter is used to quickly reduce the result set based on the field values provided. Although the filters is case-insensitive it does preform an exact match. filters=ServiceTeamID==EastCoast
This will return all objects where the WorkCenter field has a value of EastCoast Supported operators are shown below in a table. | Operators | Description |
|---|
| "==" | Equals | | "=ne=" or "!=" | Not equals | | "=gt=“ or “>" |
| Greater than | | "=ge=" or “>=" |
| Greater than or equals to | | "=lt=“ or “<" |
| Less than or equals to | | “=in=" | In | | “=out=" | Not in | | ";” or “and" | Logical AND | | ",” or “or" | Logical OR |
|
| fields | Identifies the comma separated list of fields to include in the object representation in response. The fields parameter syntax is: | Code Block |
|---|
fields=field-1,field-2 |
- field-1 = The field name in the object
|
| limit | Identifies the maximum number of objects to be returned. |
qq | The q parameter allows the query to return only those results where the specified field or fields match the search term for those field(s). | Note |
|---|
Not all fields of an object support filtering via the q parameter. See details below for which fields support the use of the q parameter for this Query API. |
The q parameter syntax is: | Code Block |
|---|
q=<search term>::in:field-1,field-2 |
The q parameter supports partial term matches across multiple fields. For example, a search would match all of the following field values: John, John's, Johansson, Johansen. The q parameter currently supports one search term, although it can be combined with the filters parameter. |
fields | The fields parameter allows the query to return only those fields in the object representation in response which are deemed relevant. The fields parameter syntax is: | Code Block |
|---|
fields=field-1,field-2 |
field-1 - A field name in the object to be included in the result;field-2 - Another field name in the object to be included in the result.- etc.
|
limit | The limit parameter defines the maximum number of objects to be returned for the query. Often used with the start parameter. |
| sort | Identifies the field name start | The start parameter defines the number of objects to be skipped. This is used for pagination and allows skipping previously returned objects. Often used with the limit parameter. |
sort | The sort parameter defines the field or fields that should be used for sorting the query results. | Note |
|---|
Not all fields of an object support being used as a sorting key via the sort parameter. See details below for which fields support the use of the sort parameter for this Query API. |
The sort syntax is: | Code Block |
|---|
sort=[-]field-1,[-]field-2 |
- - The field name to sort against;
- [ - ]
- - Optional value that identifies the field is to be sorted in descending order.
| start | Identifies the number of objects to be skipped. This is used for pagination and allows skipping previously returned objects
| Info |
|---|
In the fields listed below, defining the fields supported by the filters, q and fields parameters, two formats are potentially listed: field-1 - Represents a supported "top-level" field of the object (with name "field-1") relevant to this Query API; andfield-1/subfield-1 - Represents a supported "second-level" field of the object, where the "top-level" field (with name "field-1") has a value that is an object, and it is then on that sub-object that the parameter action is to be applied, to the field (with name "subfield-1") within the sub-object.
|
