ftw.lawgiver 1.0

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:

<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 package without having to define a dependency to ftw.lawgiver by using zcml:condition while loading it in your default configure.zcml:

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

    <include zcml:condition="installed ftw.lawgiver" file="lawgiver.zcml" />

</configure>

Overriding action groups

Maybe the permission to action group mapping does not work well for a specific workflow and you would like to change to mapping for this workflow only.

This can be easily achieved by also defining the workflow in the ZCML:

<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"
        workflow="my_workflow"
        />

</configure>

States and transitions

The states and transitions are defined in simple lists:

[My Custom Workflow]
Description: A three state publication workflow
Initial Status: Private

Status Private:

Status Pending:

Status Published:

Transitions:
  Publish (Private => Published)
  Submit for publication (Private => Pending)
  Reject (Pending => Private)
  Retract (Pending => Private)
  Publish (Pending => Published)
  Reject (Published => Private)

The asterisk (*) in the state list indicates that this state is the initial state. We are not using any internal ids for workflow states or transitions. Instead, we use the same labels which the user will actually see–the ids are automatically generated by ftw.lawgiver.

Role mapping

In Plone we have a given set of rather technical roles (e.g. Editor, Contributor, Reader) which may not apply for all use cases in real life. The customer may have own roles with different names. Since the existing roles are already well established in Plone it is usually not a good thing to add new roles to Plone. It is better to try to reuse the existing roles.

Because the customer has different labels for his roles we need to map customer roles to Plone roles:

Role mapping:
  editor-in-chief => Reviewer
  editor => Editor
  everyone => Anonymous

In our example we have only “normal” editors and an “editor-in-chief” who can review and publish the contents. We do not have to use the Contributor role since our editors can edit, add new content, and request a review for existing content. Therefore, it is not necessary to distinguish Editor and Contributor role.

General statements

Usually there are some general statements, for example that a user with adminstrator role can always edit the contents on any workflow state. Such statements should not be repeated for every state but defined once as a general statement.

An example:

General:
  An administrator can always view the content
  An administrator can always edit the content
  An administrator can always delete the content

These general statements apply for all states.

Describing states

For each state we describe the actions a user with a certain role can do. We have the principle that any user / role is NOT allowed do anything by default, we have to explicitly list every action he will be allowed to perform.

Status Private:
  An editor can view this content.
  An editor can edit this content.
  An editor can delete this content.
  An editor can add new content.
  An editor can submit for publication.
  An editor-in-chief can view this content.
  An editor-in-chief can edit this content.
  An editor-in-chief can delete this content.
  An editor-in-chief can add new content.
  An editor-in-chief can publish this content.

Status Pending:
  An editor can view this content.
  An editor can add new content.
  An editor can retract this content.
  An editor-in-chief can view this content.
  An editor-in-chief can edit this content.
  An editor-in-chief can delete this content.
  An editor-in-chief can add new content.
  An editor-in-chief can publish this content.
  An editor-in-chief can reject this content.

Status Published:
  An editor can view this content.
  An editor can add new content.
  An editor can retract this content.
  An editor-in-chief can view this content.
  An editor-in-chief can add new content.
  An editor-in-chief can retract this content.
  Anyone can view this content.

Role inheritance

Roles can be inherited from other roles, globally and for a single status:

[Role Inheritance Workflow]
Initial Status: Foo

Role mapping:
  editor => Editor
  editor-in-chief => Reviewer
  administrator => Site Administrator

General:
  An administrator can always perform the same actions as an editor.
  An administrator can always perform the same actions as an editor-in-chief.

Status Foo:
  An editor-in-chief can perform the same actions as an editor.
  An editor can view this content.
  An editor can edit this content.

Status Bar:
  An editor can view this content.
  An editor-in-chief can view this content.
  An editor-in-chief can edit this content.

Worklists

Worklists are automatically generated for you when you grant access to the worklist:

[A workflow]
...

Status Pending:
  An editor-in-chief can access the worklist.

Those “can access the worklist” statements do not work in the “General” section, they need to be defined a “Status” section.

For each status with “can access the worklist” statements a worklist is generated, guarded with the role for which there is a statement.

Workflow specification discovery

All workflow directories in registered generic setup profiles are automatically scanned for workflow specifications. Just place a specification.txt in a workflow directory and ftw.lawgiver will discover it automatically.

Example paths:

• Specification: profiles/default/workflows/my_custom_workflow/specification.txt

• Workflow XML: profiles/default/workflows/my_custom_workflow/definition.txt

In this example it is assumed that profiles/default is a registered generic setup profile directory.

Changing Transition URLs

Sometimes the transition URLs need to point to another view. This can be achieved by using the transition-url option, where a string can be passed which will then be substituted with the transition id. Be sure to use a double %% for parts which should not be replaced when generating the workflow, such as the %%(content_url)s.

Example:

transition-url = %%(content_url)s/custom_wf_action?workflow_action=%(transition)s