ftw.lawgiver

HomePage: https://github.com/4teamwork/ftw.lawgiver

Author: 4teamwork GmbH

Download: https://pypi.python.org/packages/source/f/ftw.lawgiver/ftw.lawgiver-1.2.2.zip

        ftw.lawgiver
============

``ftw.lawgiver`` generates Plone workflows based on a human readable
specification written in a custom
`DSL <http://en.wikipedia.org/wiki/Domain-specific_language>`_.

.. contents:: Table of Contents


Motivation
----------

Developing and maintaining complex Plone workflows is a time-consuming and
cumbersome endeavor. Dozens of permissions need to be managed for different
roles and different workflow states. Usually, this has to be done directly in
the ZMI of Zope by selecting or unselecting thousands of checkboxes. This
process has been shown to be very tedious and prone to errors. Furthermore, it
is no simple task to document the workflow and the associated design decisions
which led to the resulting configuration of permissions and roles. The extension
or adaption of an existing workflow becomes very difficult, leading to workflows
which are barely maintainable.

Another problem poses the communication between workflow integrator and
customer. The security system of Zope is based on a role-based access control
(RBAC) which is intrinsically complex due to its use of roles, permissions, and
workflow states. Experience has shown that these security concepts can be hard
to convey to customers.


How it works
------------

``ftw.lawgiver`` helps solving these problems by using a DSL to describe how
a workflow should work. The lawgiver then generates the complete workflow
definition (``definition.xml``) based on this specification.  By separating this
specification from the resulting workflow definition (which is in XML) the
specification does not have to use permissions--handling the permissions is the
job of the lawgiver.

Using the specification file the workflow can easily be regenerated at any time
and will handle additional permissions automatically when regenerated. However,
it is still the task of the developer to regenerate the ``definition.xml`` when
more or other permissions have to be managed. He or she have to make sure that
the workflow is properly installed with an upgrade step / reindexing security.


Installation
------------

- Add ``ftw.lawgiver`` to your buildout configuration:

.. code:: rst

    [instance]
    eggs +=
        ftw.lawgiver

- Install the generic setup profile of ``ftw.lawgiver``.


Compatibility
-------------

Plone 4.3

.. image:: https://jenkins.4teamwork.ch/job/ftw.lawgiver-master-test-plone-4.3.x.cfg/badge/icon
   :target: https://jenkins.4teamwork.ch/job/ftw.lawgiver-master-test-plone-4.3.x.cfg


Action groups
-------------

In the specification we use the concept of so called action groups for
describing what a role is allowed to do. It basically groups together a bunch of
semantically similar Plone / Zope permissions so that we only have to define the
workflow based on these action groups and not on individual permissions.

For example there is an ``Access`` action group which contains permissions such
as ``View`` and ``Access Contents Information``.


Registering permissions to an action group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The registration of a permission to an action group should be done in the
package where the permission is defined.  This allows to keep changes of the
permissions and action group registrations together in branches, for reviews
etc. ``ftw.lawgiver`` already assigns default Plone / Zope permissions to action
groups.

The registration is done in ZCML.
Here is an example ``lawgiver.zcml``:

.. code:: xml

    <configure
        xmlns="http://namespaces.zope.org/zope"
        xmlns:lawgiver="http://namespaces.zope.org/lawgiver"
        i18n_domain="my.package">

        <include package="ftw.lawgiver" file="meta.zcml" />

        <lawgiver:map_permissions
            action_group="add content"
            permissions="my.package: Add Foo,
                         my.package: Add Bar"
            />

    </configure>

If you define multiple permissions in the same `map_permissions` directive
make sure to separate them by comma.

By putting the ZCML in a separate ``lawgiver.zcml`` file you can define
lawgiver in your addon p