Orchestration
- Vincent Vila
- Daniel Jones (Deactivated)
- Laure Koppe-Verley
- 1.1 Principles
- 1.2 Ruleset Chainings
- 1.3 Rulesets
- 1.4 How the rules work
- 1.5 Rule definition
- 1.5.1 Filters
- 1.5.2 Dynamic tags
- 1.5.3 Timeout
- 1.5.4 Stock
- 1.5.5 Number of candidates
- 1.5.6 Automatic claiming
- 1.6 Rule progression
- 1.7 Rules calendars
- 1.8 Ruleset stock requests
- 1.8.1 Setting stock requests
- 1.8.2 Unified stock
- 1.8.3 Detailed stock
- 1.8.4 Default stock requests
- 2 Automatic re-orchestration upon available stock
Principles
OneStock orchestration rules are shown and can be modified directly in the backoffice of OneStock.
Here is a video to introduce these pages in the backoffice:
For more information on orchestration : Order Orchestration
Ruleset Chainings
In this page, you will be able to create and modify ruleset chainings.
The ruleset chaining consists in a sequence of rulesets, which consist themselves in a sequence of orchestration rules. It allows calling multiple times the same ruleset, or calling rulesets that are using different stock requests.
It also allows specifying and forcing the check of the delivery promise during the orchestration. If you decide to do so, OneStock will check if each candidate selected by an orchestration rule is able to deliver on time to the destination, based on the configuration of the delivery promise. If a candidate is not able to deliver on time, it will be automatically discarded by the orchestration engine.
To manage delays that may occur, it is possible to configure a delay authorized to deliver the order. This tolerance is configured in the ruleset chaining.
For example, you may define a ruleset chaining that:
execute a ruleset and tries to match the promised delivery date
then, if the order couldn’t be allocated after the execution of the first ruleset, execute the same ruleset with a tolerance of 2 days of delay on the promised delivery date
finally, execute another ruleset with a tolerance of 5 days of delay.
Rulesets
The orchestration rules of each ruleset can be modified in the OneStock backoffice, if the user is authorised. The orchestration section shows a list of existing rulesets. You can click on the pen button on the right side to open and modify the ruleset.
It is strongly recommended to test a modification of the orchestration rules on the qualification environment before applying the modification in production.
A change to the orchestration rules will not apply immediately. The new rules will not be applied until midnight CET. It is still possible to delete the change or modify the new configured rules before they apply.
You can see pending modifications on the Orchestration page:
The trash button will delete the modification (and keep the current version). The pen button allows modifying the new version before it applies. The check allows to force applying the new version immediately rather than waiting for midnight.
Each ruleset has an ID (that cannot be modified), a name and is associated to a stock request for unified stock and a stock request for detailed stock. These requests are optional but default requests will be used if not specified. These stock requests define what stocks will be considered during orchestration.
The user can add, modify or delete each rule in the ruleset, and change the order and therefore the priority of the rules.
The modification of rules impacts all existing orders. Thus, all current orders being orchestrated by the modified ruleset will be impacted. Their current rule is identified by its number (the number displayed on the left in the ruleset list) and remains the same after the modification, even if the rule in question has been moved.
If rules are removed from the ruleset, a current order in a rule whose number no longer exists will be in “rules over” (see below about “rules over”).
When an order enters in the orchestration ruleset, OneStock will first check if all items to be orchestrated are available in stock, using the unified stock request associated to it. If there is no stock, specific action can be taken, usually the missing item(s) will be cancelled.
How the rules work
The orchestrator works at the order level, not order line by order line. It therefore always evaluates all items in the order (minus items already shipped or cancelled). If the order has multiple items, the orchestrator will run through the set of rules until it can serve all of them (from one or more stock locations, depending on the configured rules and the stock availability).
Each rule has a name to describe it briefly and explicitly. The name has no impact on the application of the rule.
The rule consists of :
a filter which determines which stock locations are eligible for the rule, based on the items in the order and the stocks in these stock locations,
a timeout which allows you to manage exceptions by determining the maximum time to wait in this rule before switching to the next rule if there are candidates but they do not claim the order,
additional options, detailed below.
Each candidate of a rule is a set of one or more stock location(s) that can serve an order. For example: for an order containing 3 items A, B and C, a candidate will be the allocation of items A and B to warehouse 1 and item C to warehouse 2.
The execution of a rule can return:
0 candidate: in this case, the orchestrator immediately switches to the next rule (without waiting),
1 or more candidates:
For each candidate, the stock location(s) corresponding to the candidate are assigned the order or the parts of the order they can process.
The order is therefore offered to all candidates simultaneously.
If a stock location picks up the part of the order that has been assigned to it, the orchestrator will reapply the current rule to update the candidates for the rest of the order.
If the order has not been fully claimed after the defined timeout, the orchestrator will switch to the next rule.
Rule definition
Filters
The filter of a rule is a set of conditions combined with ANDs and ORs to determine the candidates eligible for the rule.
Each of these can be a condition on:
Filter configuration border cases
No filters. Orchestration is done using the chaos mode. There is no notion of candidate (so no skipping to the next rule if no candidates for the entire order are found), all endpoints are proposed to claim whatever they can, there is no esurance that the order will be entirely fulfilled, high probability of partial fulfillement.
Not recommended in a scenario without a custom action as the order will be proposed to all stock locations which might result in a very elevated number of splits and possible performance issues.
Filters but no source filter. The orchestrator is eco-friendly, so a maximum of 5 sources is applied. If we want to consider more, we must apply a source filter greater than 5.
Dynamic tags
OneStock can automatically calculate several different dynamic tags.
Dynamic tags are designed to provide real-time data and insights to prioritize stores and orders, encourage reliability, and optimize the fulfillment process.
Here are examples of tags that can be calculated by OneStock (they are not activated by default, an additional configuration is required to turn them on):
Timeout
The timeout applies if all or part of the order has not yet been claimed and the current rule has candidates. Once the timeout has elapsed, the orchestrator will move to the next rule and the current candidates will no longer be able to claim the order (unless they are still valid candidates in the next rule).
The timeout only takes into account the working hours defined in the rule timetable (section “Timetable” at the bottom of the screen). You can define several schedules, but only one will be taken into account in the timeout of a given rule.
If no timeout is defined in the rule, OneStock will consider a timeout of 7 days.
The timeout of the rule is defined in 2 ways:
Rule: this is the time spent in the rule,
If the items of the order are all claimed and are unclaimed later on, the total time spent on the rule takes into account the time while it was claimed.
For example: if you set a timeout of 2 hours on your rule and you enter in this rule at 8am. If the order is fully claimed at 9am and then unclaimed at 11am, (3 hours after entering the orchestration rule), it will immediately move to the next rule.
Order: this is the time elapsed since the order was imported into OneStock.
As soon as the two timeouts have both elapsed, if all or part of the order has not yet been claimed, the orchestrator moves on to the next rule.
Stock
You can define here what stock type(s) must be considered to find candidates. The stock are always stocks coming from the unified and detailed stock requests of the ruleset, so you must make sure that the stock type you select is included in the stock request as well.
By default, only the stock type “on_hand” is considered.
In addition to selecting stock types, you can define the date range to consider for future stocks.
Number of candidates
You can define a minimum and maximum number of candidates applicable for this rule.
Minimum number of candidates: if the filters of the rule found less candidates than this minimum number, the orchestration will move immediately to the next rule. It ensures that there will be enough candidates to have some competition and multiple candidates to fulfil the order.
Maximum number of candidates: it the filters of the rule found more candidates than this maximum number, only the best candidates will be selected to have no more candidates than this maximum.
To select the best candidates, you need to define sorting criteria. OneStock orchestration engine will sort the candidates accordingly and keep the first ones.
You can define a first sort criteria, which is a dynamic tag (see paragraph above with their descriptions), a sort order (ascending or descending) and a threshold.
This threshold allows to consider close values as equal and to switch to the following sorting criteria. If you define a threshold n, every values between 0 and n are considered equal, between n and 2 x n as well, and so on. For example, if you define a threshold of 10 minutes on the preparation time and the next sorting criteria is on the reliability, it means that if one store has a preparation time of 42 minutes and another one has 48 minutes, they will be considered as equivalent in terms of preparation time and they will be sorted according to the next criteria, the reliability.
Automatic claiming
This option allows the order to be claimed directly by the chosen candidate.
For warehouses
Automatic claiming of warehouse
Placed Claimed_warehouse
This option is mandatory if the warehouse preparation process is not done on OneStock interfaces. In the line item workflow, the state claimed_warehouse should exists.
The orchestrator evaluates the candidates that meet the filter conditions. However it is preferable not to set a filter or only on the number of sources since the filter will be applied on warehouses anyway.
If one or more warehouses are candidates, the candidate warehouse with the most items will automatically claim the items it has. The line item will move from “placed” to “claimed_warehouse”.
Unlike the option "Automatic claiming and dispatch from warehouse", the items will not be marked as being dispatched from the warehouse. In this case, a confirmation of the dispatch from the warehouse is expected.
Depending on the integration in place to communicate with the warehouse, a message will be sent to it informing of the items to be prepared. The warehouse will then need to confirm that the items have been shipped.
The orchestrator then moves directly to the next rule, even if other stock locations (stores or warehouses) are valid candidates. If no warehouses are candidates, the orchestrator moves directly to the next rule.
Automatic claiming and dispatch from warehouse
Placed FULFILLED
This option acts exactly like the previous one, unlike line items will be automatically dispatched from the warehouse. This option should only be used if no confirmation of shipment is expected from the warehouse.
Depending on the integration set up to communicate with the warehouse, a message will be sent to the warehouse to inform it of the items to be prepared and shipped.
The orchestrator then moves directly to the next rule, even if other stock locations (stores or warehouses) are valid candidates. If no warehouses are candidates, the orchestrator moves directly to the next rule.
For stores
Automatic claiming of destination store
Placed Claimed
This option force the orchestrator to only take into account the destination store of the order. This option should only be used on Click&Collect or Reserve&Collect orders. Note that it is not necessary and not recommended for Reserve&Collect orders.
If this store is a candidate, the corresponding items are automatically claimed. They will appear on the store's “Bag” page for Click&Collect orders or on the “Reserve” page for e-bookings (this may vary depending on the store configuration).
The orchestrator then moves directly to the next rule, even if other stock locations (stores or warehouses) are valid candidates. If the destination store is not a candidate, the orchestrator goes directly to the next rule.
Automatic claiming of preferred stock location
Placed Claimed
This option force the orchestrator to only take into account the customer’s preferred store.
If this store is a candidate, the corresponding items are automatically claimed.
The orchestrator then moves directly to the next rule, even if other stock locations (stores or warehouses) are valid candidates. If the preferred store is not a candidate, the orchestrator goes directly to the next rule.
For stores or warehouses
Automatic claiming of a specific stock location
Placed ANY STATUS
This option force the orchestrator to only take into account stock locations that meet the chosen parameter, so that it automatically claims the order. Four parameters can be set :
ID : refers to the id of the stock location in the database.
Preferred stock location : This parameter acts exactly like the “Automatic claiming of preferred stock location” one, except that the order line status after claiming can be chosen.
Order destination : For Click&Collect and Reserve&Collect orders only. This parameter acts exactly like the “Automatic claiming of destination store” one, except that the order line status after claiming can be chosen.
Tag : refers to any tag visible in the detailed “Stock locations” page. The nomenclature of the tag is in json format and must be filled in as follows: [{"tag":[["specific_value"]]}]. See example below.
Rule progression
For a given order, the orchestrator executes one rule at a time. When it moves to the next rule, it will impact all future orchestrations of the order.
For example: if a store picks up part of the order while on rule 1, the orchestrator will continue to run for the rest of the order. It can then move on to rule 2 in the event of a timeout. If the store leaves the part of the order it had claimed, the order will be re-orchestrated by applying rule 2 and not rule 1.
When the orchestrator exits the last rule of the ruleset without having been able to orchestrate the whole order, it goes into "Rules over". A notification is triggered and, depending on the implementation, it can trigger specific actions: sending an email, cancelling unorchestrated items, etc. These actions are not configurable in the DIY backoffice interface.
When the entire order has been captured, the orchestrator pauses for that order. If the order is then unclaimed, the orchestrator takes over and checks if the timeout of the rule that was running has been exceeded (by counting the total time between the entry in the rule and the time the order was left). If this time is exceeded, the orchestrator moves on to the next rule and will then start counting down the time for that rule.
Rules calendars
The Rules Calendars section is located at the top right of the orchestration page. This section allows to define the time slots during which the orchestration rules will run.
On the first page you can see the list of existing calendars. By clicking on one of them, you can see a weekly view of the calendar. You have the possibility to add or modify any time slot. You can also create a new calendar from scratch after defining its name and timezone.
Our recommendations:
You should create at least 1 timetable for your stores, and 1 timetable for your warehouses:
Stores: The calendar should be as close as possible to the store's opening hours, for e.g. Monday to Saturday - 9.00am to 8.00pm. This avoids that the rules are scrolled during the night, which would be unproductive because the salespeople in stores cannot claim them.
Warehouses: If the orchestration rules doesn’t allow warehouses to claim automatically, then you should create an active calendar 7 days a week, 24 hours a day. When the rule is executed, the order will be directly assigned to the warehouse regardless of the time.
If you manage several countries with different time zones, you should create at least 1 calendar per country.
Ruleset stock requests
Stock is retrieved during orchestration at a unified and detailed level. Unified stock is checked before each orchestration attempt, if no stock is available, out of stock lines are transitioned to the set out of stock state and remaining lines are orchestrated. Once unified stock has been checked, detailed stock is retrieved.
Setting stock requests
Requests can be set per ruleset.
Unified stock
Stock location filtering
Unified stock will be retrieved using the unified stock request. In the case of Click & Collect order (order.type contains ckc), the orchestrator will apply a stock location filter to recover only stock of the destination (collection store). As a result, only destination’s stock will be recovered for stock aggregates containing "endpoint_filter.use_requested_ids" : true. During orchestration of other order types, unified stock is recovered without filtering by stock locations.
Item filtering
Also, in some scenarios, stock to be considered in different stock locations is dependant of the dispatch method. A store might be able to ship and fulfil for collect a tea set but in the case of a fridge only be able to fulfil for collect. To answer this type of requirements, we must take advantage of stock requests item filters, by setting an item request. Item request allow to apply filters to items when retrieving their stock. If the item does not match the filters, it’s stock won’t be returned.
item_filter.use_requested_ids : true
Detailed stock
Detailed stock will be retrieved using the detailed stock request. Considered stock locations are those which match the rule filters and have the ship from store module active (ffs). In the case of a click & collect order, the destination is also considered.
Default stock requests
By default, the orchestrator uses the requests named "detailed" and "unified". The "default" value triggers the use of this requests.
Automatic re-orchestration upon available stock
Out of stock lines can be automatically re-orchestrated once stock becomes available. All stock changes are monitored (imports by API and file, cancelled reservations, cancelled dispositions, etc). Stock will be consideres as available if the stock becomes greater than 0 when requesting stock with the unified request of the order's current orchestration ruleset.
For a line item to be automatically reorchestrated, it must be in an out-of-stock destination state and the order must be flagged as auto orchestrable (order field on_available_stock.auto_orchestrable : true).
The workflow must contain the following transition for auto orchestration upon available stock to work
not_in_stock:
transitions:
global_reservation_attempt: # Can either be triggered manually or when stock becomes available if the order is auto-orchestrable
actions_after:
- type: update_reserved_stock # Increase the reserved stock
parameters:
creation: true
- type: update_line_items_state
global_reservation_attempt:
transitions:
not_in_stock: # Returns to not_in_stock
auto: true
conditions:
- type: "!has_global_reservation" # If the stock increase has failed
placed:
auto: true
conditions:
- type: "has_global_reservation" # If the reserved stock is ok
actions_after:
- type: orchestrate # We can reorchestrate