--- title: Track user metadata description: Some features, such as terms and conditions acceptance, rely on user metadata that tracks information related to a managed object state. For example, such data might include when the object was created, or the date of the most recent change, for example. This metadata isn't stored within the object itself, but in a separate resource location. component: pingidm version: 8.1 page_id: pingidm:objects-guide:object-meta-data canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/object-meta-data.html keywords: ["Data Object Model", "Metadata"] --- # Track user metadata Some features, such as terms and conditions acceptance, rely on user *metadata* that tracks information related to a managed object state. For example, such data might include when the object was created, or the date of the most recent change, for example. This metadata isn't 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 metadata is the only data that has changed. Metadata isn't returned in a query unless it is specifically requested. Therefore, the volume of data that is retrieved when metadata isn't required is reduced. To specify which metadata you want to track for an object, add a `meta` stanza to the object definition in your managed object configuration. The following default configuration tracks the `createDate` and `lastChanged` date for managed user objects: ```json { "objects" : [ { "name" : "user", ... "schema" : { ... }, "meta" : { "property" : "_meta", "resourceCollection" : "internal/usermeta", "trackedProperties" : [ "createDate", "lastChanged" ] }, ... }, ... ] } ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you are not using features that require metadata, you can remove the `meta` stanza from the `user` object in your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. Preventing the creation and tracking of metadata where it's 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 your `repo.jdbc.json` or `repo.ds.json` file. For a JDBC repository, metadata is stored in the `metaobjects` table by default. The `metaobjectproperties` 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 preceding `dnTemplate` attribute. For example: ```ldif 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 the `lastChanged` 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" } } ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. If the object for which metadata is tracked isn't an object that "logs in," this field remains 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.