Technical instruction - WebViewer Order tracking configuration

Overview

To properly work, the WebViewer order tracking feature requires a bit of configuration. It is nothing too complex but it is required for everything to work as expected.

Configuration

At the moment, all of the configuring for order tracking is done in profile.config. It can now also be done directly in WebAdmin panel in the WebViewer but this feature is still in testing.

Configuration values from WebAdmin will always overwrite those from profile.config when defined. So, if something does not work as unexpected even though your profile.config looks good, it may be because you have different values in WebAdmin.

Because of recent changes, the configuration no longer needs to be nested in an OrderManager configuration block like before. In the new version, make sure to have the OrderTrackingSettings block placed at the document root (outside of the first OrderManager block) otherwise it will not work. Like so:

<!-- This will work -->
<OrderTrackingSettings enabled="true" dev-mode="false">
  ...
</OrderTrackingSettings>

<OrderManager>
  <OrderManager add-availability-on-orderline="true" enable-external-part-number="true" display-delivery-to-top="true">
  
  <!-- This won't work anymore and will cause an error -->
  <OrderTrackingSettings dev-mode="false">
    ...
  </OrderTrackingSettings>
  
  </OrderManager>
</OrderManager>

Now, let’s get into the main part of the configuration:

<OrderTrackingSettings enabled="true" dev-mode="false">
  <!-- Setting dev mode to true will make tracking stop at the first error and display it in the banner -->
  <CarrierList>
    <Carrier name="DHL" api-key="SECRET" />
    <Carrier name="PostNord" api-key="SECRET" />
    <Carrier name="UPS" api-key="SECRET" />
  </CarrierList>
  <SOSMList>
    <!-- name corresponds to the ID of the status in the WebViewer, site-status corresponds to order status from database orders for current site -->
    <SOSM name="Invoiced" site-statuses="invoiced" />
    <SOSM name="Delivered" site-statuses="Delivered" />
    <SOSM name="Canceled" site-statuses="canceled" />
  </SOSMList>
</OrderTrackingSettings>

OrderTrackingSettings can be enabled or disabled depending on whether the customer wants to display tracking information on the order page. In order to do so, the enabled attribute to must be set to "true" or "false" whether you want tracking on or off. By default, tracking will be disabled so make sure to add enabled="true" on the opening tag of <OrderTrackingSettings> block.

The actual configuration is split in two parts:

Carrier list: Describes the various supported carrier APIs used to fetch real-time tracking data
Static Order Status Mappings (SOSM): A set of different mappings used in complement of real-time data in case of missing or unknown information

Carrier configuration

Configuration for each carrier must be declared as <Carrier> and nested inside the <CarrierList> block.

Each carrier element is used to describe a supported carrier API using two attributes:

name: Must be one of the supported carrier identifiers: DHL, PostNord, TNT or UPS. (Only these four are supported at the moment)
api-key: A specific key given by the carrier to get access to their API and fetch real-time data. These keys are given by the carriers directly and the process to get one will depend on the carrier. Make sure to consult the official website of the carrier to learn more about how you can get one of these keys.

So now let’s say most of your orders are shipped using PostNord and DHL. You already got the respective api keys for both: “123456789” for PostNord and “qwertyuiop” for DHL. (These are example, you can try these keys but I highly doubt they will work. Lucky you if they do .)

You would then need the following Carrier configuration to get tracking data from both carriers.

<CarrierList>
  <Carrier name="DHL" api-key="123456789" />
  <Carrier name="PostNord" api-key="qwertyuiop" />
</CarrierList>

And that is all you need to configure the various carriers. Now let’s talk about the second part, which is about defining SOSM.

Defining Static Order Status Mappings (SOSM)

Defining SOSM is an additional part of configuration which can be used to complement real-time data fetched from the carriers. Because each carrier have different data policies, you might not get the desired real-time data from them all the time. One example of that is UPS who only provide order data for a limited amount of time after it has been delivered. After three months, tracking for delivered orders become unavailable and there is no way to differentiate a nonexistent order from one that was delivered months ago. This is just one example from UPS but basically this can be a problem since you may want an order that has been delivered five months ago to still appear as “delivered” and not some error.

To solve that problem, static order status mappings have been introduced. It’s a long name but basically:

The “Static” part is used to oppose the “dynamic” real-time data fetched from the carriers. These mappings heavily rely on static data from the customers.
“Order Status” refers to the actual status of the order coming from the customer database.
And finally “Mappings” because in order to display an order as “Delivered”, the WebViewer needs to know which statuses from the customers refer to a “delivered” state for an order. Maybe the customer already has their delivered orders marked as “delivered” and so a mapping here might seem pointless. But let’s say a a custom three-letters code is used instead and “DLV” refers to delivered orders. The WebViewer would have no way of guessing that, and, in that case, custom mappings can be used to convert the “DLV” value to one that is understood by the WebViewer.

To define SOSMs, you need to open a <SOSMList> configuration block and put your mappings inside of it, like so:

Each mapping must be declared as a <SOSM> element and described using two attributes:

name: A unique string identifier understood by the tracking feature. There are seven valid identifiers that are supported: Processing, Packing, PartiallyShipped, Shipped, Delivered, Invoiced, Canceled.
site-statuses: A set of comma-separated strings referring to one or multiple statuses from the customer database. For example, let’s say your canceled orders are marked as “CAN”, then you can just put “CAN” in the site statuses attribute. If you have multiple statuses referring to the canceled state, then you can list them as long as you make sure to separate them by a comma each time.

You can define a mapping for each of the seven supported status identifiers but we only recommend to define statuses for “Invoiced”, “Delivered” and “Canceled” as they are the only ones that have been shown to cause problems so far.

Dev mode

There is one last thing I haven’t talked about but you can set a custom attribute dev-mode="true" on the <OrderTrackingSettings > root configuration block. Doing so will activate and debug mode which will cause tracking to be halted every time an error occurs. The error will then be displayed in place of the actual real-time data to provide more information about what went wrong. Make sure to only use this in a development environment as it will break tracking at the first error.

It should be set to false by default:

Conclusion

And that is all, now you should be all set to use orders tracking!

If you have used the tracking feature before, make sure to remove any old configuration block as it is no longer understood by the app and might throw an error. Finally, don’t forget to get keys from your carriers and set them as described before.