Context

The alerts are used to mark orders that have something in common (e.g. all orders that have not been claimed for 12 hours).

Adding an alert to an order enables easy retrieval and enables customer service to promptly intervene and take necessary actions.

Open

Alerts in the back office

The alerts are displayed on the Orders page in the backoffice. You can get more information in this page: Orders list | Alerts and Counters

Alerts are also displayed on the order detail page (when you click on an order) under the summary section.

Open

Multiple alerts can be added on an order.

Alerts are added and removed automatically on an order. They can also be removed manually from the backoffice.

Configuration

This section on configuration details the process of creating new alerts and establishing automation for adding or removing the alerts on individual orders.

Each alert is actually a counter and there is a condition on the value of the counter to show it as an alert. Generally, a positive counter indicates an alert, while a counter of 0 (or negative) signifies no alert.

There are two things to configure:

• on the backoffice, you must configure the alerts to display and the condition to display them.

• on the workflows and notifications, you must configure how to increment and decrement the alert counter.

Backoffice

To configure alerts to display in the back office, you need to access the page Configuration > Backoffice > Orders > Order list.

In the section Alerts to display, you will see the list of currently defined alerts.

You can easily change in which order alerts are displayed in the Order page by dragging and dropping the six dots on the right of the line.

You can remove the display of an alert by clicking on the trash icon button.

You can add a new alert by clicking on + Add alert button.

You will need to define for each alert:

• Alert key: the identifier of the alert

• Filter type + Value: indicates the condition to consider the counter as an active alert. Typically the condition is ≥ 1, to indicate that the alert is active if the counter is positive.

• Translation key: this is the translation key use to display a proper name for the alert. It may be different from the alert key, because you might want to trigger different alerts for a single alert key. For example, you might display an alert “1 parcel late” (translation key 1_parcel_late) if only one parcel is late on an order and “Several parcels late” (translation key multiple_parcels_late) if multiple parcels are late. In this case, the alert key can be the same, but the filter will be different.

• Color: select the color used to display the alert on the backoffice. Orders affected by this alert will show a dot with this color.

Adding backoffice translations

To display the alert name in the backoffice, you need to define a translation.

Click on the globe in the translation key input to see the complete path to translation key. You can then copy this key by clicking on the corresponding icon .

Then, you need to add a backoffice translation for this translation key. Here is the instruction to add a backoffice translation key: Translations | Add a new translation key

Workflows & notifications

Entities

• Alert: the alert consists in a counter that will be used to display alert flags on orders in the backoffice. Each alert has a key to identify it, for example parcel_late_dispatch.

• Notification: a notification is a way to update the counter, either immediately or later, after a delay defined on the notification itself. The notification has a technical name, for example late_dispatch_notif.

• Workflow action send alert: a workflow action is an action that is triggered automatically during a state change. It is configured in the order, the line item group or the parcel workflow. The send alert action allows to send a notification to update a specific alert. It indicates the notification name, the alert key, how to update the counter (increment by n, decrement by n, reset to n). It can also be used to cancel an alert that was scheduled earlier and that has not yet been executed because it hasn’t reached the defined delay.

How it works

Alerts are essentially counters that can be incremented or decremented based on specific events or status changes within the system. Here’s a concise explanation of how it works:

1. Triggering Notifications:

   • When the status of an order, a line item group, or a parcel changes, the workflow automatically triggers a notification to increment, decrement or reset an alert.

2. Notification updating Alert Counters:

   • The triggered notification is either configured to be immediate or delayed.

   • If it is delayed, it will wait until the delay is reached.

   • If it is immediate, or when the delay is reached, it will either increment, decrement or reset the alert counter.

3. Displaying Alerts on the backoffice:

   • The system evaluates the value of the alert counter.

   • If the counter meets certain criteria (e.g., reaching a specific threshold), the alert will be displayed to the user.

4. Cancelling Alerts:

   • Subsequent status changes in the order or related objects can update the existing notification.

   • These updates can cancel pending notifications or adjust the alert counter (e.g., decrementing it if the notification was already executed).

Example: Alert added immediately and cancelled after

Example: Alert added after a delay and cancelled after

Example: Alert added after a delay and cancelled before the delay expires

Notification

You should begin by setting up the notification. Access the back office and navigate to Configuration > Outbound Messages > Notifications.

You will need to define the notification in either YAML or JSON format. Both are equivalent and you can easily switch from one format to the other. We will show YAML format in this documentation.

To declare a notification, you need add it to the list of existing notifications:

You need to replace <name_of_the_notification> by any unique name you want.

You need to replace <delay> by the time to wait before actually updating the alert. It can be 0s for an immediate alert, or a number of days followed by d, or hours followed by h, or minutes followed by m or seconds followed by s.

Workflow

The workflows can be modified from the backoffice, in the page Workflows and by clicking on one of these workflows: Order, Line item group or Parcel.

The workflow action "Send an alert" (send_alert) is used to manipulate the value of alerts. The parameters available are:

• Creation/Deletion (enable) -
  Select Creation (enable=true) to increase or decrease the alert.
  Set it to false to cancel the alert if it was delayed and has not yet been reached the delay. In this case, all the other parameters must be the same as in the creation of the notification.

• Notification ID (notification_name) - the name of the notification previously created.

• Alert ID (alert_id) - the alert key (as defined in the backoffice configuration).

• Increment/Decrement counter (incr) - Increases of decreases the counter value by 1.

• Specific value (set) - Set the counter to a specific value.

As you can see in the parameters, the same action is used to trigger and to delete a notification. Deleting a notification is only when it was delayed and it has not yet reached the delay. If it has already reached the delay, you must decrement the counter or set it to 0.

Define the workflow

You need to define when to increment and decrement an alert on your workflow(s).

Every alert added to the workflow should be removed at some point. No alert should remain forever on orders.

In case of delayed notifications, the decrement of the alert must be done in two parts: decrement it if it was already incremented (if it is not pending) and delete the notification (in case it is still pending and has not yet incremented the counter).

Example of Workflow

Increment the alert

Select the transition, or the initial status where you want to increment the alert counter.

A panel opens on the right, click on Add + next to Actions after creation. A popin opens and displays the list of possible actions. Search for alert and click on Send an alert.

Then, you can the Increment counter parameter. It should be added on all workflow transitions that go to the desire state(s) (e.g. to placed).

Decrement the alert

The reset should be added on all workflow transitions that go from the desire state(s) (e.g. from placed).

The decrement is done in two parts. Decrementing the alert if it has been incremented, and removing the notification (so that the alert is not incremented later).

Decrement

Select the transition where you want to decrement the alert counter.

A panel opens on the right, click on Add + next to Actions after creation. A popin opens and displays the list of possible actions. Search for alert and click on Send an alert.

You will need to select Creation.

As the alert should be immediately decrease, you must select the name of an immediate notification.

Then select the ID of the alert and select Decrement counter.

Condition

A condition must be added to make sure that the delay was reached and that the alert was already incremented.

To do so, you need to click on Add + next to Conditions. It displays the list of possible conditions. Search for notification and click on Notification waiting to be sent.

Then enter the notification ID used initially to trigger the alert.

Then, don’t forget to click on the three dots on the right and select Does not match. We want to check that the notification has been sent already, so that it has NOT to be sent.

Checks the inverse condition must then be indicated on the condition.

Remove the notification

Select the transition where you want to remove the alert counter.

A panel opens on the right, click on Add + next to Actions after creation. A popin opens and displays the list of possible actions. Search for alert and click on Send an alert.

You will need to select Deletion.

You then need to enter exactly the same parameters as you entered to increment the counter.