+
−Undoing changes in CubicWeb
+
−---------------------------
+
−
+
−Many desktop applications offer the possibility for the user to
+
−undo its last changes : this *undo feature* has now been
+
−integrated into the CubicWeb framework. This document will
+
−introduce you to the *undo feature* both from the end-user and the
+
−application developer point of view.
+
−
+
−But because a semantic web application and a common desktop
+
−application are not the same thing at all, especially as far as
+
−undoing is concerned, we will first introduce *what* is the *undo
+
−feature* for now.
+
−
+
−What's *undoing* in a CubicWeb application
+
−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
−
+
−What is an *undo feature* is quite intuitive in the context of a
+
−desktop application. But it is a bit subtler in the context of a
+
−Semantic Web application. This section introduces some of the main
+
−differences between a classical desktop and a Semantic Web
+
−applications to keep in mind in order to state precisely *what we
+
−want*.
+
−
+
−The notion transactions
+
−```````````````````````
+
−
+
−A CubicWeb application acts upon an *Entity-Relationship* model,
+
−described by a schema. This allows to ensure some data integrity
+
−properties. It also implies that changes are made by all-or-none
+
−groups called *transactions*, such that the data integrity is
+
−preserved whether the transaction is completely applied *or* none
+
−of it is applied.
+
−
+
−A transaction can thus include more actions than just those
+
−directly required by the main purpose of the user.  For example,
+
−when a user *just* writes a new blog entry, the underlying
+
−*transaction* holds several *actions* as illustrated below :
+
−
+
−* By admin on 2012/02/17 15:18 - Created Blog entry : Torototo
+
−
+
−  #. Created Blog entry : Torototo
+
−  #. Added relation : Torototo owned by admin
+
−  #. Added relation : Torototo blog entry of Undo Blog
+
−  #. Added relation : Torototo in state draft (draft)
+
−  #. Added relation : Torototo created by admin
+
−
+
−Because of the very nature (all-or-none) of the transactions, the
+
−"undoable stuff" are the transactions and not the actions !
+
−
+
−Public and private actions within a transaction
+
−```````````````````````````````````````````````
+
−
+
−Actually, within the *transaction* "Created Blog entry :
+
−Torototo", two of those *actions* are said to be *public* and
+
−the others are said to be *private*. *Public* here means that the
+
−public actions (1 and 3) were directly requested by the end user ;
+
−whereas *private* means that the other actions (2, 4, 5) were
+
−triggered "under the hood" to fulfill various requirements for the
+
−user operation (ensuring integrity, security, ... ).
+
−
+
−And because quite a lot of actions can be triggered by a "simple"
+
−end-user request, most of which the end-user is not (and does not
+
−need or wish to be) aware, only the so-called public actions will
+
−appear [1]_ in the description of the an undoable transaction.
+
−
+
−* By admin on 2012/02/17 15:18 - Created Blog entry : Torototo
+
−
+
−  #. Created Blog entry : Torototo
+
−  #. Added relation : Torototo blog entry of Undo Blog
+
−
+
−But note that both public and private actions will be undone
+
−together when the transaction is undone.
+
−
+
−(In)dependent transactions : the simple case
+
−````````````````````````````````````````````
+
−
+
−A CubicWeb application can be used *simultaneously* by different users
+
−(whereas a single user works on an given office document at a
+
−given time), so that there is not always a single history
+
−time-line in the CubicWeb case. Moreover CubicWeb provides
+
−security through the mechanism of *permissions* granted to each
+
−user. This can lead to some transactions *not* being undoable in
+
−some contexts.
+
−
+
−In the simple case two (unprivileged) users Alice and Bob make
+
−relatively independent changes : then both Alice and Bob can undo
+
−their changes. But in some case there is a clean dependency
+
−between Alice's and Bob's actions or between actions of one of
+
−them. For example let's suppose that :
+
−
+
−- Alice has created a blog,
+
−- then has published a first post inside,
+
−- then Bob has published a second post in the same blog,
+
−- and finally Alice has updated its post contents.
+
−
+
−Then it is clear that Alice can undo her contents changes and Bob
+
−can undo his post creation independently. But Alice can not undo
+
−her post creation while she has not first undone her changes.
+
−It is also clear that Bob should *not* have the
+
−permissions to undo any of Alice's transactions.
+
−
+
−
+
−More complex dependencies between transactions
+
−``````````````````````````````````````````````
+
−
+
−But more surprising things can quickly happen. Going back to the
+
−previous example, Alice *can* undo the creation of the blog after
+
−Bob has published its post in it ! But this is possible only
+
−because the schema does not *require* for a post to be in a
+
−blog. Would the *blog entry of* relation have been mandatory, then
+
−Alice could not have undone the blog creation because it would
+
−have broken integrity constraint for Bob's post.
+
−
+
−When a user attempts to undo a transaction the system will check
+
−whether a later transaction has explicit dependency on the
+
−would-be-undone transaction. In this case the system will not even
+
−attempt the undo operation and inform the user.
+
−
+
−If no such dependency is detected the system will attempt the undo
+
−operation but it can fail, typically because of integrity
+
−constraint violations. In such a case the undo operation is
+
−completely [3]_ rollbacked.
+
−
+
−
+
−The *undo feature* for CubicWeb end-users
+
−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
−
+
−The exposition of the undo feature to the end-user through a Web
+
−interface is still quite basic and will be improved toward a
+
−greater usability. But it is already fully functional.  For now
+
−there are two ways to access the *undo feature* as long as the it
+
−has been activated in the instance configuration file with the
+
−option *undo-support=yes*.
+
−
+
−Immediately after having done the change to be canceled through
+
−the **undo** link in the message. This allows to undo an
+
−hastily action immediately. For example, just after having
+
−validated the creation of the blog entry *A second blog entry* we
+
−get the following message, allowing to undo the creation.
+
−
+
−.. image:: /images/undo_mesage_w600.png
+
−   :width: 600px
+
−   :alt: Screenshot of the undo link in the message
+
−   :align: center
+
−
+
−At any time we can access the **undo-history view** accessible from the
+
−start-up page.
+
−
+
−.. image:: /images/undo_startup-link_w600.png
+
−   :width: 600px
+
−   :alt: Screenshot of the startup menu with access to the history view
+
−   :align: center
+
−
+
−This view will provide inspection of the transaction and their (public)
+
−actions. Each transaction provides its own **undo** link. Only the
+
−transactions the user has permissions to see and undo will be shown.
+
−
+
−.. image:: /images/undo_history-view_w600.png
+
−   :width: 600px
+
−   :alt: Screenshot of the undo history main view
+
−   :align: center
+
−
+
−If the user attempts to undo a transaction which can't be undone or
+
−whose undoing fails, then a message will explain the situation and
+
−no partial undoing will be left behind.
+
−
+
−This is all for the end-user side of the undo mechanism : this is
+
−quite simple indeed ! Now, in the following section, we are going
+
−to introduce the developer side of the undo mechanism.
+
−
+
−The *undo feature* for CubicWeb application developers
+
−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
−
+
−A word of warning : this section is intended for developers,
+
−already having some knowledge of what's under CubicWeb's hood. If
+
−it is not *yet* the case, please refer to CubicWeb documentation
+
−http://docs.cubicweb.org/ .
+
−
+
−Overview
+
−````````
+
−
+
−The core of the undo mechanisms is at work in the *native source*,
+
−beyond the RQL. This does mean that *transactions* and *actions*
+
−are *no entities*. Instead they are represented at the SQL level
+
−and exposed through the *DB-API* supported by the repository
+
−*Connection* objects.
+
−
+
−Once the *undo feature* has been activated in the instance
+
−configuration file with the option *undo-support=yes*, each
+
−mutating operation (cf. [2]_) will be recorded in some special SQL
+
−table along with its associated transaction. Transaction are
+
−identified by a *txuuid* through which the functions of the
+
−*DB-API* handle them.
+
−
+
−On the web side the last commited transaction *txuuid* is
+
−remembered in the request's data to allow for imediate undoing
+
−whereas the *undo-history view* relies upon the *DB-API* to list
+
−the accessible transactions. The actual undoing is performed by
+
−the *UndoController* accessible at URL of the form
+
−`www.my.host/my/instance/undo?txuuid=...`
+
−
+
−The repository side
+
−```````````````````
+
−
+
−Please refer to the file `cubicweb/server/sources/native.py` and
+
−`cubicweb/transaction.py` for the details.
+
−
+
−The undoing information is mainly stored in three SQL tables:
+
−
+
−`transactions`
+
−    Stores the txuuid, the user eid and the date-and-time of
+
−    the transaction. This table is referenced by the two others.
+
−
+
−`tx_entity_actions`
+
−    Stores the undo information for actions on entities.
+
−
+
−`tx_relation_actions`
+
−    Stores the undo information for the actions on relations.
+
−
+
−When the undo support is activated, entries are added to those
+
−tables for each mutating operation on the data repository, and are
+
−deleted on each transaction undoing.
+
−
+
−Those table are accessible through the following methods of the
+
−repository `Connection` object :
+
−
+
−`undoable_transactions`
+
−    Returns a list of `Transaction` objects accessible to the user
+
−    and according to the specified filter(s) if any.
+
−
+
−`tx_info`
+
−    Returns a `Transaction` object from a `txuuid`
+
−
+
−`undo_transaction`
+
−    Returns the list of `Action` object for the given `txuuid`.
+
−
+
−    NB:  By default it only return *public* actions.
+
−
+
−The web side
+
−````````````
+
−
+
−The exposure of the *undo feature* to the end-user through the Web
+
−interface relies on the *DB-API* introduced above. This implies
+
−that the *transactions* and *actions* are not *entities* linked by
+
−*relations* on which the usual views can be applied directly.
+
−
+
−That's why the file `cubicweb/web/views/undohistory.py` defines
+
−some dedicated views to access the undo information :
+
−
+
−`UndoHistoryView`
+
−    This is a *StartupView*, the one accessible from the home
+
−    page of the instance which list all transactions.
+
−
+
−`UndoableTransactionView`
+
−    This view handles the display of a single `Transaction` object.
+
−
+
−`UndoableActionBaseView`
+
−    This (abstract) base class provides private methods to build
+
−    the display of actions whatever their nature.
+
−
+
−`Undoable[Add|Remove|Create|Delete|Update]ActionView`
+
−    Those views all inherit from `UndoableActionBaseView` and
+
−    each handles a specific kind of action.
+
−
+
−`UndoableActionPredicate`
+
−    This predicate is used as a *selector* to pick the appropriate
+
−    view for actions.
+
−
+
−Apart from this main *undo-history view* a `txuuid` is stored in
+
−the request's data `last_undoable_transaction` in order to allow
+
−immediate undoing of a hastily validated operation. This is
+
−handled in `cubicweb/web/application.py` in the `main_publish` and
+
−`add_undo_link_to_msg` methods for the storing and displaying
+
−respectively.
+
−
+
−Once the undo information is accessible, typically through a
+
−`txuuid` in an *undo* URL, the actual undo operation can be
+
−performed by the `UndoController` defined in
+
−`cubicweb/web/views/basecontrollers.py`. This controller basically
+
−extracts the `txuuid` and performs a call to `undo_transaction` and
+
−in case of an undo-specific error, lets the top level publisher
+
−handle it as a validation error.
+
−
+
−
+
−Conclusion
+
−~~~~~~~~~~
+
−
+
−The undo mechanism relies upon a low level recording of the
+
−mutating operation on the repository. Those records are accessible
+
−through some method added to the *DB-API* and exposed to the
+
−end-user either through a whole history view of through an
+
−immediate undoing link in the message box.
+
−
+
−The undo feature is functional but the interface and configuration
+
−options are still quite reduced. One major improvement would be to
+
−be able to filter with a finer grain which transactions or actions
+
−one wants to see in the *undo-history view*. Another critical
+
−improvement would be to enable the undo feature on a part only of
+
−the entity-relationship schema to avoid storing too much useless
+
−data and reduce the underlying overhead.
+
−
+
−But both functionality are related to the strong design choice not
+
−to represent transactions and actions as entities and
+
−relations. This has huge benefits in terms of safety and conceptual
+
−simplicity but prevents from using lots of convenient CubicWeb
+
−features such as *facets* to access undo information.
+
−
+
−Before developing further the undo feature or eventually revising
+
−this design choice, it appears that some return of experience is
+
−strongly needed. So don't hesitate to try the undo feature in your
+
−application and send us some feedback.
+
−
+
−
+
−Notes
+
−~~~~~
+
−
+
−.. [1] The end-user Web interface could be improved to enable
+
−       user to choose whether he wishes to see private actions.
+
−
+
−.. [2] There is only five kind of elementary actions (beyond
+
−       merely accessing data for reading):
+
−
+
−       * **C** : creating an entity
+
−       * **D** : deleting an entity
+
−       * **U** : updating an entity attributes
+
−       * **A** : adding a relation
+
−       * **R** : removing a relation
+
−
+
−.. [3] Meaning none of the actions in the transaction is
+
−       undone. Depending upon the application, it might make sense
+
−       to enable *partial* undo. That is to say undo in which some
+
−       actions could not be undo without preventing to undo the
+
−       others actions in the transaction (as long as it does not
+
−       break schema integrity). This is not forbidden by the
+
−       back-end but is deliberately not supported by the front-end
+
−       (for now at least).