Query and Search Object Records

Multiple Objects

Querying multiple object records can be performed using /api/objects

Accessing this endpoint requires the "Identity Panel" license sku, and "Read|ObjectRecord" data permission.

The endpoint returns a ListWrap<ObjectRecord> containing entries matching the filter query (see below). Unless a limit parameter is specified, the default object page size of 10 is used.

Response Sample:

{
  "Count": 23,
  "Data": [
    {
      "$type": "SoftwareIDM.SyncModel.MVRecord, SoftwareIDM.SyncModel",
      "Id": "...",
      ...
    }
  ]
}

Query Parameters:

In addition to the required headers/parameters for forgery validation, the GET endpoint supports Query Filter Parameters.

Single Objects

Querying single objects can be done using /api/objects/{id}

Requires the same permissions as multiple object query, unless the type parameter is used, in which case the user must also have permission to read the targeted type.

Single object querying supports additional features like link expansion and querying of alternate object types. The primary use of this API endpoint is for the Time Traveller interface.

The id argument should be the Id of the object to be returned (typically a GUID in octet string format). If using a type constraint to retrieve a non-ObjectRecord object, the Id may be a byte array in which case Url Base64 encoding should be used (- instead of +, _ instead of /,- instead of =).

Query Parameters:

type: Required to switch type to anything but an ObjectRecord. Must be a fully qualified type name from the white-list of serializable types, for example:

SoftwareIDM.WorkflowModel.WorkflowRecord, SoftwareIDM.WorkflowModel

silo: Recommended (applies to ObjectRecord only), identifies the silo (as a guid string value) which contains the requested object. If an installation has many large silos including the silo parameter can significantly improve the performance of the response.

provider: Similar to silo, can be used to constrain query

expand: If querying an ObjectRecord, will switch the returned object from an ObjectRecord, to a LinkedObjectResult. This will expand join relationships to return a complete graph of connected objects, e.g. for display in time traveler.

A linked object result takes the form:

{
  "Object": ObjectRecord
  "Links": {
    "<id>": ObjectRecord,
    ...
  }
}

Search Objects

To query objects via full-text search user /api/search or /api/search/index

If specified, index should be the string guid identifying an ObjectRecord silo. If unspecified all indices will be searched (or all indices specified under the default search scopes under Settings / Shutters)

Identity Panel uses Elasticsearch to full-text index all string attributes of all object records. Query terms may use Elasticsearch query syntax.

Searches fetch a list of ids, and the corresponding objects are fetched from the MongoDB database using normal security rules.

Response:

Calls to /api/search will return a ListWrap<SearchIndexResult> and calls to /api/search/index will return a SearchIndexResult.

SearchIndexResult extends ListWrap<ObjectRecord> to add a string "Index" property so it takes the form

{
  "Index": "<silo>",
  "Count": result count,
  "Data: [
    ObjectRecords...
  ]
}

NOTE: a list of queryable indices (including schema information) may be obtained by running:

helpers.rest.get('search/indices', (r) => console.log(r))

Query Parameters:

The query may be controlled via the following parameters:

• limit: Page result set (NOTE: a limit of 0 will result in the maximum value of 1000)
• skip: Page result set
• minCreated: constrain query to objects that were created after the specified value
• maxCreated: constrain query to objects that were created before the specified value
• minModified: constrain query to objects that were last updated after the specified value
• maxModified: constrain query to objects that were last updated before the specified value
• deleted: if defined, will include objects with a deleted timestamp in the search result. By default these objects are excluded
• objectType: constrain object type, non-case-sensitive
• field: constrain search to particular attribute name, case-sensitive
• operator: contains (default), startswith, not, phrase (controls elasticsearch matching behavior)
• term: string search term