Document Model

Documents and Folders

In the Hippo Repository, folders are in general of type hippostd:folder, which defines the types of documents and child folders that can be created with the FolderWorkflow.

Documents are represented by hippo:handle nodes. These nodes can have multiple children with sub-types of hippo:document. They are termed 'variants'. Documents with simple workflows, like images and assets, only have one such variant. But the more complex 'documentworkflow' workflow manages three such variants (see below).

Each folder node has a mix:referenceable mixin added to it. Document variants also get the mix:referenceable mixin by default, unless a version history is needed, in which case the mix:versionable mixin is used. Similarly, handles have the mix:referenceable mixin, reflecting the fact that their UUIDs can be used to reference the document.

In YAML format, a typical node structure in the repository therefore looks something like this:

/myproject:
  jcr:primaryType: hippostd:folder
  jcr:mixinTypes: ['hippo:named', 'hippotranslation:translated', 'mix:referenceable']
  jcr:uuid: 92f48970-7b13-4c68-8a2e-491c84588b9c
  hippo:name: My Hippo Project
  hippostd:foldertype: [new-translated-folder, new-document]
  hippotranslation:id: 996bcac5-86cf-49b5-a7a3-16a74863e814
  hippotranslation:locale: en
  /content:
    jcr:primaryType: hippostd:folder
    jcr:mixinTypes: ['hippotranslation:translated', 'mix:referenceable']
    jcr:uuid: fbbfb1ab-2b57-4ae3-b1f0-a3597c3df94d
    hippostd:foldertype: [new-content-document, new-content-folder]
    hippotranslation:id: 6297cf67-37d8-428e-aaf1-d64a5289af8a
    hippotranslation:locale: en
    /sample-document:
      jcr:primaryType: hippo:handle
      jcr:mixinTypes: ['hippo:named', 'mix:referenceable']
      jcr:uuid: 64ab4648-0c20-40d2-9f18-d7a394f0334b
      hippo:name: Sample document
      /sample-document[1]:
        jcr:primaryType: myproject:contentdocument
        jcr:mixinTypes: ['mix:referenceable']
        jcr:uuid: 570182a8-2b85-48c9-ad66-8c0ee529c6bd
        hippo:availability: [live]
        hippostd:holder: admin
        hippostd:state: published
        hippostdpubwf:createdBy: admin
        hippostdpubwf:creationDate: 2014-03-25T16:52:00+01:00
        hippostdpubwf:lastModificationDate: 2014-03-25T16:52:00+01:00
        hippostdpubwf:lastModifiedBy: admin
        hippostdpubwf:publicationDate: 2014-03-25T16:52:00+01:00
        hippotranslation:id: ce342189-ee92-494e-8589-33d219e7cefb
        hippotranslation:locale: en
        myproject:introduction: Lorem Ipsum is simply dummy text of the printing
          and typesetting industry.
        myproject:publicationdate: 2014-03-25T16:52:00+01:00
        myproject:title: Lorem
      /sample-document[2]:
        jcr:primaryType: myproject:contentdocument
        jcr:mixinTypes: ['mix:referenceable', 'mix:versionable']
        jcr:uuid: 6ac38741-5b11-4171-b7d6-736a200cf69f
        hippo:availability: [preview]
        hippostd:state: unpublished
        hippostdpubwf:createdBy: admin
        hippostdpubwf:creationDate: 2014-03-25T16:52:00+01:00
        hippostdpubwf:lastModificationDate: 2017-12-11T10:17:08.907-08:00
        hippostdpubwf:lastModifiedBy: admin
        hippotranslation:id: ce342189-ee92-494e-8589-33d219e7cefb
        hippotranslation:locale: en
        myproject:introduction: Lorem Ipsum is simply dummy text of the printing
          and typesetting industry.
        myproject:publicationdate: 2014-03-25T16:52:00+01:00
        myproject:title: Lorem Ipsum
      /sample-document[3]:
        jcr:primaryType: myproject:contentdocument
        jcr:mixinTypes: ['mix:referenceable']
        jcr:uuid: 887f4761-56f7-41e7-a259-c3f58e8b2995
        hippo:availability: []
        hippostd:state: draft
        hippostdpubwf:createdBy: admin
        hippostdpubwf:creationDate: 2014-03-25T16:52:00+01:00
        hippostdpubwf:lastModificationDate: 2017-12-11T10:17:04.754-08:00
        hippostdpubwf:lastModifiedBy: admin
        hippotranslation:id: ce342189-ee92-494e-8589-33d219e7cefb
        hippotranslation:locale: en
        myproject:introduction: Lorem Ipsum is simply dummy text of the printing
          and typesetting industry.
        myproject:publicationdate: 2014-03-25T16:52:00+01:00
        myproject:title: Lorem Ipsum

This structure describes two folders ('myproject' and 'content') with one document ('sample-document'). As you can see, all nodes are mix:referenceable, with the 'unpublished variant' being mix:versionable.

Document Workflow

The default workflow for publishable documents is the 'document workflow'. Besides operations like 'copy', 'move', 'rename' and 'delete', it defines all operations for editing, publication, workflow requests and scheduling, versioning and unlocking, tied to the hippo:handle (parent) node of publishable documents.

Editing workflow operations

The editing workflow operations takes care of 'locking' the document when a user presses 'edit' in the CMS. (or obtains an editable instance via the workflow API) The hippostd:holder property on the draft variant contains the user id of the user who is editing the document. If this property is absent, the document is not being edited. Document content is copied from the unpublished to the draft when editing commences. It is copied in the reverse direction when the changes are committed.

A separate workflow operation, unlock, enables adminstrators to remove the lock from a document.

Publication workflow operations

These workflow operations make use of three main states for a document to be in:

• new
  the document is available for preview, but is not live. This is the state a document enters when first created, or when taken offline.
• live
  the document is published and has not been modified since publication.
• changed
  the document is published, but has been modified since publication

This state is stored in the hippostd:stateSummary property (see above). Operations like 'publish', 'take offline', 'edit' and 'commit' take the document through these states.

Requested and scheduled publication workflow operations

Apart from the main states (new, live & changed), there are a number of states that deal with requests for (de)publication. These requests take two different forms:

• author request
  an author requested a (de)publication of a document, an action that needs to be reviewed by an editor.
• scheduled job
  a job was scheduled to (de)publish a document at a particular time in the future.

The requests are persisted as separate nodes beneath the handle. Their presence can block some actions. It is e.g. not possible to edit a document with a pending request for publication present. Similarly, it is not possible to request or schedule an action when another request is already present.

Variants

There are three document variants supported in the workflow:

• published
  this variant has hippo:availability='live' when the document has been published
• unpublished
  this is the versionable variant and the central point through which all content changes flow.
• draft
  this variant contains intermediate changes by editors.

When a user starts editing a document, the contents are copied from the unpublished variant to the draft. Likewise, when committing an editable instance, contents are copied back from draft to unpublished variants. To make it possible to track content changes over time, a version is created from the unpublished variant when a document is published.

Versions

The unpublished variant is versionable, with versions being created when the document is published or taken offline. The version history is a linear history of changes that were made to the document. The version history is a regular JCR version history.

Availability

The hippo:availability property is used to expose the right variant in the right context on the delivery tier, the HST. This happens by means of authorisation rules. The 'published' variant is shown on the 'live' site by virtue of its hippo:availability value 'live'. Using the same mechanism, the 'unpublished' variant is shown on the 'preview' site.

Roles

Three roles exist in the document workflow. The author can edit documents and request (de)publication. The editor can (de)publish changes, schedule them, and accept/deny requests by authors. Finally, the administrator can unlock documents; i.e. it becomes available for editing, when it was locked before by an author or editor.

Visual representation of the document workflow

The graph below shows the states and the allowed transitions. Requests and jobs have been overlayed, as the difference can be considered an attribute of the state.

Version History

The version history of the 'unpublished' is extended with a new version when a document is published or taken offline. (The latter in order to be able to restore changes that were made since publication)

Here is the history of the document shown above, after being published twice:

/6ac38741-5b11-4171-b7d6-736a200cf69f:
  jcr:primaryType: nt:versionHistory
  jcr:uuid: 3a424913-0e79-4594-85a8-d75562c0f1dd
  /jcr:versionLabels:
    jcr:primaryType: nt:versionLabels
  /jcr:rootVersion:
    jcr:primaryType: nt:version
    jcr:uuid: 6b951a93-dd0b-4541-8f1b-e56a51d6d473
    /jcr:frozenNode:
      jcr:primaryType: nt:frozenNode
      jcr:uuid: a3da280c-0b11-42c0-9e0d-82582ed7fab8
  /1.0:
    jcr:primaryType: nt:version
    jcr:uuid: 9a60062c-352c-493c-bb80-5b71b553c73d
    /jcr:frozenNode:
      jcr:primaryType: nt:frozenNode
      jcr:uuid: 1c6b616c-faf5-4ceb-85c8-3d2278202132
      jcr:frozenPrimaryType: myproject:contentdocument
      jcr:frozenMixinTypes: ['mix:referenceable']
      jcr:frozenUuid: 570182a8-2b85-48c9-ad66-8c0ee529c6bd
      hippostd:state: published
      hippostdpubwf:createdBy: admin
      hippostdpubwf:creationDate: 2014-03-25T16:52:00+01:00
      hippostdpubwf:lastModificationDate: 2014-03-25T16:52:00+01:00
      hippostdpubwf:lastModifiedBy: admin
      hippostdpubwf:publicationDate: 2014-03-25T16:52:00+01:00
      hippotranslation:id: ce342189-ee92-494e-8589-33d219e7cefb
      hippotranslation:locale: en
      myproject:introduction: Lorem Ipsum is simply dummy text of the printing
        and typesetting industry.
      myproject:publicationdate: 2014-03-25T16:52:00+01:00
      myproject:title: Lorem
  /1.1:
    jcr:primaryType: nt:version
    jcr:uuid: 7fdfdb79-1a3e-4a93-9ac3-3efe86f556a8
    /jcr:frozenNode:
      jcr:primaryType: nt:frozenNode
      jcr:uuid: ad3d2bd8-f519-411c-9aae-8ba8a80c6981
      jcr:frozenPrimaryType: myproject:contentdocument
      jcr:frozenMixinTypes: ['mix:referenceable', 'mix:versionable']
      jcr:frozenUuid: 6ac38741-5b11-4171-b7d6-736a200cf69f
      hippostd:state: unpublished
      hippostdpubwf:createdBy: admin
      hippostdpubwf:creationDate: 2014-03-25T16:52:00+01:00
      hippostdpubwf:lastModificationDate: 2017-12-11T10:17:08.907-08:00
      hippostdpubwf:lastModifiedBy: admin
      hippotranslation:id: ce342189-ee92-494e-8589-33d219e7cefb
      hippotranslation:locale: en
      myproject:introduction: Lorem Ipsum is simply dummy text of the printing
        and typesetting industry.
      myproject:publicationdate: 2014-03-25T16:52:00+01:00
      myproject:title: Lorem Ipsum

This version history can be found by dereferencing the jcr:versionHistory property of the 'unpublished' variant.

Since the version history grows on every publication action, it may get quite big. Using an updater script, the history can be trimmed.