Fluent Commerce Docs

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Content in this track:

Workflow Framework and the Rules SDK

Overview of Workflow Framework

Workflow Scenario (Recommended Practice)

End Of Track

Content in this track: Workflow Event Execution

Essential knowledge

Author:

Fluent Commerce

Changed on:

29 Aug 2025

Overview

In this module you'll learn about how events are executed on the Fluent platform.

Key points

A workflow represents the journey of a root entity, and related sub-entities, through various stages in its lifecycle. These stages are represented by statuses.
Rulesets are collections of rules forming tasks within a process, dictating movement from one state to another based on business logic.
When an orchestration event is received, the Workflow Engine loads the associated workflow and searches for a matching ruleset based on event name, entity type, subtype, and status. Matched rulesets are executed, and may produce additional events to trigger further rulesets in sequence.

Key Concepts

In this module, you'll learn about how events are executed on the Fluent platform. Let's begin by recalling some important concepts. Refresh your knowledge of workflows, states and rulesets:A Workflow represents the journey of a Root entity and any related Sub-entity through various stages in its lifecycle, from initiation to its completion. The lifecycle stages through which the entities move within the workflow are represented through States.Rulesets are a collection of one or more Rules which are combined to form a single task within a process. Rulesets represent business logic within the workflow, including movement from one state to another.

Orchestrateable entities and contexts:

A workflow is named by its Root Entity (1) and includes the lifecycles of its Sub-Entities (2)Event Reference (3) is the entity type value used to post an event to a specific entity.Platform CREATE Event? (4) indicates which entities the Fluent Platform automatically generates a CREATE event for, off the back of a Create mutation. When you create a new Order using the createOrder mutation, the Fluent platform will generate a CREATE event for that entity to allow the triggering of workflow-based business logic for that new Order.Not all entities have a platform-generated CREATE event, however if it is an orchestrated entity, an event can be generated by an external system to trigger the workflow.

Root Entities (1)	Sub-Entities (2)	Event Reference (3)	Platform CREATE Event? (4)
Location	Location Wave	LOCATION WAVE	❌ ✅
Order	Order Fulfillment Article Consignment	ORDER FULFILMENT ARTICLE CONSIGNMENT	✅ ✅ ✅ ✅
Fulfillment Options	Fulfillment Options Fulfillment 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 Fulfillment	RETURN_ORDER RETURN_FULFILMENT	✅ ✅
Billing Account	Billing Account Credit Memo Invoice Payment Payment Transaction	BILLING_ACCOUNT CREDIT_MEMO INVOICE PAYMENT PAYMENT_TRANSACTION	✅ ✅ ✅ ✅ ✅

Example of root and sub-entities:

Product Catalogue workflow contains the lifecycles for the Product Catalogue root entity, products and categories.
Order Workflow contains the lifecycles for Order, Fulfilment, Consignment and Article.

Recommended approaches

For creating or updating sub-entities the recommended approach is to send an event to the root entity context on the workflow, and allow this to upsert the entity and handle any pre- and post-condition logic.
For updating root entities, the recommended approach is to send an event, rather than use the update mutation directly. This is so that you can cater for any other orchestrated business logic inside the workflow as part of an update.

Example of a sample event:

A JSON structure of a sample event is shown below and contains a number of attributes — this is the format of the Event API.Entity type is Order, but it could also be Fulfillment, Articles or Consignment.Event “name” is CancelOrder. It’s quite clear that it corresponds with the matching ruleset and encapsulates all of the business logic required to cancel an order.

1{
2    "name": "CancelOrder",
3    "retailerId": "1",
4    "entityId": "1234",
5    "entityRef": "ON-1234",
6    "entityType": "ORDER",
7    "rootEntityType": "ORDER",
8    "rootEntityId": "1234",
9    "rootEntityRef": "ON-1234",
10    "attributes": {
11                "cancelReason": "Stolen Credit Card"
12            }
13
14}

What happens when an orchestration event is received?

When an orchestration event is received, the Workflow Engine loads the workflow associated with the entity defined in the event context. Next, it searches for a ruleset using the primary Ruleset matching criteria, as follows:

Event Name = Ruleset Name
Entity Type - e.g: Type = ORDER
Entity Subtype - e.g: Order.type = HD
Entity Status - e.g: Order.status = BOOKED

Once the Ruleset is matched the Workflow Engine will execute it plus any subsequent rulesets. The rules within the ruleset may produce additional flow control events — we refer to these as inline events — to in-turn trigger additional Rulesets as part of the same action execution thread. These additional Rulesets will be matched and queued for execution in sequence after the initial Ruleset has been completed.

Rule execution

Rules within a Ruleset are executed sequentially

How the Workflow Engine processes an orchestration event

An example of an orchestration Event being processed inside the Workflow Engine is shown below.

Knowledge Tracks Related To This Topic

Workflow Framework

Workflow Framework and the Rules SDK

Overview of Workflow Framework

Recap of Workflow Framework

Working with Workflows

Working with Rulesets

Composing Workflows

Logical Gates in Workflows

Managing Workflow States

Workflow Process Flows

Workflow Scenario (Recommended Practice)

Workflow Event Execution

Workflow Framework Labs

Content in this track:

Workflow Framework and the Rules SDK

Overview of Workflow Framework

Recap of Workflow Framework

Working with Workflows

Working with Rulesets

Composing Workflows

Logical Gates in Workflows

Managing Workflow States

Workflow Process Flows

Workflow Scenario (Recommended Practice)

Workflow Event Execution

Workflow Framework Labs

End Of Track

Workflow Event Execution

Workflow Event Execution

Overview

Key points

Key Concepts

Orchestrateable entities and contexts:

Example of root and sub-entities:

Example of a sample event:

What happens when an orchestration event is received?

How the Workflow Engine processes an orchestration event

Fluent Commerce

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links