Fluent Commerce Docs

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Content in this track:

Introduction to Support & Operations

Support & Operations Activities

Getting Help with Support & Operations

End Of Track

Content in this track: Support and Operations Labs

Essential knowledge

Authors:

Nandha Balaguru, Dominik Malzacher, Cille Schliebitz, Anita Gu

Changed on:

22 Apr 2025

Overview

These labs focus on debugging and troubleshooting Fluent Order Management workflows using GraphQL and Postman. They cover retrieving detailed data for orders and waves, analyzing audit events, identifying stuck orders, and re-triggering workflows. The goal is to simulate real-world scenarios, understand workflow paths, and resolve issues efficiently.

Key points

Full Order/Wave Retrieval: Use GraphQL to fetch information on orders and waves.
Audit Events: Use Event APIs to trace orchestration activities and errors.
Status Transitions: Track entity status changes and time spent in each state.
Stuck Orders: Identify and troubleshoot orders stuck in specific statuses.
Workflow Debugging: Simulate workflow breaks and resolve stuck entities.
Re-trigger Rulesets: Fix workflows and re-trigger events for stuck orders to progress.

Request a Training Account

You will need a Fluent Commerce Training Account to complete the Knowledge Tracks labs. Follow the steps in the guide to receive one.

Download Postman Collection

To proceed with the Lab, you need to download the required Postman Collection associated with this course. Right click this link to save the file to your computer

Lab: Debugging Orders with GraphQL

Sometimes it is helpful to retrieve the full Order, with all its related & child entities, in order to determine what may or may not be going on. This is particularly useful when there are reports of an issue with order processing, or when unexpected behaviour occurs.In this lab, you will retrieve a full Order graph using an Order ID and an Order Ref.

Task 1: Get Full Order Information by Id

Postman Application v. Browser

We do not recommend using the web-only version of Postman, it can result in CORS (Cross-Origin Resource Sharing) errors during the course labs!

In Postman, authenticate the FC_FASHION Retailer User
Next, view the request body for the Get Full Order By ID request
- Notice all of the related entities and sub-entities retrieved in a single request
Execute the request (click Send), and review the response

Task 2: Get Full Order Information by Ref

View the request body for the Get Full Order By Ref request. Notice all of the related entities and sub-entities retrieved in a single request.
Execute the request (click Send), and review the response.

Lab: Debugging Waves with GraphQL

Sometimes it is helpful to retrieve the full Wave, with all its related entities and children, in order to determine what may or may not be going on. This is particularly useful when there are reports of an issue with a wave processing or unexpected behaviour occurs.In this lab, you will retrieve a full Wave graph using a Wave ID.

Task: Get Full Wave Information by Id

In Postman, authenticate the FC_FASHION Retailer User.
Next, view the request body for the Get Full Wave By Id request. Notice all of the related entities and sub-entities retrieved in a single request.
Execute the request (click Send), and review the response.

Lab: Debugging with Audit Events

Events are the best way to know what has happened during the orchestration of an entity. In this lab, you will learn how to use the Event API to retrieve useful information for debugging.

Task 1: Review Event API Parameters

In Postman, click on the Fluent Learning - TC-SO1 Labs > TC-SO-L03: Orchestration Audit Events Lab > Search Activity Events & Audit Logs request:

Make sure the Params tab is selected, and look through each parameter and the associated description:

Why are all Params disabled?

The "Value" column is deliberately empty, and all Params are disabled. You will use these in the later labs.

You can also see the fully generated documentation for this API by clicking on the Documentation button on the right hand drawer in Postman, shown below:

In the following tasks, you will see how to use different combinations of these parameters to retrieve and identify useful information for debugging or insights.

Task 2: Retrieve Events for an Order

In this task, we'll show you how to retrieve all events for a specific Order, including all the sub-entity events, and then narrow it down to just a single entity.

Authenticate using the FC_FASHION Retailer User Auth request
Click on the check box for the `context.rootEntityType` parameter to enable it, and type ORDER in the value field
Enable the check box for the `context.rootEntityRef` parameter, and enter a valid Order Ref for a completed Order in your Fluent OMS Account (e.g. CC_123)
Click on the Send button to send the request. You should see a list of events returned all with a Root Entity Type and Ref matching the parameters provided. Note: Results are displayed in `generatedOn desc` order.
Click on the Visualize tab in the Response view to see a more readable list of the results:

How are Results sorted?

Results are displayed in `generatedOn` descending order.

Notice all events for the Order Workflow entities are returned, including Fulfilment, Article, and Consignment (if an HD Order is being viewed)
Notice how you can view the Event Generated On timestamp, the Root Entity info, the Entity info, the Event Name, the Event Type, Category, and Status, as well as the Attributes and Retailer ID
Next lets narrow down the list to a single entity, e.g. Fulfilment...
Enable the `context.entityType` parameter and set the value to FULFILMENT
Take note of a Fulfilment ID or Ref related to the existing Order, and enable the relevant parameter in Postman and paste the value:
Notice now, that only the Fulfilment events are returned. This is helpful when there may be a specific Fulfilment with an issue, and you are looking to see what has occurred through the processing of that Fulfilment.

Task 3: Understanding Entity Status Transitions

In this task, we'll show you how to retrieve the entity status transitions for a specific entity. This is helpful when debugging or identifying what status an entity is in, which statuses it was in prior, how long it has taken to reach that status, and how long it has remained in that status.Let's stick to the same entity as the previous task, the Fulfilment.Status changes for an entity should only ever be performed using a SetState(core) rule. This way, the status changes are correctly tracked within the Workflow Engine. This is helpful for filtering the Event API down to just these events.

Enable the `name` parameter in Postman, and set the value to [YOUR_ACCOUNT_ID].core.SetState, where [YOUR_ACCOUNT_ID] is your training Account ID, e.g: FCTRAINAU123.core.SetState
Click Send to retrieve the results, and look at the Attribute props value to see the status changes:

New Accounts Use Core Module SetState Rule

Any new account created will use `SetState` rule from the Core Module, instead of `ChangeStateGQL` rule from commonv2 plugin.

In the example in the Screenshot above, the Fulfilment which started out with a status of CREATED transitioned to PENDING_PAYMENT then AWAITING_WAVE --> ASSIGNED --> PICK_PACK --> FULFILLED --> AWAITING_CUSTOMER_COLLECTION --> COMPLETE.With these Events, you can trace the status transitions for the Entity, the time between each status change, overall time, and time spent in each status.

Task 4: Understanding Workflow Path

In this task, we'll show you how to retrieve the path taken through the workflow for a specific entity. This is helpful when debugging or identifying why or how an entity was processed.Let's stick to the same entity as the previous task, the Fulfilment.To identify the workflow path, we can filter the Events to the Rulesets, since these describe what rulesets were executed in what order, and at what time. To do this, we will filter the query to the ruleset Event category.

Firstly, disable (uncheck) and clear the value for the name parameter used in the previous task, as we no longer need to filter by name
Enable the category parameter, and set the value to ruleSet

This will display all Rulesets executed, with most recently executed ruleset at the top. You can also see the status and timestamps for each Ruleset execution.

Ignore events named STATE_CHANGE

Events named STATE_CHANGE are legacy and can be safely ignored.

Task 5: Errors & Exceptions

There are 3 different ways a problem might be reflected in the events:

A FAILED Status on an ORCHESTRATION Event, which means that an exception occurred during processing of that Event
A NO_MATCH Status on an ORCHESTRATION Even, which means that an Orchestration Event was not executed successfully, due to not finding a matching Ruleset
An exception Event Category, which is an Audit log of the full stack trace of an Exception which occurred during processing of an Event

Locating these errors is as simple as querying with a filter on either the Event status or category. Combining these queries with a time range can help to identify issues that occurred within specific windows of time.

Lab: Finding Stuck Orders

In this lab, you will use a GraphQL query to search for Orders that have been in a specific status for longer than expected. This is helpful for identifying when Orders (or other orchestratable entities) are possibly stuck in a transient status and not continuing processing as intended.First we need to simulate an Order getting stuck in a status. To do this, we will temporarily break the workflow so that the Order does not progress beyond the RECEIVED status.

Log in to Fluent OMS with the `fc_fashion_admin` Retailer User
Navigate to the Orchestration Modeller, and open the Order HD workflow
Click on the first green ruleset marker, and click into the CREATE Ruleset
In the SendEvent Rule that is sending a CheckOrderCoordinates event, change this value to BREAKCheckOrderCoordinates, and commit changes

Simulating Broken Workflow: Order Stuck in RECEIVED

This is to simulate a broken workflow, where the Event being produced will not match any ruleset, and the Order will remain stuck in RECEIVED status

Now in Postman, send in an HD Order using the TC-SO-L04: Find Stuck Orders Lab > Create HD Order request.
Go to Fluent OMS > Orders, and locate the Order which should be in a RECEIVED status. Usually, after 30 seconds, the Order should progress to BOOKED and then PICK_PACK
After a few minutes, confirm that the Order is still in a RECEIVED status, and has not progressed

Navigate to Insights > Events and look for the BREAKCheckOrderCoordinates event. Click on the record, and notice the Event Status is NO_MATCH, as expected by our changes

We will now go back to Postman and use a GraphQL query to locate this stuck order
Select the Find Orders in State Longer Than request, and click on the Pre-request Script tab on the request pane
Notice the JavaScript variable called `durationInMinutes` which is currently set to 30. Since we don't want to wait for 30 minutes to use this query, change the value to 2 and save the request using the Save button

Click Send to execute this request, and review the results

This query is useful for identifying Orders that may be stuck, and allow you to look for the root cause. In this case, we know the root cause, since we deliberately simulated this invalid workflow, however there may be other reasons why Orders get stuck, such as failed integration events, etc.

Lab: Retrigger Ruleset Lab

In this lab, we'll first fix the issue with the workflow introduced in the previous lab, and then re-trigger the correct Event to allow the Order to continue processing as normal.

Go back to the Orchestration Modeller, Order HD workflow, and open the CREATE Ruleset for editing
Change the BREAKCheckOrderCoordinates parameter back to CheckOrderCoordinates, and commit changes
This has resolved the workflow for new incoming Orders, but our stuck Order will remain stuck until we re-trigger processing with the correct Event
In Postman, go to TC-SO-L05:Retrigger Ruleset Lab > Retrigger Ruleset request
In the Body, replace the tokens with the relevant information for the stuck Order, and make sure to set the name to CheckOrderCoordinates:

Execute this request, and go back to Fluent OMS to confirm if it has moved to PICK_PACK as expected:

By re-triggering the correct Event for the Order, the Order is now no longer stuck, and has progressed through processing

Knowledge Tracks Related To This Topic

Support and Operations

Introduction to Support & Operations

Support & Operations Tools

Support & Operations Activities

Getting Help with Support & Operations

Support and Operations Labs

Content in this track:

Introduction to Support & Operations

Support & Operations Tools

Support & Operations Activities

Getting Help with Support & Operations

Support and Operations Labs

End Of Track

Support and Operations Labs

Support and Operations Labs

Overview

Key points

Download Postman Collection

Lab: Debugging Orders with GraphQL

Task 1: Get Full Order Information by Id

Task 2: Get Full Order Information by Ref

Lab: Debugging Waves with GraphQL

Task: Get Full Wave Information by Id

Lab: Debugging with Audit Events

Task 1: Review Event API Parameters

Task 2: Retrieve Events for an Order

Task 3: Understanding Entity Status Transitions

Task 4: Understanding Workflow Path

Task 5: Errors & Exceptions

Lab: Finding Stuck Orders

Lab: Retrigger Ruleset Lab

Nandha Balaguru

Contributors:

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links