...

{
    "_id" : ObjectId("618225724bbd51a42c47ce10"),
    "cutoffs" : {
        "prep_time_sfs" : 1636030800,
        "carrier_pickup" : 1636030800,
        "without_always_at_start" : 1636027200,
        "purchase_cutoff" : 1636027200
    },
    "delivery_method" : "STD",
    "delivery_route_id" : "GB_GB_DPD_Standard",
    "eta_end" : 1636232400,
    "eta_start" : 1636117201,
    "expired" : false,
    "pickup_day" : 1635984000,
    "sales_channel_id" : "web",
    "version" : 0,
    "endpoint_ids" : [ 
        "190", 
        "157"
    ],
    "public_id" : "5279a9cc-3c6b-11ec-bf59-02420a0001f3",
    "unavailable_endpoint_ids" : []
}

...

When are milestones

...

To exploit milestones during order's treatment, milestones must be used in the workflow. This allows to set milestones - considered that it has been reached - and set alerts if not reached in time.

Workflow

1. set_milestone : set the achieved milestone. If empty, without_always_at_start milestone is set (generally de case when initiating milestones in the graph).
   For the set_milestone action to work, the line item group must have stock location ID assigned. As a result, when placing a set_milestone in the workflow it must be placed after assign origin actions.

   1. To make use of milestones, they must be stored for the order at each of its line_item_groups claimed transition. To do so, the action set_milestone has to be set in the claim transition of the line_item_groups, if any..

   2. When recomputing, solutions with non-achieved milestones dates in the future (greater than now) will be considered as valid options. Those with dates in the past, will not be considered.

2. set_milestone_alert : Schedule alerts to be triggered at milestones cutoffs (plus a delay)

   1. Notifications can be scheduled to be triggerd at the time of milestones cutoffs (plus a certain delay). When triggered, a validity check will be performed to ensure the specified milestone has not yet been reached/acheived. If already reached, notifications won't be triggered.

      1. The time at which the notification will be triggered is the milestone cutoff of the first milestone stored in order_delivery_promises. Cutoffs are sorted based on the sort criteria configured for the site.

   2. A special notification named recompute_cutoffs_sets can be called to recompute the cutoffs for each milestone.

When are milestones recalculated ?

All this scenarios impact the current delivery promise of the order.

1. Reservation change.
   🤓 eta_end in the reservation changes or the reservation changes from one stock key to another. 

2. When a line item group gets claimed if set_milestone is set in the graph worfklow.
   🤓 The current eta_end will be the one determined by the orchestration. The tolerance set in the ruleset chaining impacts the current eta_end.

3. When an item is put or removed from a parcel. The current eta_end that's calculated is the one for the parcel as a whole.

4. When the recompute_cutoffs_sets notification is sent by a set_milestone_alert action.

Notifications

Milestones notifications are sent using a special rabbit queue. The project must have the following notification configured for notifications to work.

lig_milestone_reached:
  media:
    rabbit:
    - order_dp:lig_milestone_reached
  time_type: duration
  time_value: 0s

Notification message example

...

...

recalculated ?

All this scenarios impact the current delivery promise of the order.

1. Reservation change.
   🤓 eta_end in the reservation changes or the reservation changes from one stock key to another. 

2. When a line item group gets claimed if set_milestone is set in the graph worfklow.
   🤓 The current eta_end will be the one determined by the orchestration. The tolerance set in the ruleset chaining impacts the current eta_end.

3. When an item is put or removed from a parcel. The current eta_end that's calculated is the one for the parcel as a whole.

4. When the recompute_cutoffs_sets notification is sent by a set_milestone_alert action.

Using milestones

To exploit milestones during order's treatment, milestones must be used in the workflow. This allows to set milestones - considered that it has been reached - and set alerts if not reached in time.

Minimum configuration requirements

To exploit milestones, the site must comply with the following :

1. Delivery promise in configured and a valid response can be recovered for delivery methods sent during order creation.
   You should be able to recover a valid delivery promise response in the Delivery promise test page when sending a request containing : a basket that with all items in the order, an order price equal to the one sent for the order (order.pricing_details.price), sales channel equal to the one sent for the order and delivery method equal to the one sent in the order.

2. Orders are orchestrated using a ruleset chaining which enforces respect of delivery promise.

3. The orders workflow sets milestones for line item groups.

If your site complies with the above, milestones should be present for the order when recovering order delivery promises details this can be recovered by API through GET /orders/:id/delivery_promise/details

If you want to exploit milestones in the Store App the site must also :

1. Have a valid configuration in the Store App for displaying milestones in pages where they need to be displayed.

2. Activate milestones display at the stock location at which milestones should be displayed.

Workflow

1. set_milestone : set the achieved milestone. If empty, without_always_at_start milestone is set (generally de case when initiating milestones in the graph).
   For the set_milestone action to work, the line item group must have stock location ID assigned. As a result, when placing a set_milestone in the workflow it must be placed after assign origin actions.

   1. To make use of milestones, they must be stored for the order at each of its line_item_groups claimed transition. To do so, the action set_milestone has to be set in the claim transition of the line_item_groups, if any..

   2. When recomputing, solutions with non-achieved milestones dates in the future (greater than now) will be considered as valid options. Those with dates in the past, will not be considered.

2. set_milestone_alert : Schedule alerts to be triggered at milestones cutoffs (plus a delay)

   1. Notifications can be scheduled to be triggerd at the time of milestones cutoffs (plus a certain delay). When triggered, a validity check will be performed to ensure the specified milestone has not yet been reached/acheived. If already reached, notifications won't be triggered.

      1. The time at which the notification will be triggered is the milestone cutoff of the first milestone stored in order_delivery_promises. Cutoffs are sorted based on the sort criteria configured for the site.

   2. A special notification named recompute_cutoffs_sets can be called to recompute the cutoffs for each milestone.

Notifications

Notifications can be triggered thanks to set_milestone_alert order workflow action.

Its also possible to intercept internal delivery promise notifications sent when a milestone is reached. Milestones notifications are sent through an internal rabbit queue (order_dp:lig_milestone_reached). To listen to messages, the site needs to have a notification configured as follows :

lig_milestone_reached:
  media:
    rabbit:
    - order_dp:lig_milestone_reached
  time_type: duration
  time_value: 0s

Notification message example

{
    "_id": "6728df89-08fb-11ee-b2dc-02420a000151",
    "params_id": "9975646481091038063",
    "notification_name": "lig_milestone_reached",
    "params": {
        "delay": 120,
        "endpoint_id": "1302",
        "exchange_name": "order_dp:lig_milestone_reached",
        "index_ranges": [
            {
                "from": 0,
                "to": 4
            }
        ],
        "message": {
            "notification_name": "alert_cancel_order",
            "order_id": "CKC021",
            "endpoint_id": "1302",
            "milestone": "prep_milestone",
            "index_ranges": [
                {
                    "from": 0,
                    "to": 4
                }
            ],
            "site_id": "",
            "cutoff": 1686558935,
            "notification_key": "6db3b287-8199-40eb-b52a-0f7ac1b046b8",
            "notification_params": {
                "delay": 120,
                "endpoint_id": "1302",
                "index_ranges": [
                    {
                        "from": 0,
                        "to": 4
                    }
                ],
                "milestone": "prep_milestone",
                "notification_key": "6db3b287-8199-40eb-b52a-0f7ac1b046b8",
                "order_id": "CKC021"
            }
        },
        "milestone": "prep_milestone",
        "notification_key": "6db3b287-8199-40eb-b52a-0f7ac1b046b8",
        "order_id": "CKC021"
    },
    "deadline": "2023-06-12T08:37:35.000Z",
    "notification": {
        "aggregate": false,
        "aggregate_batch_size": 0,
        "aggregate_max_size": 0,
        "aggregation_interval": "",
        "conditions": {},
        "media": {
            "rabbit": [
                "order_dp:lig_milestone_reached"
            ]
        },
        "time_type": "absolute",
        "time_value": "1686559055",
        "location": "",
        "skip_days": null
    }
}

Configuration example

Workflow

placed:
  transitions:
    claimed: # De placed à claimed (VI)
      conditions:
      actions_after:
      - type: set_milestone
      - type: set_milestone_alert
        parameters:
          milestone: packed
          notifications:
          - name: send_mail
            delay: -300
            params:
              to: "tbaudon@onestock-retail.com"
claimed:
  transitions:
    packed: # De claimed à packed (VI)
      conditions:
      actions_after:
      - type: set_milestone
        parameters:
          milestone : preparation #name depends on DP config
packed:
  transitions:
    dispatched: # De packed à dispatched (VI)
      conditions:
      actions_after:
      - type: set_milestone
        parameters:
          milestone : carrier_pickup

Notifications

lig_milestone_reached:
  media:
    rabbit:
    - order_dp:lig_milestone_reached
  time_type: duration
  time_value: 0s

Sorting cutoff sets

Multiple cutoff sets are calculated and consist of all the possible delivery options that can serve the order on time (promised delivery date + tolerance allowed by the orchestration ruleset chaining). See Vocabulary

Sorting criteria are defined to select the best options. The sorting is done in two steps:

• among the cutoffs: sort all the cutoffs a given delivery route (so, for the same cost)

• among the cutoffs sets: sort the best cutoffs of each delivery route.

...

Sorting cutoff sets

Multiple cutoff sets are calculated and consist of all the possible delivery options that can serve the order on time (promised delivery date + tolerance allowed by the orchestration ruleset chaining). See Vocabulary

Sorting criteria are defined to select the best options. The sorting is done in two steps:

• among the cutoffs: sort all the cutoffs a given delivery route (so, for the same cost)

• among the cutoffs sets: sort the best cutoffs of each delivery route.

This configuration is set on the configuration of the site (file or API):

delivery_promise:
  cutoffs_sets: # from v 10.1
    use_sort_orders: true # if true: sorts cutoff sets using the delivery config's sort criteria. Cutoffs are sorted based on the below configuration default_sort_criteria>..>cutoffs.
    sort_critera: # sort criteria to use (overrides use_sort_orders:true, but does not override criteria when specified in GET /cutoffs request)
      eta_fulfilled: #in case there is no tolerance defined or tolerance is finite
        cutoffs_sets: [ +cost_by_parcel, -carrier_pickup, +eta_end ] #cheapest, latest carrier pickup, fastest eta_end
        cutoffs: [ -carrier_pickup, +eta_end ] #latest carrier pickup, fastest eta_end
      eta_exceeded: #in case there is an infinite tolerance defined
        cutoffs_sets: [ +cost_by_parcel, +eta_end ]
        cutoffs: [ +eta_end, +carrier_pickup ]
    default_sort_criteria: # default criteria to use when no sort orders
      eta_fulfilled:
        cutoffs_sets: [ +cost_by_parcel, -carrier_pickup, +eta_end ] #not used if use_sort_orders is true
        cutoffs: [ -carrier_pickup, +eta_end ] #1st by latests carrier pickup, 2nd by fastests eta_end
      eta_exceeded: #juste pour tolérance infinie
        cutoffs_sets: [ +eta_end, +cost_by_parcel ] #not used if use_sort_orders is true
        cutoffs: [ +eta_end, +carrier_pickup ] #1st by fastest eta_end, 2nd by latests carrier pickup.

+ means ascending sorting (0, 1, 2, 3) — the smallest number or the earliest date will be selected

- means descending sorting (3, 2, 1, 0) — the biggest number or the latest date will be selected

use_sort_orders set to true

In this case, the cutoffs of a given delivery route will be sorted using the default_sort_criteria for cutoffs. After that, only the first cutoff of each delivery route will be considered. Then, the cutoff sets will be sorted following the sort option defined on the delivery configurations, in the Delivery screen in the backoffice.

use_sort_orders set to false

In this case, the cutoffs of a given delivery route will be sorted using the sort_criteria for cutoffs. After that, only the first cutoff of each delivery route will be considered. Then, the cutoff sets will be sorted following the sort option defined on sort_criteria for cutoffs_sets.

Display the milestones on the store app

Select the pages and milestones to display

In the store app config, you need to add a delivery_promise key, with the list of pages where to display the milestones.

Pages supported: pack, bag, reserve, pack_scan, bag_scan

delivery_promise:
  cutoffs_setspack:
#  from  v 10.1milestone: carrier_pickup
    use_sort_orderswarning:
true  #  if  truefrom: sorts600
  cutoff  sets  usingto: the1800
delivery config's sort criteria. Cutoffs are sorted based on the below configuration default_sort_criteria>..>cutoffs.  bag:
    milestone: carrier_pickup
    warning:
      from: 600
      sort_criterato: #1800
sort  criteriareserve:
to  use  (overridesmilestone: use_sort_orders:true, but does not override criteria when specified in GET /cutoffs request)
carrier_pickup
    warning:
      from: 600
      eta_fulfilled: #in case there is no tolerance defined or tolerance is finite
        cutoffs_sets: [ +cost_by_parcel, -carrier_pickup, +eta_end ] #cheapest, latest carrier pickup, fastest eta_end
to: 1800

The warning indicates the period of time, in seconds, before the milestone, during which the remaining time will be showed as a warning, in orange. Before, the milestone is shown with no warning, and after it is shown in alert, in red.

    warning:
      from: 600
      

to: 1800

Pack page specific extra configuration

page_request_additional_fields:
  pack: [parcel.cutoffs_sets]

Turn on the display of milestone on the stock location

Your stock location must have a configuration to indicate that the milestones can be displayed.

You must configure this on the stock location (endpoint), by API (it is currently not available in the backoffice):

"configurations": {
    "delivery_promise": {
        cutoffs"milestones": [ +eta_endtrue,
+carrier_pickup ]
      default_sort_criteria: # default criteria to use when no sort orders
      eta_fulfilled:
        cutoffs_sets: [ +cost_by_parcel, -carrier_pickup, +eta_end ] #not used if use_sort_orders is true
        cutoffs: [ -carrier_pickup, +eta_end ] #1st by latests carrier pickup, 2nd by fastests eta_end
      eta_exceeded: #juste pour tolérance infinie
        cutoffs_sets: [ +eta_end, +cost_by_parcel ] #not used if use_sort_orders is true
        cutoffs: [ +eta_end, +carrier_pickup ] #1st by fastest eta_end, 2nd by latests carrier pickup.

+ means ascending sorting (0, 1, 2, 3) — the smallest number or the earliest date will be selected

- means descending sorting (3, 2, 1, 0) — the biggest number or the latest date will be selected

use_sort_orders set to true

In this case, the cutoffs of a given delivery route will be sorted using the default_sort_criteria for cutoffs. After that, only the first cutoff of each delivery route will be considered. Then, the cutoff sets will be sorted following the sort option defined on the delivery configurations, in the Delivery screen in the backoffice.

use_sort_orders set to false

In this case, the cutoffs of a given delivery route will be sorted using the sort_criteria for cutoffs. After that, only the first cutoff of each delivery route will be considered. Then, the cutoff sets will be sorted following the sort option defined on sort_criteria for cutoffs_sets.

Display the milestones on the store app

Select the pages and milestones to display

In the store app config, you need to add a delivery_promise key, with the list of pages where to display the milestones.

• Pages supported: pack, bag, reserve, pack_scan, bag_scan

delivery_promise:
  pack:
    milestone: carrier_pickup
    warning:
      from: 600
      to: 1800
  bag:
    milestone: carrier_pickup
    warning:
      from: 600
      to: 1800
  reserve:
    milestone: carrier_pickup
    warning:
      from: 600
      to: 1800

The warning indicates the period of time, in seconds, before the milestone, during which the remaining time will be showed as a warning, in orange. Before, the milestone is shown with no warning, and after it is shown in alert, in red.

}
}

Configuration example

Workflow

placed:
  transitions:
    claimed: # De placed à claimed (VI)
      conditions:
      actions_after:
      - type: set_milestone
      - type: set_milestone_alert
        parameters:
          milestone: packed
          notifications:
          - name: send_mail
            delay: -300
            params:
              to: "tbaudon@onestock-retail.com"
claimed:
  transitions:
    packed: # De claimed à packed (VI)
      conditions:
      actions_after:
      - type: set_milestone
        parameters:
          milestone : preparation #name depends on DP config
packed:
  transitions:
    dispatched: # De packed à dispatched (VI)
      conditions:
      actions_after:
      - type: set_milestone
        parameters:
          milestone : carrier_pickup

Store App

delivery_promise:
  pack:
    milestone: carrier_pickup
    warning:
      from: 600
      to: 1800
  bag:
    milestone: carrier_pickup
    warning:
      from: 600
      to: 1800

Turn on the display of milestone on the stock location

Your stock location must have a configuration to indicate that the milestones can be displayed.

...

  reserve:
    milestone: carrier_pickup
    warning:
      from: 600
      to: 1800

Stock Locations

"configurations": {
    "delivery_promise": {
        "milestones": true,
    }
}

...