Skip to content

Commit 46dc192

Browse files
leungkinghin-ctleungkinghin-ct
authored
583 improve sync options doc (#586)
* Update PRODUCT_SYNC.md * Update PRODUCT_SYNC.md * Update PRODUCT_SYNC.md * Update documents * Enhance PRODUCT_SYNC.md * Revert "Enhance PRODUCT_SYNC.md" This reverts commit 268240d. * Update PRODUCT_SYNC.md * Change the content in sync options description * Change the description of warning callback in PRODUCT_SYNC.md * Change the description of error callback and warning callback * Revert "Change the description of error callback and warning callback" This reverts commit 0698b8f. * Change error callback and warning callback description * Change example of error callback and warning callback * Change CTP to commercetools platform * Change example of warn callback and error callback * Change example of beforeUpdateCallback * Modify example of beforeCreateProductCallback * Fix problem in sync options example * Modify CATEGORY_SYNC.md and PRODUCT_TYPE_SYNC.md * Fix batch size description for category sync options * Modify CART_DISCOUNT_SYNC.md * Update TYPE_SYNC.md * Modify the beforeCreateCallback example for sync options * Modify TAX_CATEGORY_SYNC.md * Fix incorrect information in sync options batch size * Fix description in warningCallback in TAX_CATEGORY_SYNC.md * Fix beforeCreateCallback example in TAX_CATEGORY_SYNC.md * Modify STATE_SYNC.md * Modify CUSTOM_OBJECT_SYNC.md * Update INVENTORY_SYNC.md * Update documents of beforeCreateCallback for product sync * Update beforeCreateCallback section in various reources sync documents
1 parent a707978 commit 46dc192

9 files changed

Lines changed: 808 additions & 14 deletions

‎docs/usage/CART_DISCOUNT_SYNC.md‎

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ against a [CartDiscountDraft](https://docs.commercetools.com/http-api-projects-c
1111
- [Usage](#usage)
1212
- [Sync list of cart discount drafts](#sync-list-of-cart-discount-drafts)
1313
- [Prerequisites](#prerequisites)
14+
- [About SyncOptions](#about-syncoptions)
1415
- [Running the sync](#running-the-sync)
1516
- [More examples of how to use the sync](#more-examples-of-how-to-use-the-sync)
1617
- [Build all update actions](#build-all-update-actions)
@@ -47,7 +48,88 @@ actual ids of the type reference, the `key` of the `Type` has to be supplied.
4748
final CartDiscountSyncOptions cartDiscountSyncOptions = CartDiscountSyncOptionsBuilder.of(sphereClient).build();
4849
````
4950

50-
[More information about Sync Options](SYNC_OPTIONS.md).
51+
#### About SyncOptions
52+
`SyncOptions` is an object which provides a place for users to add certain configurations to customize the sync process.
53+
Available configurations:
54+
55+
##### 1. `errorCallback`
56+
A callback that is called whenever an error event occurs during the sync process. Each resource executes its own
57+
error-callback. When sync process of particular resource runs successfully, it is not triggered. It contains the
58+
following context about the error-event:
59+
60+
* sync exception
61+
* cart discount draft from the source
62+
* cart discount of the target project (only provided if an existing cart discount could be found)
63+
* the update-actions, which failed (only provided if an existing cart discount could be found)
64+
65+
##### Example
66+
````java
67+
final Logger logger = LoggerFactory.getLogger(CartDiscountSync.class);
68+
final CartDiscountSyncOptions cartDiscountSyncOptions = CartDiscountSyncOptionsBuilder
69+
.of(sphereClient)
70+
.errorCallback((syncException, draft, cartDiscount, updateActions) ->
71+
logger.error(new SyncException("My customized message"), syncException)).build();
72+
````
73+
74+
##### 2. `warningCallback`
75+
A callback that is called whenever a warning event occurs during the sync process. Each resource executes its own
76+
warning-callback. When sync process of particular resource runs successfully, it is not triggered. It contains the
77+
following context about the warning message:
78+
79+
* sync exception
80+
* cart discount draft from the source
81+
* cart discount of the target project (only provided if an existing cart discount could be found)
82+
83+
##### Example
84+
````java
85+
final Logger logger = LoggerFactory.getLogger(CartDiscountSync.class);
86+
final CartDiscountSyncOptions cartDiscountSyncOptions = CartDiscountSyncOptionsBuilder
87+
.of(sphereClient)
88+
.warningCallback((syncException, draft, cartDiscount, updateActions) ->
89+
logger.warn(new SyncException("My customized message"), syncException)).build();
90+
````
91+
92+
##### 3. `beforeUpdateCallback`
93+
During the sync process if a target cart discount and a cart discount draft are matched, this callback can be used to
94+
intercept the **_update_** request just before it is sent to commercetools platform. This allows the user to modify
95+
update actions array with custom actions or discard unwanted actions. The callback provides the following information :
96+
97+
* cart discount draft from the source
98+
* cart discount from the target project
99+
* update actions that were calculated after comparing both
100+
101+
##### Example
102+
````java
103+
final TriFunction<
104+
List<UpdateAction<CartDiscount>>, CartDiscountDraft, CartDiscount, List<UpdateAction<CartDiscount>>>
105+
beforeUpdateCartDiscountCallback =
106+
(updateActions, newCartDiscountDraft, oldCartDiscount) -> updateActions.stream()
107+
.filter(updateAction -> !(updateAction instanceof ChangeCartPredicate))
108+
.collect(Collectors.toList());
109+
110+
final CartDiscountSyncOptions cartDiscountSyncOptions =
111+
CartDiscountSyncOptionsBuilder.of(sphereClient).beforeUpdateCallback(beforeUpdateCartDiscountCallback).build();
112+
````
113+
114+
##### 4. `beforeCreateCallback`
115+
During the sync process if a cart discount draft should be created, this callback can be used to intercept
116+
the **_create_** request just before it is sent to commercetools platform. It contains following information :
117+
118+
* cart discount draft that should be created
119+
120+
Please refer to [example in product sync document](PRODUCT_SYNC.md#example-set-publish-stage-if-category-references-of-given-product-draft-exists).
121+
122+
##### 5. `batchSize`
123+
A number that could be used to set the batch size with which cart discounts are fetched and processed,
124+
as cart discounts are obtained from the target project on commercetools platform in batches for better performance. The
125+
algorithm accumulates up to `batchSize` resources from the input list, then fetches the corresponding cart discounts
126+
from the target project on commecetools platform in a single request. Playing with this option can slightly improve or
127+
reduce processing speed. If it is not set, the default batch size is 50 for cart discount sync.
128+
##### Example
129+
````java
130+
final CartDiscountSyncOptions cartDiscountSyncOptions =
131+
CartDiscountSyncOptionsBuilder.of(sphereClient).batchSize(30).build();
132+
````
51133

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

‎docs/usage/CATEGORY_SYNC.md‎

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ against a [CategoryDraft](https://docs.commercetools.com/http-api-projects-categ
1111
- [Usage](#usage)
1212
- [Sync list of category drafts](#sync-list-of-category-drafts)
1313
- [Prerequisites](#prerequisites)
14+
- [About SyncOptions](#about-syncoptions)
1415
- [Running the sync](#running-the-sync)
1516
- [Build all update actions](#build-all-update-actions)
1617
- [Build particular update action(s)](#build-particular-update-actions)
@@ -48,7 +49,88 @@ actual ids of the references, their `key`s has to be supplied.
4849
final CategorySyncOptions categorySyncOptions = CategorySyncOptionsBuilder.of(sphereClient).build();
4950
````
5051

51-
[More information about Sync Options](SYNC_OPTIONS.md).
52+
#### About SyncOptions
53+
`SyncOptions` is an object which provides a place for users to add certain configurations to customize the sync process.
54+
Available configurations:
55+
56+
##### 1. `errorCallback`
57+
A callback that is called whenever an error event occurs during the sync process. Each resource executes its own
58+
error-callback. When sync process of particular resource runs successfully, it is not triggered. It contains the
59+
following context about the error-event:
60+
61+
* sync exception
62+
* category draft from the source
63+
* category of the target project (only provided if an existing category could be found)
64+
* the update-actions, which failed (only provided if an existing category could be found)
65+
66+
##### Example
67+
````java
68+
final Logger logger = LoggerFactory.getLogger(CategorySync.class);
69+
final CategorySyncOptions categorySyncOptions = CategorySyncOptionsBuilder
70+
.of(sphereClient)
71+
.errorCallback((syncException, draft, category, updateActions) ->
72+
logger.error(new SyncException("My customized message"), syncException)).build();
73+
````
74+
75+
##### 2. `warningCallback`
76+
A callback that is called whenever a warning event occurs during the sync process. Each resource executes its own
77+
warning-callback. When sync process of particular resource runs successfully, it is not triggered. It contains the
78+
following context about the warning message:
79+
80+
* sync exception
81+
* category draft from the source
82+
* category of the target project (only provided if an existing category could be found)
83+
84+
##### Example
85+
````java
86+
final Logger logger = LoggerFactory.getLogger(CategorySync.class);
87+
final CategorySyncOptions categorySyncOptions = CategorySyncOptionsBuilder
88+
.of(sphereClient)
89+
.warningCallback((syncException, draft, category, updateActions) ->
90+
logger.warn(new SyncException("My customized message"), syncException)).build();
91+
````
92+
93+
##### 3. `beforeUpdateCallback`
94+
During the sync process if a target category and a category draft are matched, this callback can be used to
95+
intercept the **_update_** request just before it is sent to commercetools platform. This allows the user to modify
96+
update actions array with custom actions or discard unwanted actions. The callback provides the following information :
97+
98+
* category draft from the source
99+
* category from the target project
100+
* update actions that were calculated after comparing both
101+
102+
##### Example
103+
````java
104+
final TriFunction<
105+
List<UpdateAction<Category>>, CategoryDraft, Category, List<UpdateAction<Category>>>
106+
beforeUpdateCategoryCallback =
107+
(updateActions, newCategoryDraft, oldCategory) -> updateActions.stream()
108+
.filter(updateAction -> !(updateAction instanceof RemoveAsset))
109+
.collect(Collectors.toList());
110+
111+
final CategorySyncOptions categorySyncOptions =
112+
CategorySyncOptionsBuilder.of(sphereClient).beforeUpdateCallback(beforeUpdateCategoryCallback).build();
113+
````
114+
115+
##### 4. `beforeCreateCallback`
116+
During the sync process if a category draft should be created, this callback can be used to intercept
117+
the **_create_** request just before it is sent to commercetools platform. It contains following information :
118+
119+
* category draft that should be created
120+
121+
Please refer to [example in product sync document](PRODUCT_SYNC.md#example-set-publish-stage-if-category-references-of-given-product-draft-exists).
122+
123+
##### 5. `batchSize`
124+
A number that could be used to set the batch size with which categories are fetched and processed,
125+
as categories are obtained from the target project on commercetools platform in batches for better performance. The
126+
algorithm accumulates up to `batchSize` resources from the input list, then fetches the corresponding categories
127+
from the target project on commecetools platform in a single request. Playing with this option can slightly improve or
128+
reduce processing speed. If it is not set, the default batch size is 50 for category sync.
129+
##### Example
130+
````java
131+
final CategorySyncOptions categorySyncOptions =
132+
CategorySyncOptionsBuilder.of(sphereClient).batchSize(30).build();
133+
````
52134

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

‎docs/usage/CUSTOM_OBJECT_SYNC.md‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ against a [CustomObjectDraft](https://docs.commercetools.com/http-api-projects-c
1212
- [Usage](#usage)
1313
- [Sync list of CustomObjectDrafts](#sync-list-of-customobjectdrafts)
1414
- [Prerequisites](#prerequisites)
15+
- [About SyncOptions](#about-syncoptions)
1516
- [Running the sync](#running-the-sync)
1617
- [More examples of how to use the sync](#more-examples-of-how-to-use-the-sync)
1718

@@ -34,7 +35,76 @@ same `key` and `container` fields set, otherwise they won't be matched.
3435
final CustomObjectSyncOptions customObjectSyncOptions = CustomObjectSyncOptionsBuilder.of(sphereClient).build();
3536
````
3637

37-
[More information about Sync Options](SYNC_OPTIONS.md).
38+
39+
#### About SyncOptions
40+
`SyncOptions` is an object which provides a place for users to add certain configurations to customize the sync process.
41+
Available configurations:
42+
43+
##### 1. `errorCallback`
44+
A callback that is called whenever an error event occurs during the sync process. Each resource executes its own
45+
error-callback. When sync process of particular resource runs successfully, it is not triggered. It contains the
46+
following context about the error-event:
47+
48+
* sync exception
49+
* custom object draft from the source
50+
* custom object of the target project (only provided if an existing custom object could be found)
51+
* the update-actions, which failed (only provided if an existing custom object could be found)
52+
53+
##### Example
54+
````java
55+
final Logger logger = LoggerFactory.getLogger(CustomObjectSync.class);
56+
final CustomObjectSyncOptions customObjectSyncOptions = CustomObjectSyncOptionsBuilder
57+
.of(sphereClient)
58+
.errorCallback((syncException, draft, customObject, updateActions) ->
59+
logger.error(new SyncException("My customized message"), syncException)).build();
60+
````
61+
62+
##### 2. `warningCallback`
63+
A callback that is called whenever a warning event occurs during the sync process. Each resource executes its own
64+
warning-callback. When sync process of particular resource runs successfully, it is not triggered. It contains the
65+
following context about the warning message:
66+
67+
* sync exception
68+
* custom object draft from the source
69+
* custom object of the target project (only provided if an existing custom object could be found)
70+
71+
##### Example
72+
````java
73+
final Logger logger = LoggerFactory.getLogger(CustomObjectSync.class);
74+
final CustomObjectSyncOptions customObjectSyncOptions = CustomObjectSyncOptionsBuilder
75+
.of(sphereClient)
76+
.warningCallback((syncException, draft, customObject, updateActions) ->
77+
logger.warn(new SyncException("My customized message"), syncException)).build();
78+
````
79+
80+
##### 3. `beforeUpdateCallback`
81+
In theory, `CustomObjectSyncOptions` provides callback before update operation. User can customize own callback and inject
82+
into sync options. However, in actual case, `beforeUpdateCallback`is not triggered in custom object sync process. When
83+
new custom object draft has the same key and container as existing custom object but different in custom object values,
84+
sync process automatically perform update operation. The value of corresponding custom object in target project is
85+
overwritten. This approach is different from other resources and no update action is involved.
86+
87+
No example is applicable.
88+
89+
##### 4. `beforeCreateCallback`
90+
During the sync process if a custom object draft should be created, this callback can be used to intercept
91+
the **_create_** request just before it is sent to commercetools platform. It contains following information :
92+
93+
* custom object draft that should be created
94+
95+
Please refer to [example in product sync document](PRODUCT_SYNC.md#example-set-publish-stage-if-category-references-of-given-product-draft-exists).
96+
97+
##### 5. `batchSize`
98+
A number that could be used to set the batch size with which custom objects are fetched and processed,
99+
as custom objects are obtained from the target project on commercetools platform in batches for better performance. The
100+
algorithm accumulates up to `batchSize` resources from the input list, then fetches the corresponding custom objects
101+
from the target project on commecetools platform in a single request. Playing with this option can slightly improve or
102+
reduce processing speed. If it is not set, the default batch size is 50 for custom object sync.
103+
##### Example
104+
````java
105+
final CustomObjectSyncOptions customObjectSyncOptions =
106+
CustomObjectSyncOptionsBuilder.of(sphereClient).batchSize(30).build();
107+
````
38108

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

0 commit comments

Comments
 (0)