|
| 1 | +# commercetools product type sync |
| 2 | + |
| 3 | +Utility which provides API for building CTP product type update actions and product type synchronisation. |
| 4 | + |
| 5 | +<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
| 6 | +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 7 | + |
| 8 | + |
| 9 | +- [Usage](#usage) |
| 10 | + - [Sync list of product type drafts](#sync-list-of-product-type-drafts) |
| 11 | + - [Prerequisites](#prerequisites) |
| 12 | + - [Running the sync](#running-the-sync) |
| 13 | + - [Build all update actions](#build-all-update-actions) |
| 14 | + - [Build particular update action(s)](#build-particular-update-actions) |
| 15 | +- [Caveats](#caveats) |
| 16 | + |
| 17 | +<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 18 | + |
| 19 | +## Usage |
| 20 | + |
| 21 | +### Sync list of product type drafts |
| 22 | + |
| 23 | +#### Prerequisites |
| 24 | +1. The sync expects a list of non-null `ProductTypeDrafts` objects that have their `key` fields set to match the |
| 25 | +product types from the source to the target. Also the target project is expected to have the `key` fields set, otherwise they won't be |
| 26 | +matched. |
| 27 | +2. It is an important responsibility of the user of the library to instantiate a `sphereClient` that has the following properties: |
| 28 | + - Limits the amount of concurrent requests done to CTP. This can be done by decorating the `sphereClient` with |
| 29 | + [QueueSphereClientDecorator](http://commercetools.github.io/commercetools-jvm-sdk/apidocs/io/sphere/sdk/client/QueueSphereClientDecorator.html) |
| 30 | + - Retries on 5xx errors with a retry strategy. This can be achieved by decorating the `sphereClient` with the |
| 31 | + [RetrySphereClientDecorator](http://commercetools.github.io/commercetools-jvm-sdk/apidocs/io/sphere/sdk/client/RetrySphereClientDecorator.html) |
| 32 | + |
| 33 | + You can use the same client instantiating used in the integration tests for this library found |
| 34 | + [here](/src/main/java/com/commercetools/sync/commons/utils/ClientConfigurationUtils.java#L45). |
| 35 | + |
| 36 | +4. After the `sphereClient` is setup, a `ProductTypeSyncOptions` should be be built as follows: |
| 37 | +````java |
| 38 | +// instantiating a ProductTypeSyncOptions |
| 39 | +final ProductTypeSyncOptions productTypeSyncOptions = ProductTypeSyncOptionsBuilder.of(sphereClient).build(); |
| 40 | +```` |
| 41 | + |
| 42 | +The options can be used to provide additional optional configuration for the sync as well: |
| 43 | +- `errorCallBack` |
| 44 | +a callback that is called whenever an event occurs during the sync process that represents an error. Currently, these |
| 45 | +events. |
| 46 | + |
| 47 | +- `warningCallBack` |
| 48 | +a callback that is called whenever an event occurs during the sync process that represents a warning. Currently, these |
| 49 | +events. |
| 50 | + |
| 51 | +- `beforeUpdateCallback` |
| 52 | +a filter function which can be applied on a generated list of update actions. It allows the user to intercept product type |
| 53 | +update and modify (add/remove) update actions just before they are send to CTP API. |
| 54 | + |
| 55 | +- `beforeCreateCallback` |
| 56 | +a filter function which can be applied on a product type draft before a request to create it on CTP is issued. It allows the |
| 57 | +user to intercept product type create requests modify the draft before the create request is sent to CTP API. |
| 58 | + |
| 59 | +- `allowUuid` |
| 60 | +a flag, if set to `true`, enables the user to use keys with UUID format for references. By default, it is set to `false`. |
| 61 | + |
| 62 | +Example of options usage, that sets the error and warning callbacks to output the message to the log error and warning |
| 63 | +streams, would look as follows: |
| 64 | +```java |
| 65 | +final Logger logger = LoggerFactory.getLogger(MySync.class); |
| 66 | +final ProductTypeSyncOptions productTypeSyncOptions = ProductTypeSyncOptionsBuilder.of(sphereClient) |
| 67 | + .errorCallBack(logger::error) |
| 68 | + .warningCallBack(logger::warn) |
| 69 | + .build(); |
| 70 | +``` |
| 71 | + |
| 72 | + |
| 73 | +#### Running the sync |
| 74 | +After all the aforementioned points in the previous section have been fulfilled, to run the sync: |
| 75 | +````java |
| 76 | +// instantiating a product type sync |
| 77 | +final ProductTypeSync productTypeSync = new ProductTypeSync(productTypeSyncOptions); |
| 78 | + |
| 79 | +// execute the sync on your list of product types |
| 80 | +CompletionStage<ProductTypeSyncStatistics> syncStatisticsStage = productTypeSync.sync(productTypeDrafts); |
| 81 | +```` |
| 82 | +The result of the completing the `syncStatisticsStage` in the previous code snippet contains a `ProductTypeSyncStatistics` |
| 83 | +which contains all the stats of the sync process; which includes a report message, the total number of updated, created, |
| 84 | +failed, processed product types and the processing time of the last sync batch in different time units and in a |
| 85 | +human readable format. |
| 86 | + |
| 87 | +````java |
| 88 | +final ProductTypeSyncStatistics stats = syncStatisticsStage.toCompletebleFuture().join(); |
| 89 | +stats.getReportMessage(); |
| 90 | +/*"Summary: 2000 products types were processed in total (1000 created, 995 updated, 5 failed to sync)."*/ |
| 91 | +```` |
| 92 | + |
| 93 | +__Note__ The statistics object contains the processing time of the last batch only. This is due to two reasons: |
| 94 | + 1. The sync processing time should not take into account the time between supplying batches to the sync. |
| 95 | + 2. It is not not known by the sync which batch is going to be the last one supplied. |
| 96 | + |
| 97 | +More examples of how to use the sync can be found [here](/src/integration-test/java/com/commercetools/sync/integration/producttypes/ProductTypeSyncIT.java). |
| 98 | + |
| 99 | +### Build all update actions |
| 100 | + |
| 101 | +A utility method provided by the library to compare a ProductType with a new ProductTypeDraft and results in a list of product type update actions. |
| 102 | +```java |
| 103 | +List<UpdateAction<ProductType>> updateActions = ProductTypeSyncUtils.buildActions(productType, productTypeDraft, productTypeSyncOptions); |
| 104 | +``` |
| 105 | + |
| 106 | +### Build particular update action(s) |
| 107 | + |
| 108 | +Utility methods provided by the library to compare the specific fields of a ProductType and a new ProductTypeDraft, and in turn builds |
| 109 | + the update action. One example is the `buildChangeNameUpdateAction` which compares names: |
| 110 | +````java |
| 111 | +Optional<UpdateAction<ProductType>> updateAction = ProductTypeUpdateActionUtils.buildChangeNameAction(oldProductType, productTypeDraft); |
| 112 | +```` |
| 113 | +More examples of those utils for different fields can be found [here](/src/test/java/com/commercetools/sync/producttypes/utils/ProductTypeUpdateActionUtilsTest.java). |
| 114 | + |
| 115 | + |
| 116 | +## Caveats |
| 117 | + |
| 118 | +1. Product types are either created or updated. Currently the tool does not support product type deletion. |
| 119 | +2. Syncing product types with an attribute of type [NestedType](https://docs.commercetools.com/http-api-projects-productTypes.html#nestedtype) is not supported yet. |
0 commit comments