Write a workflow event type #

This page is for PHP developers who add a step that administrators can put into workflows: notify an outside system when content is published, check a field before publishing, wait for an approval. A workflow runs when a trigger fires (for example content/publish/before or after); each of its events is an instance of an event type, which is a class extending eZWorkflowEventType. The complete example with templates is on Writing a workflow event type.

Contents #

1. Registration
2. The class
3. What execute() receives
4. The statuses
5. Settings per event
6. Deferring to cron
7. Rules
8. Event type or event listener?

Registration #

extension/acmereport/eventtypes/event/acmenotify/acmenotifytype.php
extension/acmereport/settings/workflow.ini.append.php

<?php /* #?ini charset="utf-8"?
[EventSettings]
ExtensionDirectories[]=acmereport
AvailableEventTypes[]=event_acmenotify
*/ ?>

AvailableEventTypes[] entries are the group (event) and the type string joined by _, like the kernel's event_ezapprove in settings/workflow.ini.

The class #

<?php
class acmeNotifyType extends eZWorkflowEventType
{
    const WORKFLOW_TYPE_STRING = 'acmenotify';

    public function __construct()
    {
        parent::__construct( self::WORKFLOW_TYPE_STRING, ezpI18n::tr( 'extension/acmereport', 'Notify the archive' ) );
        $this->setTriggerTypes( array( 'content' => array( 'publish' => array( 'after' ) ) ) );
    }

    function execute( $process, $event )
    {
        $parameters = $process->attribute( 'parameter_list' );
        $object = eZContentObject::fetch( (int)$parameters['object_id'] );
        if ( !$object )
            return eZWorkflowType::STATUS_WORKFLOW_CANCELLED;

        acmeReportQueue::add( $object->attribute( 'id' ), (int)$parameters['version'] );
        return eZWorkflowType::STATUS_ACCEPTED;
    }
}

eZWorkflowEventType::registerEventType( acmeNotifyType::WORKFLOW_TYPE_STRING, 'acmeNotifyType' );

setTriggerTypes() limits the triggers the event can be used with, so administrators cannot attach it where it makes no sense. The kernel's eZWaitUntilDateType (kernel/classes/workflowtypes/event/ezwaituntildate/) is a complete example.

What execute() receives #

For the content publish operation the parameters include object_id and version. Cast them: they are values, not objects.

The statuses #

eZWorkflowType (kernel/classes/ezworkflowtype.php) defines the answers of execute():

Settings per event #

What an administrator sets for the event in the workflow editor is read by overriding fetchHTTPInput() and validateHTTPInput() and stored in the event's columns. Ship the templates workflow/eventtype/edit/event_acmenotify.tpl and workflow/eventtype/view/event_acmenotify.tpl in your design, like the kernel's event_ezapprove.tpl.

Deferring to cron #

An event that waits (for an approval, a date, an outside answer) returns STATUS_DEFERRED_TO_CRON_REPEAT; the workflow cronjob script runs execute() again later, and Setup > Workflow processes shows the waiting processes. The editor sees the publish as pending until the event accepts.

Rules #

• Fast. execute() runs inside the editor's publish request. Queue slow work (outside calls, mail, image processing) instead of doing it there (Background work).
• No exceptions out of execute(). Catch what can fail, log it, and return a status.
• Idempotent. A deferred event runs more than once; make the second run harmless.
• Logic outside the class. Put the decision in a service you can test without a workflow.

Event type or event listener? #

Related pages #

• Workflows, triggers and events
• eZWorkflowType API
• Workflow event pattern
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.