The integration flow and error handling

Table of contents

Introduction

Ongoing WMS integrates with many web shops and ERP systems. This guide describes the general flow of these integrations and how the integration behaves when something goes wrong. The same principles apply to most goods owner integrations, although there are special cases that are not covered by this guide.

Our integrations are pull/push based and run on a schedule. A cron job runs the integration once every fifteen minutes. During every run, the integration both pulls data from the external system and pushes data back to it.

During each sync a general integration will:

  • Fetch order data (most commonly sales orders, but could also include purchase orders and production orders).
  • Fetch articles.
  • Report stock balances back to the external system.
  • Report completed work back to the external system – picked and shipped orders, received purchase orders and produced production orders.

Scheduled, pull/push based integrations

To understand how the integrations behave – and why they recover so well from temporary problems – it helps to know how they are run and how they exchange data with the external system.

What is a cron job?

A cron job is a task that is run automatically on a fixed schedule, rather than being started by a person. The name comes from the scheduling service that has been used on servers for decades, where each job is defined by a schedule that describes how often, or at which times, the job should run.

Each of our goods owner integrations is driven by a cron job that runs once every fifteen minutes. When the scheduled time arrives, the job starts, the integration performs its work, and when it is finished the job ends and waits for the next scheduled time. This repeats around the clock, which is why orders, articles and stock balances are kept up to date automatically without anyone having to start the integration manually.

Pull/push compared to webhooks

There are two common ways for two systems to stay in sync. Our integrations use a pull/push model, also known as polling.

With a pull/push integration, our side periodically contacts the external system on a schedule. On every run it pulls the latest changes from the external system (new and updated orders, purchase orders, production orders and articles) and pushes updates back to it (stock balances and completed warehouse work). The external system does not need to know anything about Ongoing WMS; it only needs to answer the questions our integration asks through its API.

With a webhook, the flow is reversed and event-driven. Instead of being asked, the external system sends a notification to a listening address the moment something changes – for example when a new order is created. This can deliver changes closer to real time, but it comes with trade-offs:

  • If the receiving side is unavailable for a few minutes, the notifications sent during that time can be lost unless the external system happens to resend them.
  • The external system must support webhooks and be configured to send them, which not all systems do.
  • Each change is handled individually as it arrives, rather than in efficient batches.

The pull/push model avoids these problems. Because every run asks for all changes since the previous run, nothing is lost if a single run is interrupted – the next run simply fetches everything that happened in the meantime. This makes the integrations robust and self-correcting, at the cost of changes being transferred in scheduled intervals (up to fifteen minutes) rather than instantly. For warehouse operations this small delay is rarely a problem, while the added reliability is a significant advantage.

The integration flow

As described in the guide about integrations with web shops or ERP systems, the web shop or ERP system is the master of the article register and order data, while Ongoing WMS is the master of the stock balances. The integration keeps these systems aligned by transferring data in both directions on every run.

What happens during each sync

Each scheduled run processes the steps listed above in sequence. New and updated orders, purchase orders, production orders and articles are pulled into Ongoing WMS, and the current stock balances and any completed warehouse work are pushed back to the external system.

Recovering from interruptions

If an unforeseen error occurs – for example the web shop being unreachable for a couple of minutes – the current action will simply fail and stop. The next scheduled run then picks up from where the previous one left off. This resilience is one of the big advantages of pull/push based integrations: a temporary problem with the external system does not require any manual intervention, as the integration recovers on its own during the next run.

Errors during the integration

Errors when fetching data

There are generally no errors when the integration fetches data from the external system. If an order is not synced to Ongoing WMS, it is usually because it does not match the filters configured for the integration rather than because of an error. For example, if the integration is set up to fetch orders in the status Open, an order in the status Waiting will not be synced until it reaches a status that is included in the filter.

Errors when reporting data

Most errors occur when orders are reported back to the external system. A common cause is that the order was changed in the ERP system while the warehouse was picking and shipping it, so that the order in Ongoing WMS and the order in the ERP system have diverged.

When this happens, the integration sets the order in an error status and then continues to run. A single order that cannot be reported does not block the rest of the integration from completing its work.

Where errors are shown

When an order is put in the error status, the error message is written as a comment on the order, so that you can see exactly what went wrong directly on the order.

In addition, every time the integration encounters an error it is recorded in the integration log, and an email is sent to the email addresses configured on the integration. It is important to monitor these emails so that issues can be resolved quickly.

Resolving orders in the error status

All orders that are put in the error status need to be resolved in some way. There are two alternatives.

Alternative 1: Fix the root cause

The first alternative is to fix the underlying cause of the error. Consider an order that was updated in the ERP system so that an order line was changed. Because Ongoing WMS does not accept order updates once the warehouse has started working on the order, the warehouse picked the article from the original order line rather than the updated one.

In this case it would be best to update the order line in the ERP system back to the original article, and then report the order again. Reporting the order is done from the integration specific buttons described in Manually trigger integration functions – use the Report back action.

Alternative 2: Mark the order as reported

The second alternative is to mark the order as reported. This does not solve the root cause, but instead marks the order as already reported so that the integration will no longer try to report it. This also means that the issue has to be handled in the ERP system or web shop separately.

We build our integrations to the best of our ability, but there will always be some special cases where errors can occur. For the unforeseen issues that rarely occur, marking the order as reported is the recommended approach.

In both cases, Ongoing WMS will also try to reset the order status to the status the order had before the integration failed to report it.

Who can resolve errors

Customer users of logistics providers (3PL) now have access to the integration-specific buttons as well. This means that customer users can handle these errors themselves without having to involve an administrator.

Related guides

Start using Ongoing WMS