Learn how the Skrym-Ongoing integration works

Ongoing is one of the most popular Warehouse Management Systems (WMS) in Sweden for E-commerce retailers.
It is very easy to utilize Skrym if you are already using Ongoing as a WMS provider due to our many different integrations with them.
Setting up Skrym with Ongoing
Regardless of your needs, all of our integrations with Ongoing are handled through their .
<MermaidChart
title="Integration between Ongoing WMS and Skrym"
subtitle="Order data flow and processing"
chart={`
sequenceDiagram
autonumber
participant S as Skrym
participant O as Ongoing WMS
activate O
Note over O: Credentials provided to Skrym
deactivate O

O->>S: Ongoing Webhook (Depends on integration)
activate S
Note over S: Webhook received

S->>O: GetOrder API Call
activate O
O->>S: Order Data Response
deactivate O

Note over S: Skrym processes data and performs calculations

S->>O: Populate additional data
deactivate S

`}
/>
There are, of course, slight differences between the integrations, and depending on whether you're using one or many of our tools, the setup might differ.
To see the basics of how our integrations are set up, have a look below:

  
    Optimization 📦
    Shipping 🚚
  
  
        
There are two common ways to integrate our optimization with Ongoing. One is by setting up the OrderCreated webhook event. 
This causes the webhook to be triggered whenever the order is created in Ongoing (this is usually when an ERP system sends it to the warehouse). 
            - **Basic recommendation:** Skrym populates the `OrderClass` field in Ongoing with the package recommendation (using the package alias) 
            - **Recommendation with dimensions:** Skrym populates the `Parcel` field in Ongoing with a parcel ID and the dimensions from the  
    </TabPanel>
    <TabPanel>
        Shipping is an area that covers many of our tools; in particular, it relates to both Booking and Tracking. 
        The integration for both of these options is quite similar since they rely on the same webhook, namely:
        - **OrderStatusChanged**: This particular webhook allows you to specify when it should be triggered depending on the status change of the order. 
        The usual way to set this up is to always go from picked to sent.

        Skrym will then fetch the required data from both Ongoing and our own checkout (if the checkout tool is being used) to create and print the labels using <Mention label="Printnode" href="https://www.printnode.com/en"/>

        The tracking integration will instead simply read from the tracking reference and order number to start a tracked shipment in Skrym. 
    </TabPanel>
</TabPanels>




  If the suggested implementations are not suitable for your current set up you can always reach us with requests or questions at: .


Ongoing

How Skrym interacts with Ongoing when performing a booking

This section explains the interaction between Ongoing and Skrym when using Skrym's  functionality.
Specific Set-up for Booking
To trigger a booking in Skrym from Ongoing, a  is usually set up, based on the OrderStatusChanged event moving from Picked to Send.
Booking Process
When Skrym receives the webhook call from Ongoing we:

Fetch the entire order from Ongoing
Check if the OrderNumber matches any entries in Skrym's system

If there is a match, proceed to step 3
If there is no match, Skrym tries to utilize the data in Ongoing WMS to book and print labels (see tabs below for more information)


Match each parcel id against the stored parcels in Skrym (usually from a checkout session)
Request booking to transporter
Upload the label and tracking data (URL + reference) back to Ongoing
Print label(s)


  
    Single Parcel
    Multi-parcel
  
  
    
      For the single parcel, there are two distinct possibilities: 
  #### 1. Order is created with Skrym  
  The order can proceed as usual with no requirement for data to exist in Ongoing (except for the parcel which should have been added by Skrym).
         
  #### 2. Order is not created with Skrym 
  The order needs to have full shipping information available in Ongoing WMS, including package data, destination information, and chosen delivery option.
</TabPanel>

<TabPanel>
  There are three possible scenarios:
        
  #### 1. Order is created fully with Skrym 
  The only requirement here is that the parcel IDs in Ongoing match the reference in Skrym.

  #### 2. Order is partially created with Skrym
  This means that Skrym has at least one package with complete shipping data available, while also indicating that there are multiple parcels that need booking.

  This will then lead to Skrym trying to use the partial data to book all the parcels to arrive at the same location. 
  If this is not possible (due to transporter limitations), Skrym will instead default to book the parcels to the geographically closest position to the destination.
        
  #### 3. Order is not created with Skrym 
  The order needs to have full shipping information available in Ongoing WMS, including package data, destination information, and chosen delivery option.
</TabPanel>

  

Confirmed Booking
When Skrym has finalized the booking, the label(s) is uploaded to Ongoing and each parcel in the order is updated with a tracking reference and URL.
If the booking contains multiple parcels, and the transporter responds with multiple tracking references, Skrym will put the respective tracking data on each parcel in Ongoing.
| Transporter | Tracking Reference | Tracking URL |
| --- | --- | --- |
|      | 00373500489530470000 | Yes |
|           | 2904305345 | Yes |
|        | 373501541843279332 | Yes |
|      | XX01720410992279 | Yes |
|     | 9990000000003544436 | Yes, but requires customer to enter reference |
|    | 1005326820 | Yes  |

Booking in Ongoing

This page details the Ongoing Article Created & Updated webhooks

In Ongoing there is a possibility to set up webhooks for Article Created and Article Updated. We utilize this to sync data from Ongoing to Skrym.


Ongoing Article Webhook

This page details the OngoingWebhookV2 endpoint in the integration service

The webhook is to be configured in a retailer's ongoing account. Once configured, this endpoint is called by Ongoing WMS notifying Skrym of a newly created order.
Note:
It must be noted that OngoingWebhookV2 endpoint is an encore raw endpoint.

For this integration to work, a retailer using Ongoing WMS should first have been onboarded by Skrym.

Retailer Onboarding
The onboarding process entails,

Skrym receiving the retailer's Ongoing WMS credentials and other configuration information, which is then stored in the webhook service, consisting of

username
password (is encrypted by Skrym)
ongoing base URL
goods_owner (a number that identifies the retailer to ongoing)
the weight and length units that the retailer uses in Ongoing.

If not provided, can be assumed to be Ongoing's default of kg and m




Skrym receiving warehouse details of the retailer, which is also stored in the webhook service.
Skrym providing the API key and endpoint path to the retailer, which should be configured to be used by Ongoing when making calls to Skrym.

Request header for authorization
X-Auth-Token: <<API KEY>>

Webhook call request body
{
  "webhookOrdersId": 1,
  "webhookEventId": 29676,
  "system": "Mert's merch",
  "timestamp": "2023-01-25T09:12:06.5210359Z",
  "orderId": 330674,
  "orderNumber": "0004566213",
  "goodsOwnerId": 65,
  "path": "/api/v1/orders/330674",
  "byUser": {
    "userId": 33
  },
  "byComputer": {
    "computerId": 12,
    "computerName": "device1"
  },
  "orderStatus": {
    "number": 200
  },
  "currentShipmentId": 100
}

Authorization

When Skrym receives this request the header is checked for its X-Auth-Token, which is the chosen token type for the Skrym-Ongoing integration.
Once authenticated, the retailer's Ongoing credentials are fetched by Skrym from the webhook service's database.

Data aggregation


From the received request, the following order and transportation information is extracted.

orderId, which refers to the order ID of the order created in Ongoing
orderNumber, which is an identifier tying the retailer's order ID to ongoing



The extracted orderId, together with the Ongoing credentials are used to fetch the corresponding order from Ongoing WMS.

This is done using a HTTP GET request to Ongoing's \

`<>/orders/<>`endpoint.
- Skrym authenticates its request towards Ongoing using basic auth along with the username and password (which is decrypted) from the stored Ongoing credentials.
  
  HTTP basic auth works by taking in a username and password, formatting it as "username:password" and encoding that to Base 64.
  This value is then added to the authorization header of the request.
  
- If this fails, the webhook call is logged as an error in Skrym, and no information is sent to Ongoing.
Note:
All of Ongoing's REST APIs can be viewed in their API docs .


Order fetch request authorization header
'Authorization: Basic <<Base-64-encoded-username:password>>='

Order fetch response
| Code                                                                                                       | Description |
| ---------------------------------------------------------------------------------------------------------- | ----------- |
| ✅ - 200 | Successful  |

Once the order is fetched, the following information is extracted.

warehouseId, which identifies the retailer's warehouse where the concerned order is handled.
name, which is the name of the chose transport method
transporterName, which is the name of the transporter offering the chosen transport method (This can be read from different fields in ongoing e.g. WayOfDelivery or Transporter/transporter name).


Skrym then checks if the extracted warehouse exists in the system.

If available, the warehouse location is fetched which enables additional features such as emissions calculations.
If the warehouse information is not known the rest of the optimization will still happen, but without said features.



Optimization
All the data aggregated until this point is transformed to the appropriate models to call Skrym's post payment optimization flow.
The result of this flow is a package suggestion for the order. Currently the only supported package type is the fixed-size one. However, this can also denote an incrementally height adjustable (foldable) package, or an envelope. This is specified via the variation field.

A variation **v** set to higher than 1 means the selected package is one of two things:

A foldable package folded at the v:th increment, which will be relayed to the packer to cut/fold the package at the right height
An envelope, in which case v can be ignored because envelopes are may sometimes be represented as multiple variations (potentially depending on how the height changes in relation to the length and width of the envelope depending on what is put inside) but this is of no interest to the packer


Result propagation

Skrym currently operates on the assumption that only one (fixed) package is chosen during optimization, i.e. no split results or other package types are chosen. This has to be handled when retailers with order splitting permissions, and other package types are to implement an Ongoing-Skrym integration.



Skrym will check if the selected packaging is indeed an envelope via a dimensions check (this is currently done by checking against the permissable dimensions of postnord varubrev which is postnord's letter flow, but should be improved in the future), and if so omit the folding/cutting information from the suggestion instruction pushed to ongoing.


If it is found that sufficient transportation information exists to calculate costs then this is done according to Skrym's understanding of the relevant transport agreement.

In case of penalty fees, their amounts are propagated to Ongoing as seen in the next step.
In case it is found that the order breaks the method agreement (i.e. will require switching to a different transport method altogether), a breaking message is propagated to Ongoing as seen in the next step.
In case the optimization or cost calculation step fails with errors, or if no suitable package is found, a manual override needed message is propagated to Ongoing as seen in the next step.

Note:
All of Ongoing's REST APIs can be viewed in their API docs .


The packaging information and cost calculation results are then propagated to Ongoing via a put request which sets the classes field; an array of class objects, each representing an information tag related to the order.


Each class contains the following fields


code, which is used by Skrym for the id of the suggested package


name, which contains the the name of said package


comment, which denotes if Skrym has successfully suggested a package, or if manual review is needed.


isParcelTypeSuggestion, serves as an indication to Ongoing which orderClass is the package recommendation. (This will be consumed by Ongoing and will have different effects on a customer basis)


The information is sent to Ongoing using a HTTP PATCH request to Ongoing's \


`<>/orders/<>/addOrderClasses` endpoint. 
- As previously mentioned, Skrym authenticates its request towards Ongoing using basic auth along with the username and password from the stored Ongoing credentials.
- If this fails, the webhook call is logged as an error in Skrym, and no information is sent to Ongoing.
Put order classes request body (automatic assigned)
{
  "classes": [
    {
      "code": "ABC-123",
      "name": "box-1",
      "comment": "Automatically assigned",
      "isParcelTypeSuggestion": true
    },
    {
      "code": "breaking",
      "name": "BREAKING",
      "comment": "This transport method will not work",
      "isParcelTypeSuggestion": false
    },
    {
      "code": "fee 100",
      "name": "100 SEK",
      "isParcelTypeSuggestion": false
    }
  ]
}

In the above example request,


the first order class represents a successful optimization selecting a valid package,


the second class represents an order that breaks the method agreement,


and the third shows incurred penalty fees.


The breaking and penalty fees classes don't have to occur together. Any one (or none) of them can be returned depending on the situation.

They will always have an accompanying chosen package class that they are returned with.



The chosen package class can however be returned on its own.
Put order classes request body (manual override)


{
  "classes": [
    {
      "code": "manual",
      "name": "Manual choice",
      "comment": "Needs manual decision",
      "isParcelTypeSuggestion" : false
    }
  ]
}

Put order classes response
| Code                                                                                                                        | Description |
| --------------------------------------------------------------------------------------------------------------------------- | ----------- |
| ✅ - 200 | Successful  |

