Skip to content

CATEGORY_SYNC.md

Latest commit

 

History

History
147 lines (112 loc) · 8.4 KB

CATEGORY_SYNC.md

File metadata and controls

147 lines (112 loc) · 8.4 KB

commercetools category sync

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

Usage

Sync list of category drafts

Prerequisites

  1. The sync expects a list of non-null CategoryDraft objects that have their key fields set to match the categories from the source to the target. Also the target project is expected to have the key fields set, otherwise they won't be matched.

  2. Every category may have a reference to a parent category and a reference to the Type of its custom fields. Categories and Types are matched by their key Therefore, in order for the sync to resolve the actual ids of those references, the key of the Type/parent Category 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.
    • Provide the reference expanded. This means that calling getObj() on the reference should not return null, but return the Type object, from which the its key can be directly accessible.

    Note: This library provides you with a utility method replaceCategoriesReferenceIdsWithKeys that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:

    // Puts the keys in the reference id fields to prepare for reference resolution
final List<CategoryDraft> categoryDrafts = replaceCategoriesReferenceIdsWithKeys(categories);

    Example of its usage can be found here.

  3. It is an important responsibility of the user of the library to instantiate a sphereClient that has the following properties:

    • Limits the amount of concurrent requests done to CTP. This can be done by decorating the sphereClient with QueueSphereClientDecorator
    • Retries on 5xx errors with a retry strategy. This can be achieved by decorating the sphereClient with the RetrySphereClientDecorator

    You can use the same client instantiating used in the integration tests for this library found here.

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

// instantiating a CategorySyncOptions
final CategorySyncOptions categorySyncOptions = CategorySyncOptionsBuilder.of(sphereClient).build();

The options can be used to provide additional optional configuration for the sync as well:

  • errorCallBack a callback that is called whenever an event occurs during the sync process that represents an error. Currently, these events.

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

  • beforeUpdateCallback a filter function which can be applied on a generated list of update actions. It allows the user to intercept category 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 category draft before a request to create it on CTP is issued. It allows the user to intercept category create requests modify the draft before the create request is sent to CTP API.

  • 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.

Example of options usage, that sets the error and warning callbacks to output the message to the log error and warning streams, would look as follows:

final Logger logger = LoggerFactory.getLogger(MySync.class);
final CategorySyncOptions categorySyncOptions = CategorySyncOptionsBuilder.of(sphereClient)
                                                                          .errorCallBack(logger::error)
                                                                          .warningCallBack(logger::warn)
                                                                          .build();

Running the sync

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

// instantiating a category sync
final CategorySync categorySync = new CategorySync(categorySyncOptions);

// execute the sync on your list of categories
CompletionStage<CategorySyncStatistics> syncStatisticsStage = categorySync.sync(categoryDrafts);

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

final CategorySyncStatistics stats = syncStatisticsStage.toCompletebleFuture().join();
stats.getReportMessage(); 
/*"Summary: 2000 categories were processed in total (1000 created, 995 updated, 5 failed to sync and 0 categories with a missing parent)."*/

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.

More examples of how to use the sync

  1. From another CTP project as source can be found here.
  2. From an external source can be found here.

Build all update actions

A utility method provided by the library to compare a Category with a new CategoryDraft and results in a list of category update actions.

List<UpdateAction<Category>> updateActions = CategorySyncUtils.buildActions(category, categoryDraft, categorySyncOptions);

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 a Category and a new CategoryDraft, and in turn builds the update action. One example is the buildChangeNameUpdateAction which compares names:

Optional<UpdateAction<Category>> updateAction = buildChangeNameUpdateAction(oldCategory, categoryDraft);

More examples of those utils for different fields can be found here.

Caveats

  1. Categories are either created or updated. Currently the tool does not support category deletion.
  2. The library doesn't sync category assets yet #3, but it will not delete them.
  3. The library will sync all field types of custom fields, except ReferenceType. #87.