System Metadata

Cloud CMS automatically tracks system metadata for all of the objects that you create within it. System metadata consists of non-data values that describe things like who created an object and when it was modified.

System Metadata

This system metadata is tracked under the special _system key at the root of your objects. This system metadata is read-only in so far as it is tracked by Cloud CMS automatically.

It is available for any object returned by any of the Cloud CMS APIs by simply specifying metadata=true as a request parameter.

System metadata can be used within your queries just like any other key/value pair within your data set. For nodes, system metadata does not participate in schema validation.

Creation

Cloud CMS automatically tracks system metadata around the creation of every object:

Key Type Description
_system.created_on.timestamp string Creation datetime (UST) in friendly format ("dd-MMM-yyyy HH:mm:ss")
_system.created_on.iso_8601 string Creation datetime (UST) in ISO 8601 format ("yyyy-MM-dd'T'HH:mm:ssZ")
_system.created_on.year number Creation datetime (UST) year
_system.created_on.month number Creation datetime (UST) month
_system.created_on.day_of_month number Creation datetime (UST) day of month (0 - 30)
_system.created_on.hour number Creation datetime (UST) hour
_system.created_on.minute number Creation datetime (UST) minute
_system.created_on.second number Creation datetime (UST) second
_system.created_on.millisecond number Creation datetime (UST) millisecond
_system.created_on.ms number Creation datetime (UST) milliseconds since Unix epoch (current time millis)
_system.created_by string The user name of the principal who created this object
_system.created_by_principal_id string The ID of the principal who created this object
_system.created_by_principal_domain_id string The Domain ID of the principal who created this object

Last Modification

Cloud CMS automatically tracks system metadata around the last modification of every object:


Key Type Description
_system.modified_on.timestamp string Last modification datetime (UST) in friendly format ("dd-MMM-yyyy HH:mm:ss")
_system.modified_on.iso_8601 string Last modification datetime (UST) in ISO 8601 format ("yyyy-MM-dd'T'HH:mm:ssZ")
_system.modified_on.year number Last modification datetime (UST) year
_system.modified_on.month number Last modification datetime (UST) month
_system.modified_on.day_of_month number Last modification datetime (UST) day of month (0 - 30)
_system.modified_on.hour number Last modification datetime (UST) hour
_system.modified_on.minute number Last modification datetime (UST) minute
_system.modified_on.second number Last modification datetime (UST) second
_system.modified_on.millisecond number Last modification datetime (UST) millisecond
_system.modified_on.ms number Last modification datetime (UST) milliseconds since Unix epoch (current time millis)
_system.modified_by string The user name of the principal who last modified this object
_system.modified_by_principal_id string The ID of the principal who last modified this object
_system.modified_by_principal_domain_id string The Domain ID of the principal who last modified this object

Last Edit

In addition to last modification (which includes modifications by any user, including system users), Cloud CMS automatically tracks last intentional modifications by editorial users. This is to say, Cloud CMS separately tracks modification information concerning changes made deliberately by editorial users.

Suppose an editorial user saves a change to a document a 1:00:00 pm. After the save, a rule might trigger that runs an AWS Transcoder job that converts video described by input keys on the document. The resulting output keys would later be written back to the document at, say, 1:02:47 pm. In this case, the editor last modification timestamp would be 1:00:00 pm (because, from the editor's standpoint, that's when they last made a change). However, the modified last modification timestamp would be 1:02:47 pm (because, technically, that's the last moment in time when the document was updated - even if it was by a system process).

Key Type Description
_system.edited_on.timestamp string Last edit datetime (UST) in friendly format ("dd-MMM-yyyy HH:mm:ss")
_system.edited_on.iso_8601 string Last edit datetime (UST) in ISO 8601 format ("yyyy-MM-dd'T'HH:mm:ssZ")
_system.edited_on.year number Last edit datetime (UST) year
_system.edited_on.month number Last edit datetime (UST) month
_system.edited_on.day_of_month number Last edit datetime (UST) day of month (0 - 30)
_system.edited_on.hour number Last edit datetime (UST) hour
_system.edited_on.minute number Last edit datetime (UST) minute
_system.edited_on.second number Last edit datetime (UST) second
_system.edited_on.millisecond number Last edit datetime (UST) millisecond
_system.edited_on.ms number Last edit datetime (UST) milliseconds since Unix epoch (current time millis)
_system.edited_by string The user name of the principal who last edited this object
_system.edited_by_principal_id string The ID of the principal who last edited this object
_system.edited_by_principal_domain_id string The Domain ID of the principal who last edited this object

Nodes

Content nodes in Cloud CMS also track a few additional system metadata properties. Unlike other objects in Cloud CMS, content nodes are versioned using changesets and so things like changeset IDs and deletion state are captured as system metadata.

Key Type Description
_system.deleted boolean Whether this node was deleted (written onto its changeset as a delete)
_system.changeset string The ID of the changeset upon which this node was written

API

In using the Cloud CMS API, you can request system metadata properties by adding the following to your call:

?metadata=true

System metadata properties will be available under the special _system key. Here is an example:

{
    "title": "My Article",
    "description": "My Article Description",
    "_type": "my:article",
    "_doc": "5bfefc440497b4cf546d",
    "_system": {
        "deleted": false,
        "changeset": "40:84e03c7bbb4813a2e16e",
        "created_on": {
            "timestamp": "04-May-2016 10:08:20",
            "year": 2016,
            "month": 4,
            "day_of_month": 4,
            "hour": 10,
            "minute": 8,
            "second": 20,
            "millisecond": 821,
            "ms": 1462370900821
        },
        "created_by": "joesmith",
        "created_by_principal_id": "cc4c84b0d0de2849de4b",
        "created_by_principal_domain_id": "default",
        "modified_on": {
            "timestamp": "04-May-2016 10:08:20",
            "year": 2016,
            "month": 4,
            "day_of_month": 4,
            "hour": 10,
            "minute": 8,
            "second": 20,
            "millisecond": 853,
            "ms": 1462370900853
        },
        "modified_by": "admin",
        "modified_by_principal_id": "cc4c84b0d0de2849de4b",
        "modified_by_principal_domain_id": "default"
    },
    "_qname": "o:5bfefc440497b4cf546d",
}

You can use system metadata properties in your queries. For example, you might query for all nodes that were modified in 2016, with a query like this:

{
    "_system.modified_on.year": 2016
}

Or all nodes that were created by a particular user:

{
    "_system.created_by": "joesmith"
}