Workflow event types #

Part 3, chapter 18. A workflow event type is a step builders can put into a workflow (see Workflows for builders): approve, wait until a date, and whatever your extension adds. This chapter shows how to write one. The example passed php -l and was created and queried with the kernel loaded; the reference classes are eZWorkflowType and eZWorkflowEventType (kernel/classes/).

Registration #

extension/mysite_hello/settings/workflow.ini.append.php:

<?php /* #?ini charset="utf-8"?

[EventSettings]
ExtensionDirectories[]=mysite_hello
AvailableEventTypes[]=event_mysitepublishlog

*/ ?>

The type string is event_<type>; the kernel (eZWorkflowType::loadAndRegisterType()) splits it into the group event and the type mysitepublishlog and includes extension/mysite_hello/eventtypes/event/mysitepublishlog/mysitepublishlogtype.php. The swark extension registers its two events (event_autopriority, event_defertocron) the same way.

The class #

<?php
/**
 * Workflow event "Log publishing": writes one line per published version to var/log/mysite_hello.log.
 * Use it on the trigger content / publish / after.
 */
class mysitePublishLogType extends eZWorkflowEventType
{
    const WORKFLOW_TYPE_STRING = 'mysitepublishlog';

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

    public function execute( $process, $event )
    {
        $parameters = $process->attribute( 'parameter_list' );
        $objectID = isset( $parameters['object_id'] ) ? (int)$parameters['object_id'] : 0;
        $version = isset( $parameters['version'] ) ? (int)$parameters['version'] : 0;

        $object = eZContentObject::fetch( $objectID );
        if ( !$object instanceof eZContentObject )
        {
            // nothing to log; let the operation continue
            return eZWorkflowType::STATUS_ACCEPTED;
        }

        eZLog::write( sprintf( 'Published object %d version %d: %s', $objectID, $version, $object->attribute( 'name' ) ),
                      'mysite_hello.log' );

        return eZWorkflowType::STATUS_ACCEPTED;
    }
}

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

With the kernel loaded, eZWorkflowType::createType( 'event_mysitepublishlog' ) returned the class with the name "Log publishing", and isAllowed( 'content', 'publish', 'after' ) was true while 'before' was false.

What execute() can return #

From eZWorkflowType (kernel/classes/ezworkflowtype.php):

swark's defertocron event is the smallest real example: its execute() only returns STATUS_DEFERRED_TO_CRON, so publishing is finished by the cronjob instead of during the editor's request.

Before or after? #

An event that only reacts and never waits or rejects is often simpler as an event listener (Events, listeners and filters): no workflow to configure.

Settings of an event #

An event can have its own settings per workflow (like the approvers of Approve): implement fetchHTTPInput(), validateHTTPInput(), workflowEventContent() and storeEventData(), and add the templates workflow/eventtype/edit/event_<type>.tpl and workflow/eventtype/view/event_<type>.tpl to your design. The kernel's approve event (kernel/classes/workflowtypes/event/ezapprove/) is the complete reference.

Be careful in execute() #

• It runs inside the publishing operation: keep it short, and never echo output.
• Write to the database inside $db->begin() / $db->commit() when you change several things.
• Cast every ID you put into SQL; swark's autopriority reads node IDs from the object and uses them in an UPDATE.
• An exception aborts publishing for the editor. Catch what you expect, log it with eZDebug::writeError(), and return a status.

RAD #

Workflow event extension (/setup/workflowevent) writes the class, settings and templates, including event settings and triggers; see With RAD: a workflow event.

Related pages #

• Previous: Datatype storage, validation and templates
• Next: Triggers and workflows for developers
• The eZWorkflowType API
• Workflows
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.