INVENTORY_SYNC.md

InventoryEntry Sync

Module used for importing/syncing InventoryEntries into a commercetools project. It also provides utilities for generating update actions based on the comparison of a InventoryEntry against a InventoryEntryDraft.

• Usage
  • Sync list of inventory entry drafts
    • Prerequisites
    • Running the sync
  • Build all update actions
  • Build particular update action(s)
• Caveats

Usage

Sync list of inventory entry drafts

Prerequisites

1. The sync expects a list of InventoryEntryDrafts 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).

2. 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 keys. Therefore, in order for the sync to resolve the actual ids of those references, their keys has to be supplied in the following way:

   • Provide the key value on the id field of the reference. This means that calling getId() on the reference would return its key.

     Note: When syncing from a source commercetools project, you can use this util which this library provides: replaceInventoriesReferenceIdsWithKeys that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync: java // Puts the keys in the reference id fields to prepare for reference resolution final List<InventoryEntryDraft> inventoryEntryDrafts = replaceInventoriesReferenceIdsWithKeys(inventoryEntries);

3. Create a sphereClient as described here.

4. After the sphereClient is setup, a InventorySyncOptions should be be built as follows:

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

More information about Sync Options.

Running the sync

After all the aforementioned points in the previous section have been fulfilled, to run the sync:

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

// execute the sync on your list of inventories
CompletionStage<InventorySyncStatistics> syncStatisticsStage = inventorySync.sync(inventoryEntryDrafts);

The result of the completing the syncStatisticsStage in the previous code snippet contains a InventorySyncStatistics which contains all the stats of the sync process; which includes a report message, the total number of updated, created, failed, processed inventories and the processing time of the sync in different time units and in a human readable format.

final InventorySyncStatistics stats = syncStatisticsStage.toCompletebleFuture().join();
stats.getReportMessage(); 
/*"Summary: 25 inventory entries were processed in total (9 created, 5 updated, 2 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 known by the sync which batch is going to be the last one supplied.

More examples of how to use the sync here.

Make sure to read the Important Usage Tips for optimal performance.

Build all update actions

A utility method provided by the library to compare an InventoryEntry with a new InventoryEntryDraft and results in a list of InventoryEntry update actions.

List<UpdateAction<InventoryEntry>> updateActions = InventorySyncUtils.buildActions(oldEntry, newEntry, inventorySyncOptions);

Examples of its usage can be found in the tests here.

Build particular update action(s)

Utility methods provided by the library to compare the specific fields of an InventoryEntry and a new InventoryEntryDraft, and in turn builds the update action. One example is the buildChangeQuantityAction which compares quantities:

Optional<UpdateAction<InventoryEntry>> updateAction = buildChangeQuantityAction(oldEntry, newEntry);

Caveats

1. The library will sync all field types of custom fields, except ReferenceType. #87.