Traceable entities

Some BigContent data entities like Document or Content contain a set of shared properties to track changes (dateCreated, dateModified, author and lastModifier). These properties are managed by the platform, that means they cannot be edited with operations and we don’t need to send them in any POST or PUT method.
Note that when deleting an entity, we never update the traceable properties.

General rule

Regarding how these properties are updated, there are some scenarios that require a clear description. For example contents located in a document are treated independently from the document metadata. In this case, modifications in the document’s contents (e.g. creation of a new version) are not reflected in the Document’s traceable properties.

Document metadata example
{
  "id" : "qga8r5hsy9rw5weggf93lopa58",
  "description" : "Invoice template",
  "_hidden" : false,
  "author" : "john@company.com",
  "dateCreated" : "2018-10-24T07:10:51.709Z",
  "lastModifier" : "john@company.com",
  "dateModified" : "2018-10-24T07:10:51.709Z",
  "currentVersion" : "1.0",
  "content" : [
    {
      "id" : "g8q9ppihd58art2f9op1sq28gh",
      "name" : "invoice.pdf",
      "type" : "application/pdf",
      "size" : 58943,
      "majorVersion" : 1,
      "minorVersion" : 0,
      "_hidden" : false,
      "author" : "john@company.com",
      "dateCreated" : "2018-10-24T07:10:51.709Z",
      "lastModifier" : "john@company.com",
      "dateModified" : "2018-10-26T09:15:55.980Z"
    }
  ],
  "categories" : [
    {
      "_name": "template",
      "Type": "invoice",
      "date": "2018-10-24T07:10:51.709Z",
      "boolean": true
    }
  ],
  "documentStore" : "invoice_store"
}

This is done to provide as much information as possible about the lifecycle of the documents. However, we are aware this can cause some confusion.

As a quick summary, keep in mind:

  • When creating or updating a traceable entity, only its own properties will be updated (nor containee or contained).

  • When deleting a traceable entity, it shall not modify any traceable properties.

  • When creating or updating non-traceable entities (e.g. categories inside a document), changes are reflected in the containee.

We do not update the properties when applying metadata_flagging deletion. That means that when we delete a Document, traceable properties are not modified. Same behavior when we delete a Content, same behavior should be expected.

Creating an entity

If the entity is traceable, we will initialize all four properties as follows:

  • author and lastModifier will contain the user account doing the operation.

  • dateCreated and dateModified will contain the time of the operation.

When the entity created is not traceable, we update the dateModified and lastModifier properties of the closer parent entity.

Table 1. Examples
Entity Action Result

Document (traceable)

Creating a Document with a contained Content (traceable)

We initialize all four properties for the document and the content.

Content (traceable)

Adding a new Content to an existing Document (traceable)

We only initialize all traceable properties of the Content

Category (not traceable)

Adding a new Category to an existing Document (traceable)

We update dateModified and lastModifier properties of the parent entity, in this case, the Document

Updating an entity

If the entity is traceable, we will only update dateModified and lastModifier properties. If it is not, we will update dateModified and lastModifier properties of the closer parent.

Table 2. Examples
Entity Action Result

Document (traceable)

Updating a Document metadata

For example, when updating the description of the Document, we only update the dateModified and lastModifier properties of the Document

Content (traceable)

Updating a Content in an existing Document (traceable)

For example, when overriding a content with Update current version we update the dateModified, lastModifier properties of the itself Content

Category (not traceable)

Updating a Category in an existing Document (traceable)

In the case we modify, for example, the name of the Category, we need to update the dateModified and lastModifier properties of the Document

Deleting an entity

We never modify any property with this operation, as the entity itself is deleted.

About logical deletion…​

Currently only supported by Documents and Contents. When performing a logical deletion, we are not updating the traceable properties to avoid some confusing scenarios.

For example, when a Document is deleted and then later restored, a non-admin user not aware of the underlying process may be confused if he/she saw dates changing. It may look like as if the document has been tampered while the actual information in the document has remained the same.
The implication of this is that we are not treating the hidden property as a simple metadata, but more akin to security rule, as an update in a security property would update the traceable properties.