ckanext-approvalworkflow

This CKAN extension adds a structured dataset approval workflow to CKAN instances that require moderation before datasets become publicly visible. It enhances governance, quality control, and transparency by introducing a controlled review process and providing administrators with clear oversight of dataset publication activities.

The extension is designed to integrate seamlessly with CKAN’s core functionality while adding essential moderation features such as notifications, approval logging, and a dedicated approval stream.

This extension provides three configuration modes for managing the dataset approval workflow:

• Not Active – The approval workflow is disabled and datasets are published immediately.
• Active – The approval workflow is enabled globally for all organizations.
• Activate Approval Workflow per Organization – The workflow can be selectively enabled or disabled at the organization level.

---

Dataset Approval Flow

When a user submits a new dataset, users who are not admin or sysadmin are not permitted to set the dataset visibility to public. If a non-admin user attempts to publish a dataset, the extension automatically reverts the visibility to private and displays a notification indicating that the dataset has not yet been approved.

1. Request Approval

A request for approval may be initiated by any user with modify permissions on the dataset by clicking the Request Review button. Upon submission of the approval request, an email notification is sent to all administrators of the corresponding organization.

---

2. Approval Form

Admins and sysadmins can approve or reject the dataset and optionally include notes.

---

3. Approval Stream Logging

Every approval or rejection event is tracked in the Approval Stream, similar to CKAN’s Activity Stream.

---

Workflow Summary

1. Notification is sent — All administrators of the relevant CKAN organization receive an email containing a direct link to the dataset awaiting review.

2. Review actions — Organization administrators or system administrators can either approve or reject the dataset.

3. Publication control —

   • Approved datasets move to a public state.
   • Rejected datasets are private.

4. Approval Stream logging — Every action is recorded with:

   • The user who performed the action
   • Timestamps for each workflow event
   • Optional review notes

This approval flow ensures that dataset publishing follows a consistent, auditable process and gives organizations full control over what becomes publicly accessible.

---

Datasets that are pending approval or have been rejected can be searched using the same interface and page as standard dataset searches. Use the Order By dropdown menu and select the appropriate approval status (Pending or Rejected).

---

Important Notes

Note:
Any update made to a dataset by a non-admin user will automatically place the dataset back into the private state.
Dataset creations and updates performed by organization administrators or sysadmins are not subject to the approval workflow.

Requirements

Make sure to have email settings in your ckan.ini file.

Compatibility with core CKAN versions:

CKAN version	Compatible?
2.9	Yes
2.10	Yes
2.11	Yes

For CKAN 2.9 use the 0.0.1 tag

Installation

To install ckanext-approvalworkflow:

1. Activate your CKAN virtual environment, for example:

   . /usr/lib/ckan/default/bin/activate

2. Clone the source and install it on the virtualenv

   git clone https://github.com//ckanext-approvalworkflow.git

   cd ckanext-approvalworkflow

   pip install -e .

   pip install -r requirements.txt

3. Add approvalworkflow to the ckan.plugins setting in your CKAN config file (by default the config file is located at /etc/ckan/default/ckan.ini).

4. Create the database tables running:

   ckan -c /path/to/ini/file approval_workflow initdb

5. ckanext-approvalworkflow is designed to work together with ckanext-scheming.
   When the scheming extension is enabled, you must explicitly add the approval state field to your dataset schema configuration.

   - field_name: approval_state
     label: Approval Status
     form_snippet: null
     display_snippet: null
     validators: approval_state_value ignore_missing

6. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu:

   sudo service apache2 reload

Config settings

If your CKAN instance uses additional dataset types defined through ckanext-scheming, beyond the default dataset type, ensure that these custom types are explicitly listed in the configuration. For example:

ckanext.approvalworkflow.dataset_types = report, camel-photos, whitepaper

To enable the dataset approval stream exclusively for authenticated users and hide it from the public, set the following configuration option to false. The default value is true.

ckanext.approvalworkflow.show_stream = false

Developer installation

To install ckanext-approvalworkflow for development, activate your CKAN virtualenv and do:

git clone https://github.com//ckanext-approvalworkflow.git
cd ckanext-approvalworkflow
python setup.py develop
pip install -r dev-requirements.txt

Tests

To run the tests, do:

pytest --ckan-ini=test.ini

Releasing a new version of ckanext-approvalworkflow

If ckanext-approvalworkflow should be available on PyPI you can follow these steps to publish a new version:

1. Update the version number in the setup.py file. See PEP 440 for how to choose version numbers.

2. Make sure you have the latest version of necessary packages:

   pip install --upgrade setuptools wheel twine

3. Create a source and binary distributions of the new version:

   python setup.py sdist bdist_wheel && twine check dist/*
   

   Fix any errors you get.

4. Upload the source distribution to PyPI:

   twine upload dist/*
   

5. Commit any outstanding changes:

   git commit -a
   git push
   

6. Tag the new release of the project on GitHub with the version number from the setup.py file. For example if the version number in setup.py is 0.0.1 then do:

   git tag 0.0.1
   git push --tags
   

License

AGPL