Skip to main content

Workflow Component Migration

Migrating from the workflow component to the processAutomation component is non-trivial. This guide aims to make the transition as smooth as possible while providing some tools to help you with.

The starting point is an application which is using the workflow component with configuration present in an accessible database. Each step is self-contained and designed to be picked up incrementally. This means you can plan each step as a separate task or ticket.

Partial Migration

Even if you do not plan to adopt process automation in its 0.x.x releases, it is advised to at least go through step 1 and 2. These are both fully compatible with the workflow component and already provide some of the conveniences.

Step 1: Introduce workflow metamodel​

Workflow configuration will currently be stored in the database, and configured with .sql scripts. With process automation this will move to the model such that we can expand a lot more and avoid lots of dynamic lookups.

The first step is adding the model resource for the workflow model.

<expansionResources>
  <expansionResource name="net.democritus.workflow:workflow-model-stack" version="1.7.0"/>
</expansionResources>

We provide the workflows-importer tool to import a database configuration and write it to the model files for the workflows. For detailed instructions on how to use this tool, see the dedicated instructions page.

When upgrading from dataFlowTasks or a previous version of the workflow model, you can use the UpgradeWorkflowModel transmutation.

mvn expanders:transmute-model -Dtransmutation=UpgradeWorkflowModel

Besides moving the runtime configuration to the model, the workflow metamodel will add a few things to the application:

  • Each workflow has a <Workflow>ConfigureBean, which populates the database with all configured transitions if not yet present. You no longer need to add .sql migration files to create or update configuration.
  • If a state is configured as 'initialState', it will set the status field in the logic layer pre-create.

Step 2: Migrate Task Outcomes​

Tasks have the option isBranchingTask which allows the task implementation to choose the end-state of a transition. This is not nicely modeled as the task shouldn't be aware of the transition it is in. To better support this we added TaskOutcome to the model. It is a list of values which can be the result of a task. These outcomes can then be referenced from the workflow metamodel if multiple end-states are defined.

When task outcomes are defined, an enum with the provided values will be expanded and the return type of the task will change to this enum. When doing this migration you will have to change all branching task implementations to use a task outcome instead of a status return.

If you defined multiple end states in the workflow metamodel, you can run the 'UseTaskOutcomes' transmutation to add outcomes to the model. Otherwise, you can also model these manually.

mvn expanders:transmute-model -Dtransmutation=UseTaskOutcomes

Step 3: Adopt process automation​

This step is the most involved, as there are some significant differences between the workflow and process automation component.

  1. First you will need to add the process-automation-component as an expansionResource to the project.
    <expansionResources>
      <expansionResource name="net.democritus.workflow:process-automation-component" version="1.1.1"/>
    </expansionResources>
    *Note*: When using the TomEE application server, make sure your `applicationServer` in businessLogicSettings is set to 'TOMEE'.
  2. Next, the workflow component needs to be removed, as their implementations are conflicting. This includes removing 'workflow' from the application and component dependencies, and replacing them with 'processAutomation'.
  3. The component needs some runtime data to be stored. The database should be migrated to create all tables required by process automation. A `.sql` file should already be expanded based on the newly added model resources.
  4. When using the knockout UI, you will likely need to adjust the `<app>.menu` file to use processAutomation instead of workflow.
  5. (Optional) Add the process-automation-tracing resource to get trace logging for all transitions executed in process automation.
    <expansionResources>
      <expansionResource name="net.democritus.workflow:process-automation-tracing" version="1.1.1"/>
    </expansionResources>
  6. If all steps were done correctly, you now should have a functional application again. Note that any customizations or configurations are ignored. The process automation flowEngine will only take the waittime and batch size into account if defined. If other customizations were critical, you will need to replace these in step 4.

Step 4: Customize​

Flow engines do not take much advantage of the improvements of this component. It is strongly advised to revisit the trigger design and execution configuration to suit your application.

  1. Configure appropriate triggers. The workflow design guide talks about the available triggers and when to apply them. This can significantly reduce overhead and is generally more performant.
  2. Execution configuration can be used to further fine-tune how workflows are executed. The default should provide a generally applicable solution, but in performance critical situations it can be valuable to customize this configuration. See the workflow execution guide for some guidance on this topic.
  3. If the customizations provided do not give you enough control, there is room for rolling your own. This includes custom triggers, implementing queue drivers or simply customizing behavior through expander features and custom code.