UserAudit Query API

Resource URL

GET /seiapi/v3/query/UserAudit?filter=${filterOptions}&q={queryOtions}sort=${sortOptions}&limit=${limit}&customerid=xxxx&customercode=xxxx

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).

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 consists of three parts: A selector, a comparison-op, 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
"=le=" or “<="	Less than or equals to
“=in="	In
“=out="	Not in
"=like="	Field values which are similar (like)
";” or “and"	Logical AND
",” or “or"	Logical OR

q

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).

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:

q=<search term>::in:field-1,field-2

The q parameter supports partial term matches across multiple fields. For example, a search term of Joh 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:

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.

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.

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:

sort=[-]field-1,[-]field-2

field-1 - The field name to sort against;
[ - ] - Optional value that identifies the field is to be sorted in descending order.

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; and
field-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.

Filters

The ${filterOptions} parameter supports the following User Audit Object fields:

Category
Latitude
Longitude
RefCode
Subcategory
TimeStamp
UserID
UserStatus

Q

The ${queryOptions} supports the following User Audit Object fields:

Category
Latitude
Longitude
RefCode
Subcategory
TimeStamp
UserID
UserStatus

Sort

The ${sortOptions} supports the following User Audit Object fields:

Category
Latitude
Longitude
RefCode
Subcategory
TimeStamp
UserID
UserStatus

Date Ranges

This API supports an extended filter format for the TimeStamp field as follows:

Syntax	Description
(date₁..date₂)	TimeStamp > date₁and < date₂
[date₁..date₂]	TimeStamp >= date₁and <= date₂
(date₁..date₂]	TimeStamp > date₁and <= date₂
[date₁..date₂)	TimeStamp >= date₁and < date₂
(date₁..)	TimeStamp > date₁
[date₁..)	TimeStamp >= date₁
(..date₂)	TimeStamp < date₂
(..date₂]	TimeStamp <= date₂
(..)	All values are valid

Example:

..&filter=TimeStamp:[2015-01-01T10:00:00.0Z..]

HTTP Headers

This API uses the default ServiceMobility HTTP Headers.

HTTP Response Body

The response body contains a collection of User Audit Object objects that match the query parameters.

JSON Format

 {
    "TotalRecords" : 0,
    "Items" : [
		{
			// object definition 
		}
    ]
}

HTTP Response

Response Codes

HTTP Code	Description
200	OK. Request was processed successfully. Even though the request may return a successful code of 200, the body may still contain warning details.
400	Syntax error in request. The response body will provide more details on the specific reason. Verify the URI, its parameters, and request body.
401	Unauthorized. The credentials are incorrect, please verify and try again.
404	Not Found. The URL is incorrect, please verify and try again.
405	The specified HTTP method is not supported for this resource.
409	Conflict. This error usually occurs when attempting to overwrite an existing object that can not be replaced.
410	The specified object does not exists. Please verify the URI.
500	An error has occurred within ServiceMobility. Please review the error message details and if necessary, contact customer support.

Response Body

{
    "code": 400,
    "detail": {
        "message": "",
        "params": {
            "value": ""
        },
        "dataPath": ""
    }
}

Response Object Properties

Property

Type

Description

code

integer

The HTTP response code.

detail

object

This object provides additional details the system provided while processing the transactions. Usually the details provide additional information on why an error occurred. However, it may also provide warning details even when the requests was successful. For example, the request may have returned a response of 200=OK, but included warnings in the response body of properties that are still being used that are marked for deprecation.

Property	Type	Description
message	string	A human readable message related to the processing of the request.
params	collection	A collection of additional key/value pairs that contain the values that caused the warning/error condition.
dataPath	string	Identifies the location within the request body the message refers to.