Guidelines for integrating an external system
Table of contents
Introduction
Ongoing WMS' open API allows external developers to connect a system, such as your customer's ERP system or web shop, to Ongoing WMS. This means that the external IT partner is responsible for the development, set up and maintenance of the integration. All you need from Ongoing WMS are the API keys, allowing the external system to interact with Ongoing WMS through the integration. We will charge according to our hourly rate for giving support or assistance during the set up.
Ongoing WMS has also developed a few integrations to commonly used web shop platforms and some Scandinavian ERP systems. Those integrations have a standard set up that is easy to set up and start running. A set of settings allows some customization of the integrations. If you need a more tailored integration than the settings provide, you should find an external developer to set up the integration towards our API according to you needs. Please see our page about our own integrations for more information. Note that using one of our integrations is not part of your monthly fee, and set up, troubleshooting and maintenance of integrations are charged by the hourly rate specified in your contract with Ongoing WMS.
In this document, we have pointed out a few things to consider when an external developer is building an integration to your Ongoing WMS. Your contact person at Ongoing WMS can support you through the process, but it is a good idea to go through this document with your customer up front and consider what information the integration must contain, what reports you want to extract from Ongoing WMS and what information is required to pass on to other systems along the supply chain e.g. the transport administration system. Ongoing WMS itself requires very little information for an integration to work. For example, you only need an article number to create an article. It is the work processes at the warehouse or legal reasons which will determine the information required (e.g. scanning requires barcodes and customs requires statistic numbers, country of origin and product prices).
This document also contains a few references to where to read/write data in our API. Those are written in italic and are aimed for the developer building the integration. Depending on your system set up, deviations may occur.
A standard set-up
Below is a standard integration set-up.
- Synchronize the article register from the external system to Ongoing WMS. Master data is in the external system. This synchronizes the article definitions, not the stock values.
- Place purchase orders to Ongoing WMS.
- Report received goods (per purchase order) to the external system.
- Post order to Ongoing WMS.
- Report picked/shipped orders from Ongoing WMS to the external system.
- Synchronize the stock values from Ongoing WMS to the external system. Master data in Ongoing WMS.
The integration set up differs depending on the system to which the integration is built. E.g. a web shop integration does not normally contain purchase orders. Further messages may be needed for e.g. handling returns or tracking numbers.
Articles and stock values
Article numbers
Article numbers are normally used as a unique identifier in Ongoing WMS and need to be matched to a unique identifier, or unique combination, in the external system. The article number can contain letters, numbers and characters. The characters ! % _ ^ \ are used as special search values in Ongoing WMS and should not be part of the article number.
Scanning
If the warehouse intends to use scanning, a barcode (or another code that is used in the warehouse scanning module) should be specified on each article definition. Barcodes are placed at ArticleDefinition - BarCode. This field refers to the barcode for the stock keeping unit (SKU), if other barcodes are used per package, those can be set at ArticleDefinition - BarCodePackage.
Customs information
If you wish to extract proformas from Ongoing WMS, or if custom information needs to be forwarded to another system, e.g. a TA-system, at least the following information should be sent to Ongoing WMS. Make sure this information is available in the system.
- County of origin per article definition (ArticleDefinition - CountryOfOriginCode)
- Statistical number/ HTS code per article definition (ArticleDefinition - StatisticsNumber)
- Price per order row – 2 different prices can be set per order row. (CustomerOrderLine – CustomerLinePrice and LinePrice)
- Currency per order row (CustomerOrderLine – CurrencyCode)
- Possibly VAT per order row (CustomerOrderLine – VatCode)
Synchronizing stock values
Please see our page about Inventory for thorough information about how stock values are handled in the API.
Purchase orders and orders
Purchase orders
Purchase orders (advising an inbound delivery) can be used in an integration, but it is not mandatory. Purchase orders make it easier to report received goods back to the external system than if the goods are received without a purchase order.
Tracking number
If tracking numbers are reported to Ongoing WMS from a transporter or a TA system, then those can be sent to the external system. It may take some time from sending the order to the transporter / TA system until the tracking number is available in Ongoing WMS. Normally the tracking number can be found at OrderInfo - WayBill.
Customer information
When creating an order in Ongoing WMS, we recommend that you always specify the customer's address. If you are using the SOAP API, we also recommend that you set CustomerIdentification = FullNameAndAddress or CustomerIdentification = CustomerNumber.
The address must be split up in name, address row, zip code, city and country. It cannot be sent in as one text string.
Set transporter and transporter service
The transporter and transporter service can be set on the order though the integration. The codes sent to Ongoing WMS must match the codes listed in Ongoing WMS. Make sure the external developer setting up the integration has access to those codes. They can also be fetched using the API function GetTransporterContracts.
Partial deliveries
Discuss with your customer how to work with partial deliveries, and who should have control of the partial deliveries. Some integrations are set up in such way, that orders should not be able to contain goods out of stock. However, due to missing goods, or errors at in- or outbound deliveries, damaged goods, or missing goods, it might still occur that the warehouse receives orders which they cannot satisfy fully.
Even if you do not plan to use partial deliveries it is good to have discussed the procedure. Below are some common ways to handle partial deliveries.
- No partial deliveries: Orders are only sent if all goods are available to pick. The order will be on hold until all items can be picked.
- Stock value based: In this case, all items available to pick will be shipped. As soon as a missing item returns in stock the order will be picked again. This may result in multiple deliveries of one order, and the goods owner does not have control over the partial deliveries. Ongoing WMS can be set up automatically create a back order when picking parts of an order, or you can continue to pick from the same order.
- Goods owner controlled: Another way of working with partial deliveries is to let the goods owner control the partial deliveries. The warehouse will pick all available goods and report the delivered number of items to the external system. If the rest of the goods should be sent in a partial delivery, the goods owner should create a back order and send it to Ongoing WMS.
Returns
Returns can be handled in different ways in Ongoing WMS: it can be returned on a specific outbound order, as an inbound order marked as return or as a return order. If the return should be advised upfront, then return orders or return purchase orders are used. If the return should be tracked to a specific order, the return is done on the outbound order. Discuss with your contact at Ongoing WMS to decide which way is most suitable for your process.
To get returns connected to an outbound order you can use the API function GetOrdersByQuery and filter by LastReturnedFrom. For returns as purchase orders, you can fetch the return with the API function GetInorderByQuery and filter by IsReturnType and LastReceiveTimeFrom. For return orders, use ProcessReturnOrder and GetReturnOrdersByQuery.
Delivery notes and other reports
Go through the delivery notes and reports your customer wants to extract from Ongoing WMS and make sure the integration will contain all this information. E.g. if the delivery note will contain invoicing address, this must be passed on to Ongoing WMS.