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).