Chapter 6. Accessing Data Objects

Managed objects in the supported OpenIDM repositories can be accessed using a parameterized query mechanism. Parameterized queries on repositories are defined in the repository configuration (repo.*.json) and are called by their _queryId.

Parameterized queries provide security and portability for the query call signature, regardless of the back-end implementation. Queries that are exposed over the REST interface must be parameterized queries to guard against injection attacks and other misuse. Queries on the officially supported repositories have been reviewed and hardened against injection attacks.

For system objects, support for parameterized queries is restricted to _queryId=query-all-ids. There is currently no support for user-defined parameterized queries on system objects. Typically, parameterized queries on system objects are not called directly over the REST interface, but are issued from internal calls, such as correlation queries.

A typical query definition is as follows:

"query-all-ids" : "select _openidm_id from ${unquoted:_resource}"

To call this query, you would reference its ID, as follows:

?_queryId=query-all-ids

The following example calls query-all-ids over the REST interface:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 "http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids"
            

Native query expressions are supported for all managed objects and system objects, and can be called directly over the REST interface, rather than being defined in the repository configuration.

Native queries are intended specifically for internal callers, such as custom scripts, in situations where the parameterized query facility is insufficient. For example, native queries are useful if the query needs to be generated dynamically.

The query expression is specific to the target resource. For repositories, queries use the native language of the underlying data store. For system objects that are backed by OpenICF connectors, queries use the applicable query language of the system resource.

Native queries on the repository are made using the _queryExpression keyword. For example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 "http://localhost:8080/openidm/managed/user?_queryExpression=select+*+from+managedobjects"
            

Unlike parameterized queries, native queries are not portable and do not guard against injection attacks. Such query expressions should therefore not be used or made accessible over the REST interface or over HTTP, other than for development, and should be used only via the internal Resource API. For more information, see the section on Protecting Sensitive REST Interface URLs.

If you really need to expose native queries over HTTP, in a selective manner, you can design a custom endpoint to wrap such access.

The openidm.query function enables you to query OpenIDM resource objects for reconciliation processes and workflows. Query syntax is openidm.query(id, params), where id specifies the object on which the query should be performed and params provides the parameters that are passed to the query. For example:

var params = {
    'query' : {
        'Equals': {
            'field' : 'uid',
            'values' : [
                id
            ]
        }
    }
};
var results = openidm.query("system/ScriptedSQL/account", params)
            

OpenIDM supports nine query filters and a range of keywords that can be applied to these filters. Each filter takes a field and a list as value. The following filters are supported:

Attribute Operations

Comparable Attribute Operations

Compares single-value attributes to a given filter.

String Attribute Operations

Compares string values to a given filter.

Filter Operations

Filter operations are used to construct more complex filters by comparing two filters from the preceding section or negating filters defined in the previous section.