Track User Metadata
Some self-service features, such as progressive profile completion, privacy and consent, and terms and conditions acceptance, rely on user metadata that tracks information related to a managed object state. Such data might include when the object was created, or the date of the most recent change, for example. This metadata is not stored within the object itself, but in a separate resource location.
Because object metadata is stored outside the managed object, state change situations (such as the time of an update) are separate from object changes (the update itself). This separation reduces unnecessary synchronization to targets when the only data that has changed is metadata. Metadata is not returned in a query unless it is specifically requested. Therefore, the volume of data that is retrieved when metadata is not required, is reduced.
To specify which metadata you want to track for an object, add a meta
stanza to the object definition in your schema (in the UI or in conf/managed.json
). The following default configuration tracks the createDate
and lastChanged
date for managed user objects:
{ "objects" : [ { "name" : "user", ... "schema" : { ... }, "meta" : { "property" : "_meta", "resourceCollection" : "internal/usermeta", "trackedProperties" : [ "createDate", "lastChanged" ] }, ... }, ... ] }
Important
If you are not using the self-service features that require metadata, you can remove the meta
stanza from your user object definition in managed.json
. Preventing the creation and tracking of metadata where it is not required will improve performance in that scenario.
The metadata configuration includes the following properties:
property
The property that will be dynamically added to the managed object schema for this object.
resourceCollection
The resource location in which the metadata will be stored.
Adjust your repository to match the location you specify here. It's recommended that you use an
internal
object path and define the storage in yourrepo.jdbc.json
orrepo.ds.json
file.For a JDBC repository, metadata is stored in the
metaobjects
table by default. Themetaobjectproperties
table is used for indexing.For a DS repository, metadata is stored under
ou=usermeta,ou=internal,dc=openidm,dc=forgerock,dc=com
by default.User objects stored in a DS repository must include the
ou
specified in the precedingdnTemplate
attribute. For example:dn: ou=usermeta,ou=internal,dc=openidm,dc=forgerock,dc=com objectclass: organizationalunit objectclass: top ou: usermeta
trackedProperties
The properties that will be tracked as metadata for this object. In the previous example, the
createDate
(when the object was created) and thelastChanged
date (when the object was last modified) are tracked.
You cannot search on metadata and it is not returned in the results of a query unless it is specifically requested. To return all metadata for an object, include _fields=,_meta/*
in your request. The following example returns a user entry without requesting the metadata:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/bjensen"
{ "_id": "bjensen", "_rev": "000000000444dd1a", "mail": "bjensen@example.com", "givenName": "Barbara", "sn": "Jensen", "description": "Created By CSV", "userName": "bjensen", "telephoneNumber": "1234567", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] }
The following example returns the same user entry, with their metadata:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/bjensen?_fields=,_meta/*"
{ "_id": "bjensen", "_rev": "000000000444dd1a", "mail": "bjensen@example.com", "givenName": "Barbara", "sn": "Jensen", "description": "Created By CSV", "userName": "bjensen", "telephoneNumber": "1234567", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] "_meta": { "_ref": "internal/usermeta/284273ff-5e50-4fa4-9d30-4a3cf4a5f642", "_refResourceCollection": "internal/usermeta", "_refResourceId": "284273ff-5e50-4fa4-9d30-4a3cf4a5f642", "_refProperties": { "_id": "30076e2e-8db5-4b4d-ab91-5351d2da4620", "_rev": "000000001ad09f00" }, "createDate": "2018-04-12T19:53:19.004Z", "lastChanged": { "date": "2018-04-12T19:53:19.004Z" }, "loginCount": 0, "_rev": "0000000094605ed9", "_id": "284273ff-5e50-4fa4-9d30-4a3cf4a5f642" } }
Note
Apart from the createDate
and lastChanged
shown previously, the request also returns the loginCount
. This property is stored by default for all objects, and increments with each login request based on password or social authentication. If the object for which metadata is tracked is not an object that "logs in," this field will remain 0.
The request also returns a _meta
property that includes relationship information. IDM uses the relationship model to store the metadata. When the meta
stanza is added to the user object definition, the attribute specified by the property
("property" : "_meta",
in this case) is added to the schema as a uni-directional relationship to the resource collection specified by resourceCollection
. In this example, the user object's _meta
field is stored as an internal/usermeta
object. The _meta/_ref
property shows the full resource path to the internal object where the metadata for this user is stored.