Adding a State to your Workflow with User Action

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Extend

Author:

Fluent Commerce

Changed on:

14 Sept 2025

Key Points

It’s possible to add a new state to an existing workflow by adding a new status to the `Statuses array` of the workflow JSON.
Create a simple User Action to allow the user to change the status.

Steps

Adding a State to your Workflow

Statuses within the workflow are represented by white rounded rectangles whose border colour matches the lifecycle phase they belong to.

For example, within the Booking phase, the Order status could be:

Created
Awaiting Payment
Fraud Check
Booked

Similarly, within each of the other phases, there could be multiple different states in which the entity might travel.

Tip

While all Fluent Entities begin their lifecycle at the `CREATED` state, all other statuses are configurable and in line with your specific workflow logic.

Note

You can only add new States to a Workflow via the JSON document.

Adding a State via the Workflow JSON

To add a State to a Workflow JSON, you must add a new Status to the `statuses` array of the Workflow JSON that matches the schema outlined below.

Status schema

JSON Key	Value Type	Mandatory	Description
name	String	YES	Name of the status.
entityType	String	YES	Name of the entity the status belongs to.
category	String	YES	Name of the category the status belongs to.There are four possible values: BOOKING FULFILMENT DELIVERY DONE

Status sample

1 {
2  "statuses": [
3    {
4      "name": "{{name}}",
5      "entityType": "{{entityType}}",
6      "category": "{{category}}"
7    }
8  ]
9}

Tip

States will not appear in the Workflow graph until they are referenced by a Ruleset.

Here is an example of how to add a new manager Hold status to an Order:

Business Use Case

As a Customer Service Representative (CSR), I want to see a feature that sets the CC fulfilment on hold if the store staff have not processed the order/fulfilment.

Step 1: go to the workflow modeller to view the CC order workflow. In the statuses section, add a new status called CS_HOLD

1
2    {
3      "name": "HOLD",
4      "entityType": "FULFILMENT",
5      "category": "BOOKING"
6    },

Step 2: Add a new ruleset that provides the user action to the OMS Webapp, which allows moving the fulfilment to CS_HOLD status if the fulfilment status has not passed the AWAITING_WAVE stage:

1{
2    "name": "CSHOLD",
3    "type": "FULFILMENT",
4    "subtype": "CC_PFS",
5    "eventType": "NORMAL",
6    "rules": [
7        {
8            "name": "{{AccountId}}.core.SetState",
9            "props": {
10                "status": "CS_HOLD"
11            }
12        }
13    ],
14    "triggers": [
15        {
16            "status": "AWAITING_WAVE"
17        }
18    ],
19    "userActions": [
20        {
21            "context": [
22                {
23                    "label": "Hold the Fulfilment",
24                    "type": "PRIMARY",
25                    "modules": [
26                        "adminconsole"
27                    ],
28                    "confirm": true
29                }
30            ],
31            "attributes": []
32        }
33    ]
34},

Inventory Reservation

This feature will move the fulfilment aside so that STORE user will not able to process the order from the fluent STORE app. The reservation of the fulfilment lines still in placed as once business process is completed, this fulfilment can reset to AWAITING_WAVE status to continue the order jounery.

update order workflow

The user can also to perform the above steps via API call to retrieve the current workflow (GET: {`GET:{{fluentApiHost}}/api/v4.1/workflow/{{retailer_id}}/ORDER::CC`) , update the workflow offline and upload the workflow (`PUT:{{fluentApiHost}}/api/v4.1/workflow`).

Step 3: Logon to OMS, then go to order -> fulfilment screen. User should able to see a new user action "HOLD THE FULFILMENT" button on the top right-hand corner: No alt provided

unHold the fulfilment

By following the above steps, you can easily to add a ruleset that allow the CSR to move fulfilment status from CS_HOLD back to AWAITING_WAVE.

Update order status

The same trick can be used to update the order status if there is a requirement that the order status be reflected if the fulfillment is set to HOLD.

Except as otherwise stated in the Extend Knowledge Content site policy, the content on this page is licensed under the Creative Commons Attribution 4.0 Licence, and any code samples that appear on this page are licensed under the Apache 2.0 Licence, unless any code sample forms part of the Fluent Order Management Platform code. Neither of these licences apply to any content on any other page that can be reached via a link on this page unless otherwise specified on that other page. If you wish to use any of the Extend Knowledge Content, you must do so in compliance with the licenses referred to above and the Extend Knowledge Content site policy, including attribution in the manner set out on this page.

Adding a State to your Workflow with User Action

Key Points

Steps

Adding a State to your Workflow

Adding a State via the Workflow JSON

Status schema

Status sample

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links