Filter Query Parameters

Filter query parameters are supported by any API endpoint that uses the FilterQuery helper classes to expose database data by converting URL query parameters into MongoDB queries.

Access to these APIs requires appropriate licensing for the endpoint and appropriate "Read|Type" data permissions.

APIs that support this interface include:

• Identity Panel
  • /api/objects
  • /api/multis
  • /api/logging
  • /api/histories
  • /api/statistics
  • /api/healthchecks
  • /api/errordetails
  • /api/portalapprovals
  • /api/portalrequests
  • /api/portalworkflows
  • /api/workflow
  • /api/accessentries
  • /api/directoryschemas
  • /api/datasignature
  • /api/accesslog
  • /api/notes
  • /api/schedules
• Service Panel
  • /api/servicestep
• MIMTest
  • /api/fixtures
  • /api/suites
  • /api/assertions
  • /api/systemschemas
• Access Panel
  • /api/accesscampaigns
  • /api/accessentitlements
  • /api/accessprincipals

NOTE: most of these controllers also support additional actions that are more specific to different aspects of business logic.

Query Parameters:

NOTE: all query parameters are optional. An empty set of parameters will just query the underlying collection and return the first 10 results.

• limit: Paging parameter, default value is 10, setting limit=0 will return the full result set up to the maximum value of 1000
• skip: paging parameter, default 0
• fields: comma separated list of fields to specify as Include property of underlying data query. used to reduce size of data queried from database and returned. Allows dotted path notation, e.g. for an object record you might have:
  • Id,ObjectType,Attributes.sAMAccountName
• sort: singular field to use for sorting results. May use dotted notation: e.g. Attributes.sAMAccountName. Query may fail if a large collection is queried while sorting on an un-indexed field. Prefix field name with "-" to sort in descending order.
• filter: database query to parse. See details below

Filter:

NOTE: the following discusses filters prior to URI encoding. The entire filter query should be escaped using Query Data URI rules. In Identity Panel this may be done by passing an object to helpers.toQueryString: e.g.

helpers.toQueryString({
  limit: 5,
  filter: 'Silo eq string:<silo id> ObjectType eq person'
 });

A filter may have 0 or more clauses separated by spaces.

A clause may have the form:

<field> <operator> or <field> <operator> <filter value>

NOTE: If the operator is "null" or "notnull" the value is not required.

Because tokens in a field query are separated by spaces, if a token contains a space it must be escaped with '\'. To encode a backslash use '\\'

IMPORTANT: operators are not case-sensitive, but field names and values ARE.

Fields:

Field names should match object property paths as pictured in the Rule Engine. For Example:

• Id
• Silo
• ObjectType
• Attributes.userPrincipalName
• Attributes.First Name (which must be encoded as Attributes.First\ Name)
• RecordOf
• Argument
• _t – type constraint for polymorphic typed object, e.g.
  • SoftwareIDM.SyncModel.MVRecord,\ SoftwareIDM.SyncModel

Operators:

The following operators are supported:

• eq: equals
• ne: not equals
• lt: less than
• gt: greater than
• lte: less than or equal
• gte: greater than or equal
• in: (takes comma separated list of values)
• notnull (field is defined and has a value)
• null (field is not defined or has null value)
• contains (textual contains, reduced performance compared to equals, uses the underlying $regex operator)
• startswith (reduced performance compared to equals, uses the underlying $regex operator)
• endswith (reduced performance compared to equals, uses the underlying $regex operator)
• sizeeq (length of an array property)

Values:

Values are parsed and typed according to the following rules:

1. If the operator is 'SizeEq' the value is parsed as an int (or 0 if not a number)
2. If the operator is 'In', the value is split on ',' and each sub-value is parsed
3. If the field is _t and the value is a fully qualified type name that meets white-listing rules the value is translated to its underlying database discriminator
4. If the operator is contains, startswith, or endswith the raw value is treated as a string

Otherwise:

The value will be attempted for parsing as one of the following types in order. If it does not parse as a typed value it is treated as a string.

• DateTime (parsed and converted to UTC)
• integer (64 bit)
• boolean
• GUID/UUID

To prevent typed parsing (e.g. a parameter that looks like a guid but should be parsed as a string), the value may be prefixed with "type:" accepted type parameters (non-case-sensitive) are:

• null
• string
• long
• double
• binary (expects base-64 encoded string data)
• boolean
• guid
• datetime
• timespan

Note: objects will fail to match on the equality operator if there is a type mismatch between the query value and database value.