Skip to content

OrderFlow Magento Integration Guide

OrderFlow Ltd.

Document Version: 4.2.4

Document Built: 2024-02-16

This document and its content is copyright of OrderFlow Ltd. All rights reserved.
You may not, except with our express written permission, distribute, publish or commercially exploit the content.
Any reproduction of part or all of the contents in any form is prohibited.

Inventory Export

Inventory Import

The inventory import operation is a very important part of the OrderFlow Magento integration, particularly as the imported stock quantity is generally used to determine whether or not the product concerned appears as 'in stock' and therefore sellable to the public.

In the current version (1.9.1.1) of Magento, the built-in SOAP web service stock update is limited by the fact that only a single product stock figure can be updated via a single web service call. This limits the ability of OrderFlow to do efficient bulk stock updates, or indeed, to reset the stock levels across the full product catalog where this is necessary.

The inventory import uses a queueing architecture through which many (any number from one to several hundred, for example) product stock levels may be sent from OrderFlow to Magento via a single message. This message is queued for processing.

The interface is robust in allowing for these messages to be delivered out of sequence, while still being able to determine whether a particular update is the most recent available, or whether it should be discarded as a stale update.

As mentioned earlier in this document, the stock updates are initiated by OrderFlow.

The product inventory quantity is calculated as the following:

  • the total stock across all locations
  • less stock in non-usable locations (damaged, quarantined, etc.)
  • less the stock quantity associated with open (unfulfilled) orders received by OrderFlow

Info

As of version 1.0.0.37 of the module, the product inventory calculation can be adjusted to also take into account unsent orders and active quotes on Magento.

Initiating Inventory Import

There are three ways that inventory import into Magento can be triggered. In each case, the action is initiated in OrderFlow.

Single product push: the stock level for an individual product can be 'pushed' or exported from OrderFlow to Magento. This option is not typically used in day to day operations, but is very useful in testing.

Full stock push: the stock levels for all products in OrderFlow can be pushed from OrderFlow to Magento. This option is typically used to reset all of the Magento stock levels, for example, after a stock take.

Incremental stock push: this mechanism involves a stock push for products whose stock level may have changed since the last export took place, so is very efficient in its use of system resources. In almost all environments this process will be automated.

Single Stock Push

The best way to understand how OrderFlow and the Magento extension work together to do stock updates is to work through a single stock push example.

Start by navigating to a test product, which we can do through the Inventory -> Inventory -> Search menu.

The following screenshot shows the listing for one of the out of stock products.

Orderflow stock push 1

Note the cached inventory record for this product, which here shows as 10.

A single stock push can be invoked using the Push Stock link, followed by the Confirm button.

On the OrderFlow side, this operation results in an outgoing message being queued, which can be found using the Integration -> Remote Messages -> Search menu.

Drilling into the detail of the most recently created record, the following queued message displays:

Orderflow stock push message

Note that OrderFlow is now configured to automatically send negative availability figures as zero.

Normally, sending of these messages will be automated. Additionally, the Send button can be used to manually push through the message to Magento.

Clicking on the Send button should result in the Response field being populated with text such as the following:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:Magento" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
      <ns1:orderflowInventoryMultiUpdateResponse>
         <result xsi:type="xsd:string">Success - Message 4 Received</result>
      </ns1:orderflowInventoryMultiUpdateResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Note that the above response has indicated that message 4 has been received. This message can be found immediately on the Magento Admin Panel using the OrderFlow -> Requests menu, as shown below.

Magento inventory request

Each row in the grid shows the following:

Request ID: a numerical counter, simply an internal identifier within the extension for that record.

OrderFlow ID: this is the ID for the message that was received from OrderFlow, once again with the value of 4.

Import ID: the ID of the import record that gets created within the Magento extension.

Note that the import record above is not created instantaneously on receipt of the message. Instead it is queued for creation through a scheduled job. Before the request has been processed, no import record will have been created, and the value for the column will be 'Pending'.

The detail of the request shows the same information as above, but also shows the XML received from OrderFlow.

It is also possible to follow a Import ID link once the message has been processed. This leads to a screen such as the following.

Magento inventory import

On this screen, we can see the outcome of import processing. Specifically, the screen informs us that the stock quantity of the SKU hdd000 has been set to zero.

Note the Sequence ID column. This displays the value of OrderFlow product inventory record ID at the point when the inventory notification is created. This field is used to ensure that stale updates are not applied, as described in the Handling Inventory Duplicates section.

Full Stock Push

A full stock push can be initiated to send similar stock updates to the ones applied above for all of the products known to OrderFlow.

To initiate a full stock push, navigate in OrderFlow to Inventory -> Admin -> Inventory, as shown below:

Orderflow full stock push

The Push All Stock Levels button can be used to initiate a product inventory export for all products. The stock push will be divided into multiple separate messages, with the maximum number of products sent per message set according to the system property inventory.notification.chunk.size. A sensible value for this property would be about 100 to 200.

Once invoked, the messages created would be queued in OrderFlow, then sent automatically to Magento. On Magento, the messages will be queued for processing as described in the previous section, and processed automatically. The Batch Size property in the Magento extension's Inventory Import configuration will control how many messages can be processed each time the inventory import job runs.

Note

In general a full stock push should not be necessary. Unless the inventory is reinitialised using the Initialize button, most of the stock updates will be discarded as duplicates. How this happens will be explained in more detail in the Handling Inventory Duplicates section below.

Initialize button will recalculate the inventory level for all of the products on the system.

Incremental Stock Push

The manual stock push operations are only useful in exceptional circumstances. Ordinarily, inventory notifications are automatically send through an incremental export process.

Each time a stock change is made, or a new order is received, or an order is cancelled, OrderFlow will automatically recalculate the inventory for each of the affected products, creating a new inventory record for each product.

Another process on OrderFlow checks for all inventory records created since the last inventory notification took place, and creates a new inventory notification for each of these.

This process results in a continual stream of near real time inventory updates for products whose stock positions may have changed.

Handling Inventory Duplicates

The OrderFlow Magento integration has been designed to deal with the consequences of real world situations that may occur in any enterprise computing environment; network outages may result in stock updates being received out of sequence, and even duplicates of the same message being received.

In the stock notification message, as well as sending a stock value, OrderFlow also sends the current inventory record ID as a product sequence number associated with the the update, as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:Magento" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
      <ns1:orderflowInventoryMultiUpdate>
         <sessionId xsi:type="xsd:string">[session_authentication_token]</sessionId>
         <skusQty SOAP-ENC:arrayType="ns1:skuQty[1]" xsi:type="ns1:skuQtyArray">
            <item xsi:type="ns1:skuQty">
               <key xsi:type="xsd:string">hdd000</key>
               <value xsi:type="xsd:int">0</value>
            </item>
         </skusQty>
         <skusSeqId SOAP-ENC:arrayType="ns1:skuSeq[1]" xsi:type="ns1:skuSeqArray">
            <item xsi:type="ns1:skuSeq">
               <key xsi:type="xsd:string">hdd000</key>
               <value xsi:type="xsd:int">10</value>
            </item>
         </skusSeqId>
         <messageSeqId xsi:type="xsd:int">4</messageSeqId>
      </ns1:orderflowInventoryMultiUpdate>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The extension ensures that for each of the stock updates received, the system does not overwrite a more recently created stock record with one that is older, that is, a stale record.

If a stale update is received and processed, the extension will detect this and log an Imports -> Inventory entry such as the following:

Magento inventory stale

The extension will also detect messages that have been previously received and processed. In this case, the occurrence will be logged for auditing purposes, but no further processing will be attempted.

Unsent Orders and Active Quotes

The stock available figure sent to Magento from OrderFlow takes into account the orders that it has received at the point where the stock figure is calculated.

However, there are three sources of lag which may result in the reported figure that is updated in Magento overstating the actual available figure:

  • there is a delay in OrderFlow between the time that the 'most recent' order is received in OrderFlow and the time that the available figure is calculated.
  • there is a delay in OrderFlow between the time the available figure is calculated and the time that it is sent to Magento.
  • there is a delay in Magento between the time the available figure is sent to Magento and the time it is processed on Magento.

During the lag period, the following may have happened:

  • new orders may have been taken for the sku concerned, but not yet sent to OrderFlow.
  • new orders may have been added to cart, but not yet completed on Magento.

The OrderFlow Magento integration includes a feature which allows for these scenarios to be taken into account.

Note

This feature is only available on OrderFlow 3.6.9 and Magento Module version 1.0.0.37 onwards.

Magento Configuration

The following screenshot shows the inventory import configuration in Magento.

Magento inventory import config

The Adjust Inventory control allows you to determine whether to allow inventory to be adjusted based on unsent orders, unsent orders and active quotes, or not at all. The options for this are:

  • No: no inventory adjustment is made based on unsent orders and/or active quotes. This is the backward compatible setting, and is the default option.
  • Unsent orders: the Magento module takes into account orders that have been submitted since the date of the last order used in calculating the inventory level in OrderFlow.
  • Unsent orders and active quotes: the Magento module takens into account not only unsent orders, but active quotes that have not yet been confirmed as orders. Note that a quote is created when a user adds items into their 'shopping cart'.

The remaining configuration options set on the screen above.

  • Unsent Order Statuses: determines the status of orders that will be considered as unsent. For example, orders for which the payment was unable to complete may be excluded from the list of orders that would be used to adjust the inventory for a product.
  • Active Quote Cutoff: the maximum age for active quotes that might be used to adjust the inventory. This is useful to ensure that old or stale quotes don't artificially depress the adjusted product inventory. This value is set to 1 by default.s
  • Unsent Order Cutoff: the maximum age for unsent orders that might be used to adjust the inventory. This allows exclusion from the inventory adjustment old orders that for whatever reason have not have been passed through to OrderFlow.