Lab: Support and Operations

Download Postman Collection

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

• 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:

• 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:

`generatedOn`

• 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:

`SetState`

`ChangeStateGQL`

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.

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

• 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