Home

Workflows is a toolkit for listening to specific events and letting the right people know with appropriate follow up actions.

It aims to answer the following questions:

1. When should an action or notification happen
2. What is the message and what are the follow up actions
3. Who should be notified
4. Where should the notification go

Workflows can be defined in code or via the WordPress admin, however there are some extra steps to make the latter work.

API

Workflow

The simplest possible example of a workflow defined in code might be:

<?php
namespace HM\Workflows;

Workflow::register( 'notify_editor_on_new_post' )
  ->when( 'draft_to_pending' )
  ->what( 'A new post is ready for review' )
  ->who( 'editor' )
  ->where( 'email' );

1. Workflow::register( '<id>' ) creates a new Workflow object that can be referenced later
2. ->when( '<Event>' ) tells it to listen to a specific action hook or Event object
3. ->what( '<message text>' ) sets the text to send
4. ->who( '<email | role | user ID(s)>' ) sets the recipients of the message
5. ->where( '<Destination>' ) is how the message is delivered, built in options are email, slack and dashboard

Learn more about the Workflow object

Events

Events that trigger a workflow can be anything that happens within WordPress. The simplest example is an action hook such as publish_post. This could also be any custom event you can detect and respond to in PHP, for example a specific query string argument is present.

In the above example draft_to_pending is assumed to be an action hook and is converted to an Event object internally. You could also pass a custom Event object to get fine grained control over your event listener.

Because Event action hooks might receive some custom data such as post data you can also add handlers to provide support for the following:

• Dynamic recipients
• Tags that are replaced by dynamic data in the message text
• Follow up actions appended to the message

Learn more about the Event object

Built in events:

• Publish post
• Publish page
• Post status change (select from all available statuses)
• New comment
• New editorial comment

Destinations

A Destination object receives a workflow's processed recipients list and handles dispatching the messages. The simplest example is the email Destination.

You can also create and register any number of custom destinations you might want such as posting to a CRM, issue tracker or chat application.

Learn more about the Destination object

Built in destinations:

• Email
• Dashboard
• Slack

UI

Both the Event and Destination objects can optionally have a UI object assigned to them. The presence of this object instructs the plugin to show the event or destination in the Workflows admin. This allows them to be reused and remixed to create any number of custom Workflows without hardcoding them.

In addition to making these objects available in the admin interface you can also add a settings form to allow users to configure aspects of the event or destination's behaviour. For example this is how the email destination allows you to choose whether to send individual messages or cc everyone.

Learn more about the UI object

Built in features

This plugin provides a few custom features on top of the lightweight framework.

Dashboard notifications

Receiving notifications in the context of where you work makes a lot of sense for a productive team. With that in mind you can target messages to a user's dashboard directly.

Slack integration

You can send messages from a workflow to any Slack channel. Just add your Slack incoming webhook URL to the slack destination settings.

Editorial comments and assignees

A key part of any workflow tool is being able to discuss your content and clearly define who is responsible for it. Editorial comments provide another way to add notes about the post you're working on and when needed assign it to someone else along with instructions. You can then create a workflow to notify the new assignee(s).