|
| 1 | +# Custom Object Sync |
| 2 | + |
| 3 | +Module used for importing/syncing CustomObject into a commercetools project. |
| 4 | +It also provides utilities for correlating a custom object to a given custom object draft based on the |
| 5 | +comparison of a [CustomObject](https://docs.commercetools.com/http-api-projects-custom-objects#customobject) |
| 6 | +against a [CustomObjectDraft](https://docs.commercetools.com/http-api-projects-custom-objects#customobjectdraft). |
| 7 | + |
| 8 | +<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
| 9 | +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 10 | + |
| 11 | + |
| 12 | +- [Usage](#usage) |
| 13 | + - [Sync list of CustomObjectDrafts](#sync-list-of-customobjectdrafts) |
| 14 | + - [Prerequisites](#prerequisites) |
| 15 | + - [Running the sync](#running-the-sync) |
| 16 | + - [More examples of how to use the sync](#more-examples-of-how-to-use-the-sync) |
| 17 | + |
| 18 | +<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 19 | + |
| 20 | +## Usage |
| 21 | + |
| 22 | +### Sync list of CustomObjectDrafts |
| 23 | + |
| 24 | +#### Prerequisites |
| 25 | +1. The sync expects a list of `CustomObjectDraft`s that have their `key` and `container` fields set to be matched with |
| 26 | +custom objects in the target CTP project. Therefore, the custom objects in the target project are expected to have the |
| 27 | +same `key` and `container` fields set, otherwise they won't be matched. |
| 28 | + |
| 29 | +2. Create a `sphereClient` [as described here](IMPORTANT_USAGE_TIPS.md#sphereclient-creation). |
| 30 | + |
| 31 | +3. After the `sphereClient` is set up, a `CustomObjectSyncOptions` should be be built as follows: |
| 32 | +````java |
| 33 | +// instantiating a CustomObjectSyncOptions |
| 34 | +final CustomObjectSyncOptions customObjectSyncOptions = CustomObjectSyncOptionsBuilder.of(sphereClient).build(); |
| 35 | +```` |
| 36 | + |
| 37 | +[More information about Sync Options](SYNC_OPTIONS.md). |
| 38 | + |
| 39 | +#### Running the sync |
| 40 | +After all the aforementioned points in the previous section have been fulfilled, to run the sync: |
| 41 | +````java |
| 42 | +// instantiating a CustomObjectSync |
| 43 | +final CustomObjectSync customObjectSync = new CustomObjectSync(customObjectSyncOptions); |
| 44 | + |
| 45 | +// execute the sync on your list of custom object drafts |
| 46 | +CompletionStage<CustomObjectSyncStatistics> syncStatisticsStage = customObjectSync.sync(customObjectDrafts); |
| 47 | +```` |
| 48 | +The result of the completing the `syncStatisticsStage` in the previous code snippet contains a `CustomObjectSyncStatistics` |
| 49 | +which contains all the stats of the sync process; which includes a report message, the total number of updated, created, |
| 50 | +failed, processed custom objects and the processing time of the last sync batch in different time units and in a |
| 51 | +human-readable format. |
| 52 | + |
| 53 | +````java |
| 54 | +final CustomObjectSyncStatistics stats = syncStatisticsStage.toCompletebleFuture().join(); |
| 55 | +stats.getReportMessage(); |
| 56 | +/*"Summary: 2000 custom objects were processed in total (1000 created, 995 updated, 5 failed to sync)."*/ |
| 57 | +```` |
| 58 | + |
| 59 | +__Note__ The statistics object contains the processing time of the last batch only. This is due to two reasons: |
| 60 | + |
| 61 | + 1. The sync processing time should not take into account the time between supplying batches to the sync. |
| 62 | + 2. It is not known by the sync which batch is going to be the last one supplied. |
| 63 | + |
| 64 | +#### More examples of how to use the sync |
| 65 | + |
| 66 | +- [Sync from an external source](https://github.com/commercetools/commercetools-sync-java/tree/master/src/integration-test/java/com/commercetools/sync/integration/externalsource/customobjects/CustomObjectSyncIT.java). |
| 67 | + |
| 68 | +*Make sure to read the [Important Usage Tips](IMPORTANT_USAGE_TIPS.md) for optimal performance.* |
| 69 | + |
| 70 | +More examples of those utils for different custom objects can be found [here](https://github.com/commercetools/commercetools-sync-java/tree/master/src/test/java/com/commercetools/sync/customobjects/utils/CustomObjectSyncUtilsTest.java). |
0 commit comments