Filtering Endpoints

This section describes using the filter parameter for querying data

Identity Panel Suite defines a number of ReST endpoints which support a common set of query parameters for filtering and paginating data via control over the underlying database queries. This control happens via the following parameters:

• limit - number of records to fetch, defaults to 10 in most cases. If set to 0 will attempt to return all records.
• skip - paginate past records, defaults to 0
• filter - filter via database properties
• sort - Sort by a single field name, e.g. sort=Attributes.employeeId. May be prefixed with - to support a descending sort.
• fields - Optional list of properties to load from database. By default full objects are loaded, but setting fields makes it possible to more efficiently fetch a smaller object. e.g. fields=Silo,DN,Attributes,ObjectType

Filtering

To query filtered endpoints the authenticated caller must be assigned Read permission on the underlying data type(s) via an Identity Panel security role.

The filter parameter is used to construct a database query from a series of clauses. Filters are constructed from clauses with the form Field Operator Value. The entire filter value should be data URI encoded since spaces and special characters are significant.

Filter Clauses

Field
Fields are case sensitive. Available filter fields depend on the queried object. Fields may use dotted notation to query based on sub-properties, e.g. Attributes.displayName.

Operator
Operators are not case-sensitive. The following operators are supported:

• Eq - field equals value
• Ne - field is not equal to value
• Lt - field is less than value
• Gt - field is greater than value
• Lte - field is less than or equal to value
• Gte - field is greater than or equal to value
• In - value is a comma separated list, and field is contained in the list
• NotNull - field has a (non-null) value, for this operator value should not be specified
• Null - field is null or is not defined, for this operator value should not be specified
• Contains - field contains the text value (Note: this operator is relatively expensive to execute)
• StartsWith - field starts with the text value (Note: this operator is relatively expensive to execute)
• EndsWith - field ends with the text value (Note: this operator is relatively expensive to execute)
• Regex - value is a regex which matches field (Note: this operator is relatively expensive to execute)

Value
Text values are case-sensitive. Where possible value type is inferred, but type hints are needed in cases where the queried field has type Object, e.g. when querying an Attribute value.

Because spaces are used to separate fields, operators, and values, spaces within a value must be escaped. Values containing spaces may be escaped by wrapping in double quotes, wrapping in single quotes, or placing a backslash \ before the space. A backslash in a non-quoted value must be escaped with another backslash. When using type hints, wrap the entire value token in quotes.

For example:

• "has domain\name"
• "string:has domain\name"
• 'has domain\name'
• has\ domain\\name

The query engine will attempt to parse a value as a typed value, before falling through to string. In many cases it is necessary to use an explicit type hint (see below) to achieve the desired behavior. The descending type priority is:

1. Try parse as datetime
2. Try parse as integer
3. Try parse as decimal
4. Try parse as boolean
5. Try parse as guid
6. Default to string

A value may start with one of the following hints to force typed parsing (case-insensitive):

• string: - parse as string
• long: - parse as int64
• double: - parse as 64 bit floating point number
• binary: - parse as base64 encoded byte array
• boolean: - parse as boolean value
• guid: - parse as 16 byte uuid
• datetime: - parse as .NET datetimestamp
• timespan: - parse as .NET timespan/duration
• objectid: - parse as MongoDB ObjectId

Supported Endpoints

The following data types/endpoints support filtering via a GET request:

Identity Panel

• Error Detail - /api/errordetails
• Health Check - /api/healthchecks
• Log Message - /api/logs
• Multi Attribute - /api/multis
• Object Record - /api/objects
• History Record - /api/histories
• History Statistic (cut down history record) - /api/statistics
• Version History - /api/versions
• Pending Workflows and Workflow History - /api/workflows
• Report Definitions - /api/reports
• Schedule Definitions - /api/schedules
• Notes - /api/notes

Access Panel

• Access Policy - /api/accesspolicies
• Campaign Definition - /api/campaigndefinitions
• Campaign Instance - /api/campaigninstances
• Delegation - /api/delegations
• SoD Exception - /api/sodexceptions

Test Panel

• Assertion - /api/assertions
• Fixture - /api/fixtures
• Suite - /api/suites
• System Schema - /api/systemschemas

Providers/Connections

• ACL Entry - /api/accessentries
• Panel Action - /api/panelactions
• MIM Portal Approval - /api/portalapprovals
• MIM Portal Workflow - /api/portalworkflows
• MIM Portal Request - /api/portalrequests