Skip to content

Latest commit

 

History

History
131 lines (97 loc) · 8.4 KB

INVENTORY_SYNC.md

File metadata and controls

131 lines (97 loc) · 8.4 KB

commercetools inventory sync

Utility which provides API for building CTP inventory update actions and inventory synchronisation.

Usage

Build all update actions

Build particular update action(s)

To build the update action for changing inventory quantity:

final Optional<UpdateAction<InventoryEntry>> updateAction = buildChangeQuantityAction(oldInventory, inventoryDraft);

For other examples of update actions, please check here.

Sync list of inventory entry drafts

In order to use the inventory sync an instance of InventorySyncOptions has to be injected.

In order to instantiate a InventorySyncOptions, a sphereClient is required:

// instantiating an InventorySyncOptions
final InventorySyncOptions inventorySyncOptions = InventorySyncOptionsBuilder.of(sphereClient).build();

then to start the sync:

// instantiating an inventory sync
final InventorySync inventorySync = new InventorySync(inventorySyncOptions);

// execute the sync on your list of inventories
inventorySync.sync(inventoryEntryDrafts);

Note: We encourage you to use QueueSphereClientDecorator as sphereClient implementation. It will reduce amount of concurrent requests to CTP, thus will improve its performance. An example of use can be found here.

Preconditions: The sync expects a list of InventoryEntryDraft objects that have their sku fields set, otherwise the sync will trigger an errorCallback function set by the user (more on it can be found down below in the options explanations).

Every inventory entry may have a reference to a supply Channel and a reference to the Type of its custom fields. These references are matched by their key. Therefore, in order for the sync to resolve the actual ids of those references, their keys has to be supplied in one of two ways:

  • Provide the key value on the id field of the reference. This means that calling getId() on the reference would return its key. Note that the library will check that this key is not provided in UUID format by default. However, if you want to provide the key in UUID format, you can set it through the sync options. Different example of sync performed that way can be found here.
  • Provide the reference expanded. This means that calling getObj() on the reference should not return null, but return the actual object complete object of the reference, from which the its key can be directly accessible. Example of sync performed that way can be found here.

The sync results in a CompletionStage that contains an InventorySyncStatistics object. This object contains all the stats of the sync process: a report message, the total number of updated, created, failed, processed inventory entries and the processing time of the sync in different time units and in a human readable format. An example of how it looks like can be found here.

inventorySync.sync(inventoryEntryDrafts)
            .thenAccept(inventorySyncStatistics -> inventorySyncStatistics.getReportMessage());
//"Summary: 2000 inventory entries were processed in total (1000 created, 995 updated, 5 failed to sync)"

Note The statistics object contains the processing time of the last batch only. This is due to two reasons:

  1. The sync processing time should not take into account the time between supplying batches to the sync.
  2. It is not not known by the sync which batch is going to be the last one supplied.

Additional optional configuration for the sync can be configured on the InventorySyncOptions instance, according to your need:

  • ensureChannels a flag which represents a strategy to handle syncing inventory entries with missing supply channels. Having an inventory entry, with a missing supply channel reference, could be processed in either of the following ways:

    • If ensureChannels is set to false this inventory entry won't be synced and the errorCallback will be triggered. An example of use can be found here.
    • If ensureChannels is set to true the sync will attempt to create the missing channel with the given key. If it fails to create the supply channel, the inventory entry won't sync and errorCallback will be triggered. An example of use can be found here.
    • If not provided, it is set to false by default.

  • batchSize a number that could be used to set the batch size with which inventory entries are fetched and processed with, as inventory entries are obtained from the target CTP project in batches for better performance. The algorithm accumulates up to batchSize inventory entries from the input list, then fetches the corresponding inventory entries from the target CTP project in a single request, and then performs the update actions needed. Playing with this option can slightly improve or reduce processing speed. An example of use can be found here.

    • If not provided, it is set to 30 by default.

  • errorCallBack a callback that is called whenever an event occurs during the sync process that represents an error. An example of use can be found here.

  • warningCallBack a callback that is called whenever an event occurs during the sync process that represents a warning.

  • allowUuid a flag, if set to true, enables the user to use keys with UUID format for references. By default, it is set to false.

  • beforeUpdateCallback a filter function which can be applied on a generated list of update actions. It allows the user to intercept inventory entry update and modify (add/remove) update actions just before they are send to CTP API.

  • beforeCreateCallback a filter function which can be applied on a inventoryEntry draft before a request to create it on CTP is issued. It allows the user to intercept inventoryEntry create requests modify the draft before the create request is sent to CTP API.

Under the hood

The tool matches categories by their sku and supplyChannel key. Based on that inventories are created or updated. Currently the tool does not support inventory deletion.