1.6.3. Manipulating Managed Objects Programmatically

You can address managed objects as resources using URLs or URIs with the managed/ prefix. This works whether you address the managed object internally as a script running in OpenIDM or externally through the REST interface.

You can use all resource API functions in script objects for create, read, update, delete operations, and also for arbitrary queries on the object set, but not currently for arbitrary actions. See the Scripting Reference appendix for details.

OpenIDM supports concurrency through a multi version concurrency control (MVCC) mechanism. In other words, each time an object changes, OpenIDM assigns it a new revision.

Objects can be arbitrarily complex as long as they use supported types, such as maps, lists, numbers, strings, and booleans as defined in JSON.

1.6.3.1. Creating Objects

The following script example creates an object type.

openidm.create("managed/foobar/myidentifier", mymap)
1.6.3.2. Updating Objects

The following script example updates an object type.

var expectedRev = origMap._rev
openidm.update("managed/foobar/myidentifier", expectedRev, mymap)

The MVCC mechanism requires that expectedRev be set to the expected revision of the object to update. You obtain the revision from the object's _rev property. If something else changes the object concurrently, OpenIDM rejects the update, and you must either retry or inspect the concurrent modification.

1.6.3.3. Patching Objects

You can partially update a managed object using the patch method, which changes only the specified properties of the object. OpenIDM implements the JSON patch media type version 02, described at https://tools.ietf.org/html/draft-pbryan-json-patch-02.

The following script example updates an object type.

openidm.patch("managed/foobar/myidentifier", rev, value)

The patch method supports a revision of "null", which effectively disables the MVCC mechanism, that is, changes are applied, regardless of revision. In the REST interface, this matches the If-Match: "*" condition supported by patch.

The API supports patch by query, so the caller does not need to know the identifier of the object to change. 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST -d '[{"replace":"/password","value": "Passw0rd"}]' 
 "http://localhost:8080/openidm/managed/user?_action=patch&_queryId=for-userName&uid=DDOE"

For the syntax on how to formulate the query _queryId=for-userName&uid=DDOE see Section 1.6.3.6, “Querying Object Sets”.

1.6.3.4. Deleting Objects

The following script example deletes an object type.

var expectedRev = origMap._rev
openidm.delete("managed/foobar/myidentifier", expectedRev)

The MVCC mechanism requires that expectedRev be set to the expected revision of the object to update. You obtain the revision from the object's _rev property. If something else changes the object concurrently, OpenIDM rejects deletion, and you must either retry or inspect the concurrent modification.

1.6.3.5. Reading Objects

The following script example reads an object type.

val = openidm.read("managed/foobar/myidentifier")
1.6.3.6. Querying Object Sets

The following script example queries object type instances.

var params = {
    "_queryId": "my-custom-query-id",
    "mycustomtoken": "samplevalue"
};
val = openidm.query("managed/foobar", params);

The example sets up a query with ID my-custom-query-id. The query definition (not shown) is found in the repository configuration. The query definition includes the parameter mycustomtoken for token substitution.

An example for a query can be found in chapter Managed Object as Correlation Query Target .