Now that we know how to set up our tables and classes, we can explain how to transition objects through a workflow.
Creating an object is not different from plain SQLAlchemy:
somejar = Jar(12, u"A big jar")
session.add(somejar)
You need to create the ORM-mapped object and add it to a session. Note we have supplied it with a code, 12.
At this point, the status of the version will be clio.NEW and the code will be 12.
We can publish a version of an object by calling its publish method:
somejar.publish()
The workflow status of the version will now be clio.PUBLISHED.
The code will still be 12 and will remain so for each version of this object.
Once an object is published we shouldn’t change it again directly. Instead, we should create an editable version for it:
editable_jar = somejar.edit()
somejar still refers to the original published version. editable_jar refers to a new version with the same value for code and the status clio.EDITABLE.
You can now edit attributes on the editable object:
editable_jar.name = u"A big cookie jar"
If the object has one-to-many relations and thus other objects associated with it, these objects will be automatically copied as well when an editable version of the object is created. Upon publication, these associated objects are also published.
Updating is very similar to editing, but will not copy any versions associated with a one-to-many relation. This is to support the scenario where doing so would create the copying of a tremendous amount of objects in the database. The updatable version behaves as if its relations are those of the published version instead.
Otherwise, the behavior is the same as for editing. When publishing an updatable versions, the objects associated with the previously published version will now become associated with the newly published version.
The status of an updatable version is clio.UPDATABLE.
You can re-publish an edited or updated version:
newly_published_jar = editable_jar.publish()
The previously published version (somejar) will be put into an archived state automatically. You can verify this by calling the is_archived method on it:
somejar.is_archived()
The version referred to by newly_published_jar is now the published version (and in fact editable_jar still refers to it too).
After a version is archived, it should not be changed anymore - it merely exists as a record.
There is no single archived status, as multiple archived versions of an object can exist in parallel to each other. The status of an archived version is greater than or equal to clio.ARCHIVED.
An published version can be submitted for deletion. The version remains published, but when publish is called on it, it will be automatically archived (along with everything associated with it in a one-to-many relation):
deleted_jar = somejar.delete()
deleted_jar still refers to the same version as somejar does.
It is possible to revert an editing, update or delete operation back to its published version. This can be done by calling revert:
jar = editable_jar.revert()
A deleted version will be removed. An editable or updatable version will be replaced by a version based on the currently published version. A deleted editable/updatable version will be turned back into a plain editable/updatable version.