Adding a State to your Workflow with User Action

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

How-to Guide

Extend

Author:

Fluent Commerce

Changed on:

23 June 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}

Language: json

Name: Status sample

Description:

Sample payload of a status

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    },

Language: json

Name: Add a new status into CC order workflow for fulfilment entities

Description:

Sample payload of a status

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},

Language: json

Name: CS HOLD ruleset in CC order workflow

Description:

Ruleset to move fulfilment from AWAITING_WAVE to CS_HOLD Status.

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:

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.

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