Document Meta data and versions
- December 1, 2014
- Alan Moore
In a previous post we talked about Rapture Document repositories and mentioned briefly the idea that documents had attached “metadata”. This post talks about that metadata and also a related feature – document versioning.
All documents in repositories can have additional information stored with them. Some of this information is generated automatically by Rapture but a user can use the Rapture API to add their own custom meta data associated with the document. When retrieving data from Rapture you can ask for just the document contents, just the meta data or both.
The automatic system meta data generated contains the following information:
- The user name associated with the api context that saved the document
- The date and time the document was saved (in UTC)
- The current version of the document – even if the repository does not store previous versions a understanding of how many times the document was saved can give an indication of the “version”.
There are a number of API calls that directly manipulate or retrieve meta data. They are all in the “doc” api section:
DocumentWithMeta getMetaContent(String docURI); DocumentMetadata getMetaData(String docURI);
Custom meta data is also known as “attributes”. The following api calls manage attributes:
Boolean addDocumentAttribute(String attributeURI, String value); List<Object> addDocumentAttributes(String attributeURI, List<String> keys, List<String> values); XferDocumentAttribute getDocumentAttribute(String attributeURI); List(XferDocumentAttribute) getDocumentAttributes(String attributeURI); Boolean removeDocumentAttribute(String attributeURI);
It is worth talking about the “attribute URI” parameter in the above calls. Within Rapture, attributes on documents use the “bookmark” uri convention to define the attribute. So, given a document called:
Setting an attribute “a1” to the value “42” would be a call similar to the one below (given in Reflex)
Retrieval of a single attribute follows the same convention.
A versioned document repository is one where previous versions of documents can be retained and retrieved at a later date. As you add new documents to a repository any existing documents are preserved in this version history. An api call can be used to trim out old versions from a repository.
Internally a document repository maintains a concept of “the current version”. This is the version that is retrieved if you pass in an unadorned URI to an api call (e.g. //idp.data/test/one above). Using a getMetaData call you can retrieve the version of that latest document and then use a slightly adjusted URI to retrieve previous versions. The script below illustrates this concept:
docMeta = #doc.getMetaContent(“//idp.data/test/one”); version = docMeta.metaData.version; previous = version - 1; previousDocument <— (“//idp.data/test/one@“ + previous);
You could loop back until you get to version 1 (the first document created) although depending on archiving status earlier versions may already have been expunged from the system.
There are a couple of API calls that rely on version information:
DocumentWithMeta revertDocument(String docURI); Boolean archiveVersions(String repoURI, int versionLimit, long timeLimit, Boolean ensureVersionLimit); Boolean putContentWithVersion(String docURI, String content, int currentVersion);
Revert document takes the previous version of a document and makes that the latest version of a document (making the existing “latest version” the previous version)
Archive versions removes old versions of documents given limits on how many versions or time should be preserved (e.g. keep all versions written in the last month, make sure that you keep at least ten versions).
Put content with version attempts to save a new document over an existing one. It assumes that the code saving the document has previously loaded the document and therefore has knowledge of the version of the document it has loaded. If that version does not match the call will fail. This is a form of “optimistic locking” – the assumption is that no-one else should be modifying this document but if someone does the call will fail and will have to be retried (reloaded and re-edited perhaps). Rapture also has a locking system for more formal procedures around modification of data.
This short post gave a quick overview of additional information that can be stored with a document (meta data and attributes) and for some repositories how versioning can be used to maintain a complete history of the changes to a document over time.
As before – if you’d like more information about Incapture or Rapture please drop me a line personally or to our general email address firstname.lastname@example.org and we will get back to you for a more in depth discussion.