End of Life notice

Please be aware that BetterWorkflow is now at End of Life. Support will be provided for existing licence holders until March 31 2018. After this time no further support will be availabe.

Overview top

Better Workflow is an ExpressionEngine add-on from Electric Putty that adds inline preview, entry drafts and approval processes to the EE control panel. With Better Workflow, you will be able to work on a 'draft copy' of a live entry, preview your changes and then 'submit for approval', all without affecting the live website. When the new content has been approved and published the 'draft copy' replaces the 'entry' and the live site is updated.

Requirements top

Better Workflow requires ExpressionEngine 2.4 or newer.

Browser Compatibility

Better Workflow will work in all modern browsers, but you may experience issues if you are using an outdated browser version, such as Internet Explorer 7, which has issues with the <button> element.

Add-on Compatibility

Please refer to our compatibility page for detailed information.

Installation top

  1. Back up your database
  2. Download and unzip Better Workflow
  3. Back up your database again and put this backup somewhere else (better safe than sorry)
  4. Copy system/expressionengine/third_party/ep_better_workflow to system/expressionengine/third_party
  5. Copy themes/third_party/ep_better_workflow to themes/third_party/
  6. In the control panel, go to Add-ons → Extensions and enable Better Workflow
  7. [Optional] Enable the 'Approval required' accessory
  8. Click Settings and choose which channels you wish to use Better Workflow with and which user groups you want to make Editors and Publishers

Configuration top

The Better Workflow settings panel is straightforward; simply select the channels you want to use, the default template for those channels and which, if any, member group receives approval notification emails. Then select your member group roles (Publisher or Editor) and you're all set!

Let's go through these in greater detail:

Channel settings

The channel selection menu

When you choose a channel to be managed by Better Workflow, the dropdown menus for preview template and notification emails appear. Choose your desired template for the channel (no modifications to the template should be required), this will be the template used for the inline preview function. If you are using Structure, the preview will use the entry's Structure URL except in the case of brand new entries (see caveat above).

N.B. Better Workflow's preview feature relies on the standard /template_group/template/entry_id format for its URL so you should be able to simply select the channel's default template. However, depending on how your template is constructed, it may sometimes be necessary to create a 'preview specific' version.

Next you can choose a member group that will receive notification emails when an 'entry' or 'draft copy' is 'Submitted for approval'. If you are using the Editor/Publisher options this means that when a user designated a 'editor' submits an entry for approval, users in the selected member group will receive an email notifying them that there is an entry needing their attention.

Existing entries

If you choose to enable Better Workflow on an channel that has existing entries that have statuses other than open or closed then you will be presented with the following dialog:

The status mapping menu

You will then have to choose a new status for these entries as this channel will be assigned the Better Workflow status group. When you have mapped these statuses, and click the 'save' button on the settings page, these entries will be permanently updated to the selected mapped statuses.

Group settings

The group settings menu

Now you need to choose your member group settings. You will see a list of all member groups who have Control Panel access and you need to decide which groups are Publishers and which are Editors.

Publishers have the ability to Publish content on the live site as well as the ability to approve entries that have been submitted for approval.
Editors cannot publish to the live site (for the channels that BWF is assigned to), they can only submit their 'entries' and 'draft copies' for approval by a Publisher.

Advanced settings

The advanced settings menu
  • Redirect on Save and close / Discard draft: By default, when dealing with live + draft entries, if you press 'Save and close' or 'Discard draft' we will redirect you back to the ExpressionEngine edit list. If you wish to redirect to Structure, or Zenbu on these interactions, please enable it here.
  • Disable preview: This can be set to 'Never', 'Always' or 'For new entries'; Enabling this option will hide the 'Save and Preview' button on a brand new entry. If you are using Structure, and preview a brand new unsaved entry you may have issues with your preview as the Structure URL will not have been generated yet, and Better Workflow will use the normal EE URL format. If you are having these issues, you may wish to disable the preview on brand new entries using this option, so that your users can only preview once a Structure URL has been created.
  • Display full URL in preview window: Better Workflow normally shows a simple version of the URL in the preview window. Changing this to 'Yes' will show you the full URL with query strings. We may ask you to turn this on so we can help diagnose a problem.
  • Ignore Pages / Structure URL for preview: If you have the Pages or Structure modules installed, Better Workflow will use the 'Page URL' to generate the preview URL by default. If you wish to force the default 'template_group/template' ExpresisonEngine format, enable this option.
  • Remove index.php from preview URL: As there may be some people who do not remove the index.php in their ExpressionEngine install, we always include index.php in the preview URL. If you wish to remove the index.php from the preview URL, please enable this option.
  • Preview URL last segment: You can select whether to use the entry's ID or url_title as the last segment of your preview URL
  • Log Events: If you're having trouble with Better Workflow, we may ask you to turn on the 'log events' option. This will generate a .txt file on your server which you can send to us so we can help diagnose your problem.
  • Show full error messages: Again, if you're having trouble with Better Workflow, we may ask you to turn on the 'show full error messages' option. This will output the full error message in the error popup on the Publish page, which may help us debug your issue.
  • Enable external previews: When selected Better Workflow will add a button to the bottom of the preview window. When clicked this will generate a preview URL which will allow access to the preview from outside the Control Panel.

Config overrides

There are three optional config override. These are advanced options and should be used with some caution. Add these to your ExpressionEngine config.php if you wish to use them.

  • $config['bwf_preview_status']: When you preview a non-live entry, we change its status to 'open' for a split second to generate the preview, then revert it back. If you wish to change the status it is changed to, you can override it using this setting. You will then need to add this status to your channel entries tag in the template you are using. e.g.


$config['bwf_preview_status'] = "preview_secret";


{exp:channel:entries channel="editorial" status="open|preview_secret"}
  • $config['bwf_preview_token_length']: Length in characters of the auth token generated by Better Workflow (default 25)
  • $config['bwf_preview_token_ttl']: Auth token time-to-live in hours (default 24)

Usage top

We hope you will find using Better Workflow very intuitive, but here's a lowdown on all the controls you might see:


The preview button's location in the Better Workflow publish bar

At the heart of Better Workflow is our inline preview functionality. Whether you are working on a draft entry, a draft copy of a live entry or even a closed entry, a click of 'save and preview' at any time will save your work and then immediately open a modal window showing you a live preview. There's no need to go to another page and then navigate back, to continue working on the entry just close the window - now that's better workflow!

The Better Workflow preview modal

Entries & Draft copies

All entries start out in draft status, before being either or published. When approved/published, they get given the status of open. If you wish to edit an open entry, Better Workflow will give you the ability to create an editable draft copy which you can amend, preview and finally, either or publish.

The Edit Entries list

The Edit Entries list with Better Workflow enabled

We have added extra highlighting and icons to the Edit Entries list to show you the status of your Better Workflow managed entries. At a glance you will be able to see what entries need , what entries have drafts copies of their live versions, as well as all your normal draft entries.

The Publish view

We've added a control bar to the top and bottom of your Publish Entry view. This will contain different buttons depending on what state your entry is in.

The draft state of the Better Workflow control bar looks like this (for a Publisher):

The Better Workflow publish bar in 'draft' state
  • Save and preview will save the entry, and open the preview modal.
  • Save and close will save the entry, and return you to the Edit entries list.
  • Publish will publish the entry.

Editor differences

For an Editor, Publish is replaced with ''.

The Better Workflow publish bar, for an editor, in 'draft' state

The live state of the Better Workflow control bar looks like this (for a Publisher):

The Better Workflow publish bar in 'live' state
  • Save and preview will create and save a draft copy of the page, and open the preview modal.
  • Save and close will create and save a draft copy of the page, and return you to the Edit entries list.
  • Publish will publish the entry.
  • Archive will set the status of the entry to closed.

Editor differences

For an Editor, Publish is replaced with ''. Also, they do not have the ability to Archive a live entry.

The Better Workflow publish bar, for an editor, in 'live' state

The live + draft copy state of the Better Workflow control bar looks like this (for a Publisher):

The Better Workflow publish bar in 'live draft' state
  • Save and preview will update the draft copy and launch the preview modal.
  • Discard draft will discard the draft copy of the entry, reverting back to the live state of the entry.
  • Save and close will update the draft copy of the entry and take you to the Edit entries list.
  • Publish will publish the draft copy, replacing the old live entry.

Editor differences

For an Editor, Publish is replaced with ''.

The Better Workflow publish bar, for an editor, in 'live draft' state


An entry in 'submitted' state, as viewed by an Editor

When an Editor submits a draft or draft copy for approval, two things happen:

  • An e-mail is sent to all members of the user group that has been specified on the Better Workflow settings screen.
  • The status of the entry is set to '' and is not editable by the Editor unless they click 'Revert to Draft'.

The Publisher can then choose to revert the entry back to draft status, or publish the entry.

Accessory: Approval required

The pending approval accessory showing some items requiring approval

If you enable this accessory, Publishers with the correct permissions can see a list of 9 entries requiring approval. Simply click on an entry to be taken to it, where you can then approve the entry if desired.

Template tagstop

For version 1.5 we have added some tags which you can use in your templates to set conditionals based on BWF behaviour:


If the template is being viewed as a preview in the CP, or via a BWF external preview URL, this will be set to true.


If the content being sent to the template is a BWF live-draft (as in, NOT a standard EE Entry) this will be set to true.

Changelog top

Please note: As of BWF 1.6.2 support for old style relationships has been removed - If you require this please use version, available on request.

V1.6.5 [04/08/2015]

  • [Bug] Fixed issue where an empty file field was converted to a file directory reference when saving a Draft
  • [Bug] Fixed version comparision method in entry list JavaScript

V1.6.4.2 [03/03/2014]

  • [Bug] Fixed relationship logging issue
  • [Bug] Fixed entry list JavaScript to work in EE2.8

V1.6.4.1 [17/01/2014]

  • [Bug] Added check for userdata property in session object to constructor so we don't try and instantiate the library until it is populated
  • [Bug] Removed second parameter from all calls to json_encode as this was throwing errors in some version of php

V1.6.4 [26/11/2013]

  • [Enhancement] Added Save and Preview label to language file
  • [Enhancement] Added extra debug information to preview JavaScript
  • [Housekeeping] Moved all entry list related JavaScript into accessory and removed cp_js_end hook
  • [Housekeeping] Removed css inclusion from zenbu library as this is now handled by accessory
  • [Bug] Removed hard coded logging flag from ep_files library

V1.6.3 [27/09/2013]

  • [Bug] Added check for valid Matrix data at point of draft creation
  • [Housekeeping] Removed package from zip to solve issues when using Updater - this version is now available on request.

V1.6.2.1 [26/07/2013]

  • [Bug] Re-factored JavaScript to perform pre ajax save processing on all CKEditor based field - resolved compatibility issue with Wygwam 3
  • [Bug] Removed hard-wired value in third-party field controller which ignored logging setting

V1.6.2 [10/07/2013]

  • [Enhancement] Added support for EE2.6 + including new Relationships field.

V1.6.1.2 [01/07/2013]

  • [Bug] Added $this->EE->extensions->last_call check to template_post_parse hook to overcome compatibility issues.

V1.6.1.1 [14/06/2013]

  • [Bug] Fixed issue where Matrix rows were getting removed from a BWF draft when the preview window was closed

V1.6 [16/04/2013]

  • [Feature] Playa compatibility now entirely handled by Playa (version 4.4) using BWF API
  • [Feature] BWF log can now be viewed and cleared from the settings screen within the CP
  • [Feature] Added ability to specity url_title as last segement of preview URL
  • [Feature] Added new setting to disable preview completely
  • [Bug] Added last_call checks to session_start and publish_form_entry_data hook calls to resolve some compatibility issues

V1.5.1 [19/12/2012]

  • [Bug] Refactored binding and unbinding JS

V1.5 [05/12/2012]

  • [Feature] Matrix compatibility now entirely handled by Matrix (version 2.5) using BWF API
  • [Feature] Added {is_bwf_preview} and {is_bwf_draft} template tags
  • [Enhancement] Removed all internal Matrix compatibility code (approx 1000 lines)
  • [Enhancement] Tweaked database upgrade method to check minimum version number and only perform updates if current is less than this
  • [Bug] Fixed hook deletion issue in ep_activate model

V1.4 [19/10/2012]

  • [Feature] Added ability to preview draft entries from outside the CP
  • [Enhancement] Added auth token config vars 'bwf_preview_token_length' and 'bwf_preview_token_ttl' (time to live)
  • [Enhancement] Refactored preview auth process
  • [Bug] Resolved JS issue caused when a Matrix field failed to reinitialise after a preview
  • [Bug] Fixed new issue caused when creating a draft with an empty file field (as of EE 2.5.3)
  • [Bug] Fixed status mapping issue which listed the same status more than once

V1.3.2 [31/8/2012]

  • [Enhancement] Added AJAX method to revert entry's status as soon as preview template has rendered
  • [Bug] Fixed issue where draft_publish() method in Third Party API was getting called twice

V1.3.1 [24/8/2012]

  • [Bug] Fixed MSM issues where role information was not available outside main site

V1.3 [22/8/2012]

  • [Feature] Language file added for customisation of button text labels
  • [Feature] Added option to disable notifications
  • [Feature] Added option to remove index.php from preview URL
  • [Feature] Added option to ignore Pages/Structure URL when previewing
  • [Feature] Added option to redirect to Structure or Zenbu on Draft action
  • [Feature] Added config override for status switching on non-live entries
  • [Enhancement] Major JS refactoring
  • [Enhancement] Native Playa support added for 4.3.1 +
  • [Enhancement] Added dynamic preview window resizing

V1.2.3 [7/6/2012]

  • [Bug] Fixed IE 8 preview bug where auth token was cached
  • [Bug] Fixed issue where entry_id=0 was not getting checked before hook was called
  • [Bug] General Matrix fixes

V1.2.2 [30/4/2012]

  • [Enhancement] Updated API for further support with third party add-ons
  • [Bug] Fixed Matrix PHP errors
  • [Bug] Fixed session var errors
  • [Bug] Fixed edge case multiple draft bug

V1.2.1 [19/4/2012]

  • [Feature] Added bwf_notify_users hook so third party developers can create their own notification routines
  • [Enhancement] Radically updated the preview authorisation process
  • [Enhancement] Draft data retrieval performance enhanced
  • [Enhancement] Implemented new status switching method

V1.2 [2/4/2012]

  • [Feature] Added an API for third-party add-on developers!
  • [Enhancement] Added username of editor to submission email notification
  • [Enhancement] Added support for Playa 4.1+
  • [Enhancement] Added support for Matrix 2.2.4+
  • [Enhancement] Added support for EE 2.4 data tables
  • [Enhancement] Refined required fields notification, with detailed field information
  • [Enhancement] Option: Display full error messages on preview
  • [Bug] Fix for channel entry tag with dynamic="no", by adding a check for relevant entry ID
  • [Bug] Various fixes/refactoring for Matrix fields

V1.1.1 [12/1/2012]

  • [Enhancement] Removed dependancy on JSON_ENCODE(), now leveraging native EE generate_json() method
  • [Enhancement] Accessory now shows edit date of 'live drafts' as well as regular entries
  • [Enhancement] Added config file for BWF constants
  • [Bug] Added binary check for case sensitivity on status mapping
  • [Bug] Added extra redundancy for Zenbu support, data array now traps missing statuses
  • [Bug] Added extra redundancy for Accessory to check that all BWF settings have been assigned
  • [Bug] Added extra redundancy to relationship handling
  • [Bug] Fixed submit for approval generating a second 'live draft' if clicked after a preview

V1.1 [8/12/2011]

  • [Feature] Added support for Zenbu - Thanks to Mark Croxton and Nicolas Bottari
  • [Feature] Added 'Approval required' accessory
  • [Feature] Added support for MX Google Map - Thanks Max Lazar
  • [Feature] Added native Pages support
  • [Feature] Added native Safecracker File support
  • [Enhancement] Refactored extension settings
  • [Enhancement] Refactored upgrade process
  • [Enhancement] Added support for Matrix tag params in preview (Search, limit, offset, order by)
  • [Enhancement] Added extra logging information
  • [Enhancement] Removed unnecessary queries from auth checking model
  • [Enhancement] Added control buttons for Editors on 'Closed' entries
  • [Enhancement] Added session var to tell other third party add-ons they are dealing with a draft
  • [Enhancement] Added advanced setting to show full URL string in preview window
  • [Bug] Fixed URL to Control Panel from Approval E-Mail
  • [Bug] Fixed previewing when in Wygwam/Expresso source mode
  • [Bug] Fixed format of edit_date
  • [Bug] Fixed status switching issue on preview
  • [Bug] Fixed relationship issues
  • [Bug] Fixed strict mode database errors

V1.0 [17/10/2011]

  • Initial Release

Commercial License Agreement top

This license is a legal agreement between you and Electric Putty ("Electric Putty Ltd.") for the use of Better Workflow (the "Software"). By downloading this add-on you agree to be bound by the terms and conditions of this license. Electric Putty reserves the right to alter this agreement at any time, for any reason, without notice.

Permitted Use

One license grants the right to perform one installation of the Software. Each additional installation of the Software requires an additional purchased license.


Unless you have been granted prior, written consent from Electric Putty, you may not:

  • Reproduce, distribute, or transfer the Software, or portions thereof, to any third party.
  • Sell, rent, lease, assign, or sublet the Software or portions thereof.
  • Grant rights to any other person.
  • Use the Software in violation of any international law or regulation.

Display of Copyright Notices

All copyright and proprietary notices and logos in the Control Panel and within the Software files must remain intact.

Making Copies

You may make copies of the Software for back-up purposes, provided that you reproduce the Software in its original form and with all proprietary notices on the back-up copy.

Software Modification

You may alter, modify, or extend the Software for your own use, or commission a third-party to perform modifications for you, but you may not resell, redistribute or transfer the modified or derivative version without prior written consent from Electric Putty. Components from the Software may not be extracted and used in other programs without prior written consent from Electric Putty.

Technical Support

Technical support is available primarily through Tender (http://betterworkflow.tenderapp.com). Electric Putty do not provide direct phone support. No representations or guarantees are made regarding the response time in which support questions are answered.


You agree to indemnify and hold harmless Electric Putty for any third-party claims, actions or suits, as well as any related expenses, liabilities, damages, settlements or fees arising from your use or misuse of the Software, or a violation of any terms of this license.

Disclaimer Of Warranty

The software is provided "as is", without warranty of any kind, expressed or implied, including, but not limited to, warranties of quality, performance, non-infringement, merchantability, or fitness for a particular purpose. Further, Electric Putty do not warrant that the software or any related service will always be available.

Limitations Of Liability

You assume all risk associated with the installation and use of the Software. In no event shall the authors or copyright holders of the Software be liable for claims, damages or other liability arising from, out of, or in connection with the Software. License holders are solely responsible for determining the appropriateness of use and assume all risks associated with its use, including but not limited to the risks of program errors, damage to equipment, loss of data or software programs, or unavailability or interruption of operations.