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.9.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. Note that this guide assumes a full migration. If you need to approach the migration more slowly, take section Granular migration of workflows into account.

  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.5.5"/>
    </expansionResources>
    Note: When using the TomEE application server, make sure your `applicationServer` in businessLogicSettings is set to 'TOMEE'.
  2. Depending on whether you're doing a granular update either:
    • the workflow component needs to be removed. This includes removing 'workflow' from the application and component dependencies, and replacing them with 'processAutomation'.
    • or instead of removing the workflow component dependency, keep it until all workflows are migrated.
  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.5.5"/>
    </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.

Granular migration of workflows​

note

This strategy has been introduced in the workflow-model-stack:1.9.0 and will only work with process-automation-component:1.5.0 and above.

For some projects it may be difficult to migrate the entire application at once. In these cases you can opt into a migration strategy which specifically targets individual components and workflows.

  1. Run the transmuter StartWorkflowComponentMigration on a component. This will add the optionworkflow.component.migrate to the component and workflow.component.enable to all workflows. You can also run it on the application to transmute all components at once.
    1. Navigate to your Component.
    2. In the tree-view, open the context menu of the component (right-click).
    3. Select "Start Workflow Component Migration". This will add the options mentioned above.
  2. Add 'processAutomation' to the componentDependencies of the component you want to start migrating.
  3. Remove the workflow.component.enable option from the workflow(s) you want to migrate. The workflow without this option will now be picked up by processAutomation, instead of using the workflow component.
  4. Repeat the previous two steps until all workflows are migrated.
  5. Remove the workflow.component.migrate option and workflow componentDependency from the component.
  6. Once all components are migrated, the workflow component can be removed from the application and theworkflow-model-stack can be removed from the expansion config.

Removed features and replacements​

Not all features available in the workflow component are still supported by process-automation. This section lists the features for which support has been dropped and how they should be re-implemented.

  • TimeWindowGroup: If workflows should only run within certain intervals you can now configure WorkSchedules on each workflow execution.
  • Service element: Instead of using a service element workflows can be configured to act as a service by defining a single transition with the same begin- and end-state. Additionally, a single instance of the dataElement with this state should be provisioned in the database.
  • Workflow claims: Claims are no longer needed, as the queues within process-automation handle task distribution between multiple nodes.
  • Greedy sequencing strategy: FlowEngines no longer take an instance through the whole workflow. Instead, they perform only one transition and thereafter rely on the queue and other triggers to process any remaining transitions. To get a similar outcome to the greedy sequencing strategy you would add the OnTransition trigger to all transitions after the first, and increase their workflow.priority above 50. This makes sure any follow-up transitions are executed first when they end up on the queue.