|
| 1 | +# Type Sync |
| 2 | + |
| 3 | +Module used for importing/syncing Types into a commercetools project. |
| 4 | +It also provides utilities for generating update actions based on the comparison of a [Type](https://docs.commercetools.com/http-api-projects-types.html#type) |
| 5 | +against a [TypeDraft](https://docs.commercetools.com/http-api-projects-types.html#typedraft). |
| 6 | + |
| 7 | +<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
| 8 | +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 9 | + |
| 10 | + |
| 11 | +- [Usage](#usage) |
| 12 | + - [Sync list of type drafts](#sync-list-of-type-drafts) |
| 13 | + - [Prerequisites](#prerequisites) |
| 14 | + - [Running the sync](#running-the-sync) |
| 15 | + - [Important to Note](#important-to-note) |
| 16 | + - [More examples of how to use the sync](#more-examples-of-how-to-use-the-sync) |
| 17 | + - [Build all update actions](#build-all-update-actions) |
| 18 | + - [Build particular update action(s)](#build-particular-update-actions) |
| 19 | +- [Caveats](#caveats) |
| 20 | + |
| 21 | +<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 22 | + |
| 23 | +## Usage |
| 24 | + |
| 25 | +### Sync list of type drafts |
| 26 | + |
| 27 | +#### Prerequisites |
| 28 | +1. The sync expects a list of `TypeDraft`s that have their `key` fields set to be matched with |
| 29 | +types in the target CTP project. Also, the types in the target project are expected to have the `key` |
| 30 | +fields set, otherwise they won't be matched. |
| 31 | + |
| 32 | +2. Create a `sphereClient` [as described here](IMPORTANT_USAGE_TIPS.md#sphereclient-creation). |
| 33 | + |
| 34 | +3. After the `sphereClient` is set up, a `TypeSyncOptions` should be be built as follows: |
| 35 | +````java |
| 36 | +// instantiating a TypeSyncOptions |
| 37 | +final TypeSyncOptions typeSyncOptions = TypeSyncOptionsBuilder.of(sphereClient).build(); |
| 38 | +```` |
| 39 | + |
| 40 | +[More information about Sync Options](SYNC_OPTIONS.md). |
| 41 | + |
| 42 | +#### Running the sync |
| 43 | +After all the aforementioned points in the previous section have been fulfilled, to run the sync: |
| 44 | +````java |
| 45 | +// instantiating a type sync |
| 46 | +final TypeSync typeSync = new TypeSync(typeSyncOptions); |
| 47 | + |
| 48 | +// execute the sync on your list of types |
| 49 | +CompletionStage<TypeSyncStatistics> syncStatisticsStage = typeSync.sync(typeDrafts); |
| 50 | +```` |
| 51 | +The result of the completing the `syncStatisticsStage` in the previous code snippet contains a `TypeSyncStatistics` |
| 52 | +which contains all the stats of the sync process; which includes a report message, the total number of updated, created, |
| 53 | +failed, processed types and the processing time of the last sync batch in different time units and in a |
| 54 | +human-readable format. |
| 55 | + |
| 56 | +````java |
| 57 | +final TypeSyncStatistics stats = syncStatisticsStage.toCompletebleFuture().join(); |
| 58 | +stats.getReportMessage(); |
| 59 | +/*"Summary: 2000 types were processed in total (1000 created, 995 updated, 5 failed to sync)."*/ |
| 60 | +```` |
| 61 | + |
| 62 | +__Note__ The statistics object contains the processing time of the last batch only. This is due to two reasons: |
| 63 | + |
| 64 | + 1. The sync processing time should not take into account the time between supplying batches to the sync. |
| 65 | + 2. It is not known by the sync which batch is going to be the last one supplied. |
| 66 | + |
| 67 | +#### Important to Note |
| 68 | +1. If two matching `fieldDefinition`s (old and new) on the matching `type`s (old and new) have a different `FieldType`, the sync will |
| 69 | +**remove** the existing `fieldDefinition` and then **add** a new `fieldDefinition` with the new `FieldType`. |
| 70 | + |
| 71 | +2. The `fieldDefinition` for which the `fieldType` is not defined (`null`) will not be synced. |
| 72 | + |
| 73 | +#### More examples of how to use the sync |
| 74 | + |
| 75 | + 1. [Sync from another CTP project as a source](https://github.com/commercetools/commercetools-sync-java/tree/master/src/integration-test/java/com/commercetools/sync/integration/ctpprojectsource/types/TypeSyncIT.java). |
| 76 | + 2. [Sync from an external source](https://github.com/commercetools/commercetools-sync-java/tree/master/src/integration-test/java/com/commercetools/sync/integration/externalsource/types/TypeSyncIT.java). |
| 77 | + |
| 78 | +*Make sure to read the [Important Usage Tips](IMPORTANT_USAGE_TIPS.md) for optimal performance.* |
| 79 | + |
| 80 | +### Build all update actions |
| 81 | + |
| 82 | +A utility method provided by the library to compare a `Type` with a new `TypeDraft` and results in a list of type update actions. |
| 83 | +```java |
| 84 | +List<UpdateAction<Type>> updateActions = TypeSyncUtils.buildActions(type, typeDraft, typeSyncOptions); |
| 85 | +``` |
| 86 | + |
| 87 | +### Build particular update action(s) |
| 88 | + |
| 89 | +Utility methods provided by the library to compare the specific fields of a `Type` and a new `TypeDraft`, and in turn builds |
| 90 | + the update action. One example is the `buildChangeNameUpdateAction` which compares names: |
| 91 | +````java |
| 92 | +Optional<UpdateAction<Type>> updateAction = TypeUpdateActionUtils.buildChangeNameAction(oldType, typeDraft); |
| 93 | +```` |
| 94 | +More examples of those utils for different types can be found [here](https://github.com/commercetools/commercetools-sync-java/tree/master/src/test/java/com/commercetools/sync/types/utils/TypeUpdateActionUtilsTest.java). |
| 95 | + |
| 96 | +## Caveats |
| 97 | + |
| 98 | +1. Updating the label of enum values and localized enum values of field definition is not supported yet. [#339](https://github.com/commercetools/commercetools-sync-java/issues/339) |
| 99 | +2. Removing the enum values and localized enum values from the field definition is not supported yet. [#339](https://github.com/commercetools/commercetools-sync-java/issues/339) |
| 100 | +3. Updating the input hint of a field definition is not supported yet. [#339](https://github.com/commercetools/commercetools-sync-java/issues/339) |
| 101 | +4. Currently the sync would handle changes to Enum or LocalizedEnum Types but not [Set](https://docs.commercetools.com/http-api-projects-types.html#settype) of either. [#313](https://github.com/commercetools/commercetools-sync-java/issues/313) |
0 commit comments