Workflow Framework
How-to GuideStep-by-step guides to achieve a specific scenario or setup.
Changed on:
5 Nov 2024
Changed on:
5 Nov 2024
The Workflow Framework provides the following value propositions:
On the left are single lego blocks, which represent a Rule. Rules are the smallest building block for a task (ruleset) in a process. Combining single Rules in different sequences makes a Ruleset, represented by the lego blocks on the right.Single lego blocks are not very useful on their own, but when combined in different sequences, they form Rulesets that execute different pieces of logic — this logic could be for example to perform a specific task within a business process.Let's say we've defined the following Rules:
All Events enter the OMX Workflow Framework via the Fluent APIs. The framework processes these Events via the Event Queue matching the correct workflow and Rulesets to execute — this all occurs within the Workflow Engine.
Outbound (Actions) from the Workflows retrieved from the Rules are returned back and applied via the Fluent APIsThe Action can:
Workflow phases and statesEach workflow has phases (Status or Categories) that the entity flows through from beginning to completion. A default Order workflow for example involves 4 phases:Booking, Fulfillment, Delivery, and Done/Complete.Each of these phases can contain one or many statuses:


If you click on a Workflow title (e.g. HOME DELIVERY) a view of the workflow is displayed. If there are sub-entities involved as part of the overall lifecycle of the domain root entity, they are also displayed in the swim lanes (vertical columns) below the main flow. 

You can add new Rulesets via either an existing Ruleset list or via the Entity Workflow Swim lane. Clicking on the green icon reveals a list of Rulesets configured within that state or transition.Each Ruleset displays the following:
Note: Ruleset Name is required as part of the Event that would Trigger the Ruleset to run.Clicking on a Ruleset Name brings up its details on a slide-out panel on the right-hand side of the screen:
Each of these sections can expand or collapse by clicking on the section header. The expand / collapse feature makes it much easier to work with large Rulesets.
Configuring User Actions involves linking a Button Configuration with a Trigger and a Ruleset. The Button Configuration captures the Button Label, Button Type (type of button), Module Selector (Modules to be displayed), and Confirmation Required check
Clicking the Add Rule button brings up the Rule Library panel on the left of the Ruleset panel. Here, you will find a list of all available Rules based on which Rule Plugins are installed (and Active) for the given Account and Workflow. You can add, change, or remove Rules in this section, as well as use drag and drop to change the order of execution.Most Rules will provide input areas for their required parameters or configuration. E.g. the Change State Rule requires the new Status to be provided so that the Rule knows what state to change the entity to.
Rules in a Ruleset will be executed in the order displayed, from top to bottom. You can add, change, or remove Rules in this section, as well as use drag and drop to change the order of execution.

Multiple instances of a Rule are a design intention.
Each Ruleset executes in sequence for the given context or event.
Recommended practice regarding the naming convention for RulesetsEach Ruleset should only have a single purpose. And, a Ruleset that changes the state of an entity, should be clearly named to reflect that purpose. This is done so that a Workflow is easy to read, and thus becomes easier to support.The diagram on the right shows an example, as well as a non-example of this recommendation.
Key takeaways and Best Practices:A Rule consists of two components:
A Logical Gate may also have multiple possible paths, such as in the evaluation of an ENUM, but, a Logical Gate Ruleset only produces a single outcome, typically an inline event to process the next Ruleset. For example, evaluating X to select one of the three branches (A or B or C) to continue processing.Example: The evaluation of the shipping method that was selected during the order process.
Logical Gate ScenarioFor this scenario, let's assume that the client has a simple requirement:If the order is above $500 annotate it as High Value, and Check for Fraud, else Book the Order.As you can see here, only one of those conditions can ever resolve to TRUE at any given point in time, thereby providing only a single output path from this Ruleset at any time.
Recommended Practice
Secondly, avoid duplicating logic within a workflow.Don't duplicate logic unnecessarily within the workflow - this makes the workflow harder to maintain, and may result in unexpected differences in behaviour between the different tasks. The workflow should be readable and simple.Example: Avoid having more than one Change of State action for each state.
And finally, you must always use ChangeStateGQL to change the state of an entity. Use the ChangeStateGQL rule to change status, as this will ensure that the workflow engine can track the state change and update the context appropriately. If any status changes are made via direct mutation, the workflow engine would not know about this change, and may result in incorrect ruleset matching logic during event execution.Note to Developers using the Rules SDK: You should never set a new status on an orchestrateable entity via mutation action. Always let the workflow configurator use the standard change state rule.Lastly, even if you are able to call an API from within a rule, (a Mutation can be called from within a rule, as it is just a GraphiQL API) and Change the State of that entity from within the rule, it is recommended that you never do this. As this would mean that all that logic will be hidden inside the Java code where no one knows it exists. Why does this matter?Imagine-if someone else were to use that same rule and drop it into another part of the workflow, then their workflow will change states, even if it was not intended. And, that in turn might need additional time and effort to identify and resolve.So, always use the ChangeStateGQL rule that's provided out-of-the-box, so that the workflow engine is able to track and be aware of any entity state changes in order to ensure the event context is valid during processing.
Recommended Practices
Example: UPSERT Inventory Use Case.For the purpose of this example, let us assume that an event is fired with details about an Inventory Position that may or may not yet exist.
Recommended Practice


Here's what the partner creates... They take all three of the client's requirements and build it into a single Rule.
3 months later the client comes back with a request to update one of their requirements.


Now, let's look at the same scenario, but with a different Partner who follows the Best Practice advice and keeps logical gates isolated to their own Ruleset.


Here's what the partner creates... They take the client's requirements and build a separate Rule for each of them.
3 months later the client comes back with a request to update one of their requirements.
So, if we go back and look at Scenario 1, we see that building all the requirements into a single Rule is an Anti-pattern, and will cost the client additional time and money to resolve.
Whereas in the second scenario, because the partner built the Business Logic into the workflow, and not the rule, it was easier for them to update the requirements, without having to charge their clients for additional time spent fixing these changes.
Key takeaways from this scenario| Root Entities (1) | Sub-Entities (2) | Event Reference (3) | Platform CREATE Event? (4) |
| Location | Location Wave | LOCATION WAVE | ❌ ✅ |
| Order | Order Fulfilment Article Consignment | ORDER FULFILMENT ARTICLE CONSIGNMENT | ✅ ✅ ✅ ✅ |
| Fulfilment Options | Fulfilment Options Fulfilment Plan | FULFILMENT_OPTIONS FULFILMENT_PLAN | ✅ ✅ |
| Product Catalogue | Product Catalogue Standard Product Variant Product Group Product Category | PRODUCT_CATALOGUE PRODUCT PRODUCT PRODUCT CATEGORY | ✅ ✅ ✅ ✅ ✅ |
| Inventory Catalogue | Inventory Catalogue Inventory Position Inventory Quantity | INVENTORY_CATALOGUE INVENTORY_POSITION INVENTORY_QUANTITY | ✅ ✅ ✅ |
| Virtual Catalogue | Virtual Catalogue Virtual Position | VIRTUAL_CATALOGUE VIRTUAL_POSITION | ❌ ❌ |
| Control Group | Control Group Control | CONTROL_GROUP CONTROL | ❌ ❌ |
| Return Order | Return Order Return Fulfilment | RETURN_ORDER RETURN_FULFILMENT | ✅ ✅ |
| Billing Account | Billing Account Credit Memo Invoice Payment Payment Transaction | BILLING_ACCOUNT CREDIT_MEMO INVOICE PAYMENT PAYMENT_TRANSACTION | ✅ ✅ ✅ ✅ ✅ |
