Develop a workflow event to feed an external API

Tutorials

Crédit photo : pxfuel.com


In this blog post, we are going to show you how we can use eZ legacy features along with symfony to feed an external API after publishing a content.

Context:  

We have an entreprise eZ edition 5.x and we want to synchronise eZ contents containing information collectors with forms from a solution for marketing automation (in our case, Eloqua). When a form (eZ content) is updated we want to push the updates automatically into Eloqua.

We decided to use eZ workflows to trigger a custom event in which we are going to use symfony features to access content and interact with eloqua API.

Creating an extension:

First of all, we need to create the directory structure for our new extension that is going to hold the logic for the workflow. We are going to name it eloqua.

Create a new folder eloqua under ezpublish_legacy/extension/ and create the subfolders as follows:

  • eventtypes/event/ : custom event with all the business logic
  • settings/ : settings files

Once we have the directories structure, let’s create the event for our workflow.

Create the event: 

Inside the event folder, create a folder synceloqua/ that will be holding all the logic for our event.

Inside this folder, create a PHP file with the same name as the folder and add type.php at the end. The name of our file will be SyncEloquaType.php

Here is the template for your file :

   

<strong><?php</strong> 
 <strong>class</strong> SyncEloquaType <strong>extends</strong> eZWorkflowEventType 
{ 
    const WORKFLOW_TYPE_STRING = "synceloqua"; 
    <strong>public</strong> <strong>function</strong> __construct() 
    { 
        parent::__construct( SyncEloquaType::WORKFLOW_TYPE_STRING, 'Sync eZ forms with Eloqua' ); 
    } 
    <strong>public</strong> <strong>function</strong> execute( $process, $event ) 
    { 
        $parameters = $process->attribute( 'parameter_list' ); 
        <em>/*  YOUR CODE GOES HERE */</em> 
        return eZWorkflowType::STATUS_ACCEPTED; 
    } 
} 
eZWorkflowEventType::registerEventType( SyncEloquaType::WORKFLOW_TYPE_STRING, 'synceloquatype' ); 
<strong>?></strong> 
   

Your class will be extending eZWorkflowEventType and have one major function execute which will be called when the workflow is executed.

This function is receiving two parameters : $process and $event

  • $process : instance of eZWorkflowProcess, holds information about the workflow process. In particular, let us retrieve the contentId of the object that has triggered the workflow. 
  • $event : instance of eZWorkflowEvent, holds information about the workflow event. Not used in our example.

The return value depends on what needs to be done next.

For example eZWorkflowType::STATUS_ACCEPTED for a workflow that is finished or eZWorkflowType::STATUS_DEFERRED_TO_CRON for a workflow deferred to be processed by a cron.

Business logic code :

The idea is to get the container to be able to call all symfony services. From the attribute parameters_list of the parameter $process, you can get the  (contentId) of the content that has triggered the workflow and then load the content with the content service. Once we have the content, we have all the informations to make our API call and update Eloqua form with the new version of the eZ content.

   

<strong>public</strong><strong>function</strong> execute( $process, $event ) 
{ 
     $parameters = $process->attribute('parameter_list'); 
     $container = ezpKernel::instance()->getServiceContainer(); 
     /** @var $repository \eZ\Publish\API\Repository\Repository */ 
     $repository = $container->get('ezpublish.api.repository'); 
     /** @var $logger \Symfony\Component\HttpKernel\Log\LoggerInterface|\Psr\Log\LoggerInterface */ 
     $logger = $container->get('logger'); 
     $logger->debug('Starting eloqua sync workflow'); 
     $contentService = $repository->getContentService(); 
     $content = $contentService->loadContent($parameters[‘object_id']) 
<em>     /*  YOUR CODE GOES HERE */</em> 
   

Activate the extension : 

Now that our extension is ready we need to activate it in our site.ini file. This is done in the block ExtensionSettings by adding a new line :

   

<strong>[ExtensionSettings]</strong> 
ActiveExtensions[]<strong>=</strong>synceloqua 
   

Declare the workflow event : 

Create a file workflow.ini.append.php under synceloqua/settings/

   

<?php /* 
<strong>[EventSettings]</strong> 
ExtensionDirectories[]<strong>=</strong>synceloqua 
AvailableEventTypes[]<strong>=</strong>event_synceloqua 
*/ ?> 
   

Regenerate the autoload array and clear the caches :

   

php bin<strong>/</strong>php<strong>/</strong>ezpgenerateautoloads.php 
php bin<strong>/</strong>php<strong>/</strong>ezcache.php --clear-all -s yoursiteaccess 
   

Create Eloqua workflow : 

Create a workflow inside the Standard workflow group. Choose a name, for example Sync Eloqua forms and add a Sync eZ forms with Eloqua event.

Create post update workflow : 

Create a new workflow 'Post Publish Event' and add an Event / Multiplexer. Configure the affected sections, languages, classes, and choose 'Updating existing object'. In our case we want this workflow to be executed only in classes Eloqua Form

The workflow to run will be Sync Eloqua forms.

Assign the post update workflow to a trigger : 

Go to trigger administration and assign  'content / publish / after' to ''Post Publish Event' workflow.

Test : 

Edit your form, publish it and verify that the corresponding form in Eloqua is updated.

N.B. This post is inspired by http://share.ez.no/learn/ez-publish/creating-a-simple-custom-workflow-event