Skip to content

Commit

Permalink
Merge pull request #2606 from GetDKAN/stefaniefgray-docs3
Browse files Browse the repository at this point in the history 
Final Workflow content improvements
  • Loading branch information
Ero authored Jul 31, 2018
2 parents 258baf3 + ceefdea commit 0ffb0db
Showing 1 changed file with 61 additions and 56 deletions.
117 changes: 61 additions & 56 deletions docs/components/workflow.rst
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,46 @@
DKAN Workflow
=============

For large organizations, it can be difficult to moderate vast amounts of content submitted by a wide range of publishers and agencies. It is important to be able to manage which users are able to add, edit and delete content, as well as which users can view and approve of content under review.
Introduction
------
For large organizations, it can be difficult to moderate vast amounts of content submitted by a wide range of publishers and agencies.

DKAN Workflow is an optional module for `DKAN
<https://github.com/GetDKAN/dkan>`_ based on the `Workbench
<https://www.drupal.org/project/workbench>`_ family of modules.

With Workflow, site managers and administrators can determine which users are able to add, edit and delete content, as well as which users can view and approve of content under review.

Workflow creates a moderation queue so that content is published to the live site only after a designated supervisor or group moderator has reviewed and approved it.

*With Workflow, content exists in three states:*
**When using DKAN Workflow, content exists in three states:**

* _Draft_ - A saved work in progress.
* _Needs_ _Review_ - The author feels the content is ready to go on public on the live site, and would like the supervisor to review it.
* _Published_ - The content is public and visible on the live site.
* **Draft** - A saved work in progress.
* **Needs Review** - The author feels the content is ready to go on public on the live site, and would like the supervisor to review it.
* **Published** - The content is public and visible on the live site.

.. figure:: ../images/workflow/dkan_workflow_screenshot.png

_What you see on My Workbench after login. The Workbench navigation bar contains your content, drafts, and more. The "Create Content" menu features a list of content types you can create.
The above image displays what you see on My Workbench after login. The Workbench navigation bar contains your content, drafts, and more. The "Create Content" menu features a list of content types you can create.

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

Requirements for DKAN Workflow
------------------------------
DKAN Workflow is included on all out-of-the-box DKAN sites; however, it is not enabled by default. It can be enabled either from the Modules management page or by using drush.

.. code-block:: bash
drush en dkan_workflow -y
Enabling DKAN workflow will automatically enable all other required modules and add the Workflow Supervisor role to all users already assigned the site manager role. (More information available in the `Workflow Roles`_
section).

You may also see a message instructing you to rebuild permissions. If so, click the "Rebuild permissions" link to update the node access settings.

.. image:: ../images/rebuild-permissions-message.png

Requirements for DKAN Workflow
--------------------------------
The DKAN Workflow component as a whole is comprised of three modules:

* DKAN Workflow
Expand All @@ -46,25 +64,9 @@ Finally, the following Drupal contrib modules provide extra functionality (Menu
All of the aforementioned dependencies are declared in the `drupal-org.make
<https://github.com/GetDKAN/dkan/blob/7.x-1.x/drupal-org.make>`_ file.

Installation
------------
DKAN workflow is included on all out-of-the-box DKAN sites; however, it is not enabled by default. It can be enabled either from the Modules management page or by using drush.

.. code-block:: bash
drush en dkan_workflow -y
Enabling DKAN workflow will enable all of the necessary dependencies modules and update site
user roles (more information available in the `Workflow Roles`_
section).

You may also see a message instructing you to rebuild permissions. If so, click the "Rebuild permissions" link to update the node access settings.

.. image:: ../images/rebuild-permissions-message.png


My Workbench
------------
============

When logged in as a user that has been assigned a Workbench role, the "My Workbench" button will be displayed on the site's main navigation toolbar.

Expand All @@ -73,27 +75,29 @@ When logged in as a user that has been assigned a Workbench role, the "My Workbe
.. image:: ../images/workflow/dkan_workflow_main_interface.png

The My Workbench Moderation Toolbar
++++++++++++++++++++++++++++
------------------------------------

:My content: This tab provides a list of all of the content you've created.
:My content: This tab provides a list of all of the content you've created.

:My drafts: Drafts you’ve written and drafts you have permission to view.
:My drafts: Drafts you’ve written and drafts you have permission to view.

:Needs review: Content that Needs Review and can either be published to the live site or sent back to Drafts.
:Needs review: Content that Needs Review and can either be published to the live site or sent back to Drafts.

:Stale drafts: This tab contains Drafts that have sat for over 72 hours without a change in moderation state. (The "stale drafts" moderation state, as well as "stale reviews," are only visible to Site Managers.)
:Stale drafts: This tab contains Drafts that have sat for over 72 hours without a change in moderation state. (The "stale drafts" moderation state, as well as "stale reviews," are only visible to Site Managers.)

:Stale reviews: This tab provides content filed under Needs Review that has sat for over 72 hours without a change in moderation state.
:Stale reviews: This tab provides content filed under Needs Review that has sat for over 72 hours without a change in moderation state.

Additional features:
---------------------

**Content Filters**. Users can filter through content by *Title*,
*Type* (Dataset, Resource, Data Story, etc), and *Groups*.
**Content Filters:**
Users can filter through content by *Title*, *Type* (Dataset, Resource, Data Story, etc), and *Groups*.

**Bulk updates**. Certain operations such as changing content from Needs Review back to Draft can be applied to multiple items at once.
**Bulk updates:**.
Certain operations such as changing content from Needs Review back to Draft can be applied to multiple items at once.

Node Edit Page
++++++++++++++++++++++++++++
Editing Content
----------------

If you'd like to change the moderation state of an individual node (such as a dataset or
resource), you can do so while editing the node itself.
Expand All @@ -113,34 +117,34 @@ Workflow Roles

The three Workflow roles correspond with the three core DKAN `roles and permissions <http://dkan.readthedocs.io/en/latest/components/permissions.html>`_ If a user is given a Workflow role, they must also be granted the corresponding core DKAN role.

* *Workflow Contributor = Content Creator*
* **Workflow Contributor = Content Creator**

Workflow Contributor is the most basic role; users with this role can add content, save as Draft or move it to Needs Review, but cannot publish content directly to the live site. They can only view content that they've created, and cannot modify the content of others.

* *Workflow Moderator = Editor*
* **Workflow Moderator = Editor**

Workflow Moderator is the middle role, mostly pertaining to moderating specific groups. This role reviews and publishes (or unpublishes) content for their group(s), rather than for the entire site. Workflow Moderators can also view and approve of content that has not yet been assigned to a group.

* *Workflow Supervisor = Site Manager*
* **Workflow Supervisor = Site Manager**

Workflow Supervisor is the most powerful role and should only be assigned to highly trusted users. Users with the role of Workbench Supervisor can add, edit, modify, publish, unpublish, moderate or delete _all_ site content. This role is the only role that have access to the "Stale Drafts" and "Stale Review" tabs (more information below).

.. figure:: ../images/workflow/dkan_workflow_autorole.gif
:scale: 75

Automatic core role assignment with workflow roles.
Here is how core roles in DKAN are automatically correlated to Workbench roles and permissions:

+-------------------------+-------------------------------------+---------------------------------------------+
| What a user will see | "My Drafts" | "Needs Review" |
+=========================+=====================================+=============================================+
| Workflow Contributor | - Only content that they submitted. | - Can see only content they have submitted. |
| Workflow Contributor | Only content that they submitted. | Can see only content they have submitted. |
+-------------------------+-------------------------------------+---------------------------------------------+
| Workflow Moderator | - The content submitted to their | - The content submitted to their organic |
| Workflow Moderator | The content submitted to their | The content submitted to their organic |
| | organic group. | group. |
| | - Their own content. | - Their own content. |
| | Their own content. | Their own content. |
+-------------------------+-------------------------------------+---------------------------------------------+
| Workflow Supervisor | - Only content that they submitted. | - All the "Needs review" content. |
| Workflow Supervisor | Only content that they submitted. | All the "Needs review" content. |
+-------------------------+-------------------------------------+---------------------------------------------+

Notification Emails
~~~~~~~~~~~~~~~
Changing Notification Email Settings
-------------------------------------

For each DKAN Workflow moderation state transition (for example from *Draft* to *Needs Review*, from
*Needs Review* to *Draft*, etc) the users with corresponding Workflow roles will receive a notification via email.
Expand All @@ -154,21 +158,22 @@ There are three scenarios in which one will receive email pertaining to DKAN Wor
Emails will display the context that had triggered the notification as well as links to the
updated content.

Extending DKAN Workflow
-----------------------
Advanced Options
==============================================

Tweaking the Email template
+++++++++++++++++++++++++++
---------------------------
To change DKAN Workflow moderation email templates, go to the *admin/config/workbench/email* configuration page. For more
in-depth documentation, please review the `Workbench Modules Docs`_.

Workbench Modules Docs
++++++++++++++++++++++
-----------------------

For more information, please refer to the following documentation:

* `Workbench documentation in drupal.org
* `Workbench documentation on Drupal.org
<https://www.drupal.org/documentation/modules/workbench>`_.
* `Workbench Moderation documentation in drupal.org
* `Workbench Moderation documentation on Drupal.org
<https://www.drupal.org/documentation/modules/workbench_moderation>`_.
* `Workbench Email documentation in drupal.org
* `Workbench email documentation on Drupal.org
<https://www.drupal.org/node/2253081>`_.

0 comments on commit 0ffb0db

Please sign in to comment.