Strapi Plugin Paper Trail

Accountability and content versioning for strapi v4+.

Requirements

1. node v14 or higher
2. strapi v4.10 or higher

Features

• Automatic revision history and auditing with support for all major strapi content types including relations, media, components, and dynamic zones via the admin panel.
• Roll-back capabilities with the option to select specific fields to restore via the admin panel.
• Tracks revision history by both admins and users.
• Internationalization (i18n) plugin support.

Installation

To install this plugin, you need to add an NPM dependency to your Strapi application:

# Using Yarn
yarn add strapi-plugin-paper-trail

# Or using NPM
npm install strapi-plugin-paper-trail --save

Enable the plugin by adding the following in ./config/plugins.js.

1
2
3
4
5
6
7
module.exports = {
  // ...
  'paper-trail': {
    enabled: true
  }
  // ...
};

Or, if you are using TypeScript, in ./config/plugins.ts.

1
2
3
4
5
6
7
export default {
  // ...
  'paper-trail': {
    enabled: true
  }
  // ...
};

Heads up! Disabling the plugin will destroy the Paper Trail model and everything in it, clearing your revision history.

Then, you'll need to build your admin panel:

# Using Yarn
yarn build

# Or using NPM
npm run build

Usage

The functionality of this plugin is opt-in on a per content type basis and can be disabled at any time.

To enable the plugin, edit the content type via the Content-Type Builder screen.

Or by modifying the pluginOption object on your models schema.json.

1
2
3
4
5
6
7
  // ...
  "pluginOptions": {
    "paperTrail": {
      "enabled": true
    }
  },
  // ...

Once enabled on the model, Paper Trail will be listening for changes to your records and will automatically create revisions when records are created or updated. These changes can be viewed directly from the content manager edit view.

For convenience, the plugin will differentiate CREATE from UPDATE and will display which user made the change (regardless of whether they are an admin or a user permissions plugin user).

Clicking 'View all' will show the entire revision history for this record.

The revision history for each field that was touched during the CREATE or UPDATE will be displayed, and you are able to select which fields you would like to restore by checking the checkbox on each accordion.

Once you are ready, you will get a final chance to review the entire scope of the fields that will be restored. You can also view the JSON object for debugging purposes (or simply as a way to quickly grok the entire change).

Clicking 'Restore' will then immediately overwrite the selected fields on the original record, restoring your revision.

Notes & Considerations

While I have tried to keep the plugin as simple and intuitive to use as possible, there are some notes and considerations to mention. Some of these are strapi specific, some are specific to the challenge of version control, and others are plugin specific challenges.

1. The plugin has currently only been tested on node v18, though it should work perfectly on any node version that strapi v4 directly supports (currently node v14 and up).
2. The plugin relies on the content type plugin UID property to identify the correct content type and associate the revision history. If you change this value you will lose previous revision histories (all revision history records can be manually browsed and modified from Content Manager > Collection Types > Trail).
3. This has not been tested with all available custom field plugins, however as long as the custom field plugin implements on top of the core strapi content manager types (e.g. string, text, biginteger, json, component, and so on) and isn't doing anything too arcane, then it should be fine.
4. The plugin is a middleware listening on the admin and user content management endpoints. Making changes directly to the records outside of this scope (e.g. from a custom service or controller) will not be logged as a revision by the plugin, however it shouldn't be difficult to manually implement this if needed.
5. Attempting to restore a unique field with a duplicate value will cause the request to fail.
6. Likewise, attempting to restore a field that has been since deleted from the schema or renamed will cause the attempt to fail (restoration of a delete field is on the roadmap)
7. password type is not supported for security reasons.
8. The plugin is still in early development, use with caution!
9. Pull requests for new features and fixes welcome and encouraged 🚀

Roadmap

In no particular order and subject to change depending on priorities.

1. Compare diffs against current vs chosen revision, or two separate revisions.
2. Restoration for records deleted by DELETE event.
3. Small enhancements to better leverage available strapi server hooks instead of custom code.
4. Pagination for longer revision history lists.
5. Plugin management panel for purging revision history.
6. Selecting which field to send the revised change to on the record (supporting schema name changes).
7. Better support for only logging changed fields (currently the strapi admin sends the entire record back and not just the changes fields) to reduce revision noise.

Support

Please create an issue in the issue tracker if you have a problem or need support. Please select the correct label when creating your issue (e.g. help wanted or bug).

Contributing

Contributions are welcome. Note that code style is enforced with prettier. Kindly adhere to this while making contributions.

Step 1: Fork this repo

Step 2: Start hacking

Step 3: Open a PR

Step 4: Profit 💰💰💰

License

MIT License