kaliop/ezworkflowenginebundle

Kaliop eZ-Workflow-Engine Bundle

ezworkflowenginebundle

A workflow engine for eZPublish5 / eZPlatform., _(*1)

How it works, in 10 lines of configuration

Example workflow definition:, _(*2)

-
    type: workflow
    signal: LocationService\HideLocationSignal
    run_as: admin

-
    type: content
    mode: update
    new_remote_id: pippo
    match:
        content_id: workflow:signal:content_id

In plain words, this means: when any content is hidden, set its 'remote_id' value to 'pippo'., _(*3)

More examples of how "real-life" workflows do look like:, _(*4)

• Add a screenshot automatically when a video file is uploaded
• Fill contents with 'lorem ipsum' text using an online service
• Fire a mail alert if an editor moves content that he's not supposed to alter

Getting started

1. Install the bundle using composer, enable EzWorkflowEngineBundle in your application Kernel (if you had not previously installed the eZMigrationBundle, you should enable as well EzMigrationBundle - composer will have downloaded it automatically for you, but not enabled it), _(*5)

2. Create a workflow definition in any bundle you want by using the dedicated command, _(*6)

   php ezpublish/console kaliop:workflows:generate myBundle

3. Edit the workflow definition, _(*7)

   • change the value for the 'signal' element to the name of an existing eZPublish Signal (see https://doc.ez.no/display/EZP/Signals+reference)
   • add the required steps to your workflow (see the docs from the kaliop migration bundle for possible steps definitions)

4. test that the workflow is listed as available, _(*8)

   php ezpublish/console kaliop:workflows:debug

5. connect to the Administration Interface, execute the desired content modification action. (Note: if you are using the Legacy Admin interface, you will need to execute extra work. Read the dedicated chapter below), _(*9)

6. check that the workflow you defined did execute, _(*10)

   php ezpublish/console kaliop:workflows:status

   Also, if you have enabled 'debug' level logging for Symfony, you will find that any time an eZPublish signal is emitted, the workflow engine add to the log 1 or 2 lines with information about its actions., _(*11)

7. set up a cron job that will pick up and restart any suspended workflow by executing, fe. every 5 minutes, the following:, _(*12)

   php ezpublish/console kaliop:workflows:resume -n

8. set up a cron job that will clean up the workflow table in the database by executing, fe. daily, the following:, _(*13)

   php ezpublish/console kaliop:workflows:cleanup

9. once your workflow is debugged and tested, don't forget to commit the workflow definition file as part of your source code ;-), _(*14)

Frequently asked questions

Q: how can I find out which content/location the current workflow is dealing with?, _(*15)

A: the workflow engine makes available as references the parameters found in the Signal which triggers the workflow. Ex: workflow:signal:content_id. Once you have a content or location id, you can use the steps 'content/load' and 'location/load' to get hold of the whole thing, and set new references to its other attributes, eg:, _(*16)

    - 
        type: content
        mode: load
        match:
            content_id: workflow:signal:content_id
        references:
            -
                identifier: the_object_name
                attribute: name

Q: how can I make a workflow act only on some specific content(s)?, _(*17)

A: use a workflow/cancel step with an 'unless' condition, _(*18)

Q: are there steps which are specific to workflows, besides those found in the migrations bundle?, _(*19)

A: yes. Take a look at the docs, _(*20)

Q: how can I troubleshoot workflows?, _(*21)

A: by default workflow execution steps and triggers are logged in detail as part of the Symfony log, at DEBUG level. If you want to have a separate log file dedicated to troubleshoot only workflow events, you can add to your config.yml something similar to fe., _(*22)

    monolog:
        handlers:
            workflow_log:
                type: stream
                path: "%kernel.logs_dir%/%kernel.environment%.workflow.log"
                level: debug
                channels: [ ez_workflow ]

Q: can I suspend a workflow and restart it later?, _(*23)

A: yes, just as you would with a migration (see the doc in the migrationbundle for details). NB: when a workflow is restarted, all the reference values that it had originally will be restored, however it might be that the contents that they refer to have changed in the meantime., _(*24)

Q: does the workflow engine emit Symfony Events when workflows are run?, _(*25)

A: yes. Currently the following events are emitted: * ez_workflow.before_execution * ez_workflow.step_executed * ez_workflow.workflow_aborted * ez_workflow.workflow_suspended, _(*26)

Q: can the workflow engine be used for scenarios where user interaction is required (eg. Content Approval ?), _(*27)

A: not yet, and possibly never in a "good enough" way. The main reason for this is that all the eZPublish Signals are triggered 'after' an action takes place. As such, it is hard to keep a content in 'for approval' state after it has already been published. The 2nd reason is that at the moment there is no way to allow GUI interactions with existing workflows (but this could be easily worked around with dedicated steps), _(*28)

Q: can I manage the workflows and triggers via a GUI, just like I used to do in eZPublish 4?, _(*29)

A: no, but you have command line tools to help with debugging and troubleshooting, _(*30)

Q: why are you storing the workflow definitions in configuration files instead of using the database?, _(*31)

A: this makes it much easier to have consistent workflows definitions across development/test/production environments, as well as Continuous Integration scenarios, _(*32)

Q: are workflow definitions cached ?, _(*33)

A: yes. For speed of execution, the bundle caches the parsed workflow definitions attached to each signal. This means that, if you are running Symfony in non-dev mode, you will have to clear the Symfony cache each time that you modify the definition of an existing workflow or add/remove workflows (using f.e. the cache:clear command), _(*34)

Integration with the Legacy Administration Interface

By default, editing actions carried out in the Legacy Administration Interface do not trigger execution of the workflows defined in your yml files. It is however possible to do so, with just a little bit of configuration work: - enable the extension ezworkflowenginebridge in settings.ini.override.php - clear caches - in the Administration Interface, create custom Legacy Workflows and hook them up to Triggers as per the documentation that you will find in the readme, _(*35)

, _(*36)

, _(*37)