commercetools Connector v2.0.0 Migration Steps

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Author:

Fluent Commerce

Changed on:

31 Jan 2024

Key Points

The 2.0 Commerce tools connector offers a range of new capabilities in regards to configurations, availability calls and DSK context creation.
The migration requires a few Java changes and configuration changes that are covered in detail in this article.

Steps

New version of the connector

Update the project pom to reference the release of the commercetools connector.

1<parent>
2    <groupId>com.fluentcommerce.connect</groupId>
3    <artifactId>connect-sdk</artifactId>
4    <version>2.0.2</version>
5    <relativePath/>
6</parent>

Note

The new project structure only requires the version of the connector to be set at the parent section of the pom. If you have the another one at the properties like below, either update to the same version as above or remove the property.

1<properties>
2    <!-- NOTE - update the parent package whenever updating this setting - make sure the versions match-->
3    <connect-sdk>1.1.7</connect-sdk>
4    <commercetools.version>9.2.2</commercetools.version>
5</properties>

Java Changes

`MessageHandler` is now an interface. Any references to it must now change from extends to implements.
`HandlerException` has been renamed to `HandlerRetryException`.
`AccountReference` is now a record and access to its members has changed.
`ListenerInfo` package has moved to `com.fluentcommerce.connect.core.listener.external.ListenerInfo`.
`ExternalListener` has been renamed to `BaseExternalListener`.
`ExternalMessageReceiver` package has moved to `com.fluentcommerce.connect.core.listener.external.ExternalMessageReceiver`.
`JobHandler` is now an interface and the `package` has moved to `com.fluentcommerce.connect.core.job.extend.JobHandler`.
`FluentConnectConfiguration` has been renamed to `ApplicationConfigurationService`.
`ExternalMessageReceiver` interface updates.
A number of improvements/changes to `HandlerContext` classes to improve resource access control stay within the account-retailer context.
- Configuration service will automatically prefix configuration/setting keys with the connector configuration namespace. For example, requesting a property named “my-key” for a connector named “my-connector” will result in the configuration service retrieving a setting from Fluent with the following setting key: “`fc.connect.my-connector.my-key`“.
All LocalDateTime usage within the SDK has changed to `ZonedDateTime` and the timezone defaults to UTC regardless of the system timezone.
- There is also a new service `DateService` that can return a proper current datetime in UTC.
Handler routes are now grouped into logical groups.

Configuration Required Changes

application.yml
- The following listener configuration is no longer used and can be removed

1  available-listeners:
2    - "sqs"
3    - "kafka"
4  message-listener-mode: sqs
5  batch-listener-mode: sqs

Job scheduler changes
- Scheduler type has been introduced and by default, it is message-queue which uses the SQS implementation

1  job-scheduler:
2    frequency: 2
3    job-scheduler-type:"message-queue"

Listener configuration should be updated as follows:
- The snippet below brings a new listener for notification and changes for listener types
- Please note that the deployment process also needs to introduce a new variable for SQS_NOTIFICATION to specify the notification queue.
- Remember to review the pool size settings for your project needs
- With the Fluent account being set in the configuration below, remove the following files: `application-dev.yml`, `application-qa.yml`, `application-test.yml` and `application-test2.yml`.

1  listeners:
2    commercetools_events:
3      name: "SQS_CONNECTOR"
4      fluent-account: "CNCTDEV"
5      pool-size: 200
6      prefix: "ct"
7      retry: 5
8      type: "sqs"
9    messages:
10      name: "SQS_EVENTS"
11      pool-size: 200
12      prefix: "msg"
13      retry: 5
14      type: "sqs"
15    batch:
16      name: "SQS_BATCH"
17      pool-size: 5
18      prefix: "job"
19      retry: 1
20      type: "sqs"
21    notification:
22      name: "SQS_NOTIFICATION"
23      prefix: "not"
24      type: "sqs"
25      retry: 5

application-connector.yml
- The configuration below should be removed. The SDK now knows to automatically build these based on the connector-name property.

1  job-scheduler:
2    config-prefix: "fc.connect.commerce-tools.data-sync"
3
4  configuration:
5    base-path-key: "fc.connect.commerce-tools"
6    account-mapping-key: "fc.connect.commerce-tools.account-mapping"
7    general-key: "fc.connect.commerce-tools.general"
8    log-level-key: "fc.connect.commerce-tools.log-level"
9    entity:
10    order:
11      order-status-mapping: "fc.connect.commerce-tools.order.order-status-mapping"
12      payment-status-mapping: "fc.connect.commerce-tools.order.payment-status-mapping"
13      shipping-status-mapping: "fc.connect.commerce-tools.order.shipping-status-mapping"
14      shipping-method-mapping: "fc.connect.commerce-tools.order.shipping-method-mapping"
15    fulfilment:
16      status-mapping: "fc.connect.commerce-tools.fulfilment.status-mapping"
17    unit-conversion-key: "fc.connect.commerce-tools.unit-conversion"

Remove the listener configuration for commercetools_events as it has been consolidated at the application.yml. Alternatively, all listener configurations can be done on this file.
Add the credential setting to specify the manager name

1  credential:
2    credential-manager: "aws-secrets-manager"

Route configuration has changed. All out-of-the-box routes are pre-configured and do not require anything on the yml files unless you have modified those settings. The list provided below is the out-of-the-box commercetools connector routes part of the module and can be removed.

1    - route: "event.failure-summary"
2      handler-name: "EventFailureSummaryJobHandler"
3      props:
4        page-size: 100
5        event-type: ORCHESTRATION_AUDIT
6        event-status: FAILED
7    - route: "batch-location-sync"
8      handler-name: "BatchLocationSyncJob"
9      props:
10        page-size: 500
11    - route: "batch-inventory-sync"
12      handler-name: "InventorySyncJob"
13      props:
14        page-size: 500
15    - route: "batch-product-catalogue-sync"
16      handler-name: "ProductCatalogueSyncJob"
17      props:
18        query: "ct-catalogue-search.graphql"
19        page-size: 500
20    
21    - route: "commercetools.connect.category.upsert"
22      handler-name: "CategoryUpsert"
23      props:
24        query: "ct-category.graphql"
25    - route: "commercetools.connect.customer.upsert"
26      handler-name: "CustomerUpsert"
27      props:
28        query: "ct-customer.graphql"
29    - route: "commercetools.connect.product.upsert"
30      handler-name: "ProductUpsert"
31      props:
32        query: "ct-product.graphql"
33    - route: "commercetools.connect.order.create"
34      handler-name: "OrderCreateHandler"
35      props:
36        query: "ct-order.graphql"
37        mutation: "ct-updateorderNumber.graphql"
38    - route: "fc.connect.order.webhook.order-status-update"
39      handler-name: "OrderStatusUpdateHandler"
40      props:
41        query: "ct-order.graphql"
42        mutation: "ct-updateorder.graphql"
43    - route: "fc.connect.order.webhook.consignment-status-update"
44      handler-name: "ConsignmentStatusUpdateHandler"
45      props:
46        query: "ct-order.graphql"
47        mutation: "ct-updateorder.graphql"
48    - route: "commercetools.connect.inventory.upsert"
49      handler-name: "InventoryUpsertHandler"
50      props:
51        query-inventories: "ct-inventories.graphql"
52        query-channel: "ct-channel.graphql"
53        mutation-create-inventory: "ct-createinventory.graphql"
54        mutation-update-inventory: "ct-updateinventory.graphql"
55    - route: "commercetools.connect.location.upsert"
56      handler-name: "LocationUpsertHandler"
57      props:
58        query-channel: "ct-channel.graphql"
59        mutation-create-channel: "ct-createchannel.graphql"
60        mutation-update-channel: "ct-updatechannel.graphql"
61    - route: "fc.connect.order.webhook.fulfilment-status-update"
62      handler-name: "FulfilmentStatusUpdateHandler"
63      props:
64        query: "ct-order.graphql"
65        mutation: "ct-updateorder.graphql"        
66

If you intend in keeping route configuration in the yml files, please note that there have been some changes to the configuration property name:
- `name` property has been renamed to “route” and the “handler” has changed to `handler-name`.
- There is also a new way to group routes. All routes must be under a new parent “route:” property and each kind of route goes under its type

1  routes:
2    message: 
3    job:
4    notification:

Configuration Optional Changes

Docker optional changes

1FROM openjdk:17.0.2-slim
2
3RUN addgroup spring --system && adduser spring --system --no-create-home --disabled-password --disabled-login --ingroup spring
4RUN mkdir -p /usr/service/logs
5RUN chown -R spring:spring /usr/service/
6
7ARG version=latest
8COPY target/fluent-connector-${version}.jar /usr/service/connector.jar
9
10USER spring:spring
11WORKDIR /usr/service/
12
13CMD [ "java","-jar", "connector.jar", "--spring.profiles.active=connector,${ENVIRONMENT:production}" ]

Copyright © 2024-2026 Fluent Retail Pty Ltd (trading as Fluent Commerce). Unless otherwise expressly stated in a current written agreement with Fluent Commerce or any of its affiliates or on any single page of the docs.fluentcommerce.com site, use of the materials on this site is strictly limited to viewing by individuals over 18 years old for legitimate commercially appropriate reasons; and any downloading, copying or other actions or uses of any kind or by any means of the materials on this site, including by artificial intelligence tools, is strictly prohibited. All other rights reserved.

Java Changes

`MessageHandler` is now an interface. Any references to it must now change from extends to implements.
`HandlerException` has been renamed to `HandlerRetryException`.
`AccountReference` is now a record and access to its members has changed.
`ListenerInfo` package has moved to `com.fluentcommerce.connect.core.listener.external.ListenerInfo`.
`ExternalListener` has been renamed to `BaseExternalListener`.
`ExternalMessageReceiver` package has moved to `com.fluentcommerce.connect.core.listener.external.ExternalMessageReceiver`.
`JobHandler` is now an interface and the `package` has moved to `com.fluentcommerce.connect.core.job.extend.JobHandler`.
`FluentConnectConfiguration` has been renamed to `ApplicationConfigurationService`.
`ExternalMessageReceiver` interface updates.
A number of improvements/changes to `HandlerContext` classes to improve resource access control stay within the account-retailer context.
- Configuration service will automatically prefix configuration/setting keys with the connector configuration namespace. For example, requesting a property named “my-key” for a connector named “my-connector” will result in the configuration service retrieving a setting from Fluent with the following setting key: “`fc.connect.my-connector.my-key`“.
All LocalDateTime usage within the SDK has changed to `ZonedDateTime` and the timezone defaults to UTC regardless of the system timezone.
- There is also a new service `DateService` that can return a proper current datetime in UTC.
Handler routes are now grouped into logical groups.

Configuration Required Changes

application.yml
- The following listener configuration is no longer used and can be removed

1  available-listeners:
2    - "sqs"
3    - "kafka"
4  message-listener-mode: sqs
5  batch-listener-mode: sqs

Job scheduler changes
- Scheduler type has been introduced and by default, it is message-queue which uses the SQS implementation

1  job-scheduler:
2    frequency: 2
3    job-scheduler-type:"message-queue"

Listener configuration should be updated as follows:
- The snippet below brings a new listener for notification and changes for listener types
- Please note that the deployment process also needs to introduce a new variable for SQS_NOTIFICATION to specify the notification queue.
- Remember to review the pool size settings for your project needs
- With the Fluent account being set in the configuration below, remove the following files: `application-dev.yml`, `application-qa.yml`, `application-test.yml` and `application-test2.yml`.

1  listeners:
2    commercetools_events:
3      name: "SQS_CONNECTOR"
4      fluent-account: "CNCTDEV"
5      pool-size: 200
6      prefix: "ct"
7      retry: 5
8      type: "sqs"
9    messages:
10      name: "SQS_EVENTS"
11      pool-size: 200
12      prefix: "msg"
13      retry: 5
14      type: "sqs"
15    batch:
16      name: "SQS_BATCH"
17      pool-size: 5
18      prefix: "job"
19      retry: 1
20      type: "sqs"
21    notification:
22      name: "SQS_NOTIFICATION"
23      prefix: "not"
24      type: "sqs"
25      retry: 5

application-connector.yml
- The configuration below should be removed. The SDK now knows to automatically build these based on the connector-name property.

1  job-scheduler:
2    config-prefix: "fc.connect.commerce-tools.data-sync"
3
4  configuration:
5    base-path-key: "fc.connect.commerce-tools"
6    account-mapping-key: "fc.connect.commerce-tools.account-mapping"
7    general-key: "fc.connect.commerce-tools.general"
8    log-level-key: "fc.connect.commerce-tools.log-level"
9    entity:
10    order:
11      order-status-mapping: "fc.connect.commerce-tools.order.order-status-mapping"
12      payment-status-mapping: "fc.connect.commerce-tools.order.payment-status-mapping"
13      shipping-status-mapping: "fc.connect.commerce-tools.order.shipping-status-mapping"
14      shipping-method-mapping: "fc.connect.commerce-tools.order.shipping-method-mapping"
15    fulfilment:
16      status-mapping: "fc.connect.commerce-tools.fulfilment.status-mapping"
17    unit-conversion-key: "fc.connect.commerce-tools.unit-conversion"

Remove the listener configuration for commercetools_events as it has been consolidated at the application.yml. Alternatively, all listener configurations can be done on this file.
Add the credential setting to specify the manager name

1  credential:
2    credential-manager: "aws-secrets-manager"

Route configuration has changed. All out-of-the-box routes are pre-configured and do not require anything on the yml files unless you have modified those settings. The list provided below is the out-of-the-box commercetools connector routes part of the module and can be removed.

1    - route: "event.failure-summary"
2      handler-name: "EventFailureSummaryJobHandler"
3      props:
4        page-size: 100
5        event-type: ORCHESTRATION_AUDIT
6        event-status: FAILED
7    - route: "batch-location-sync"
8      handler-name: "BatchLocationSyncJob"
9      props:
10        page-size: 500
11    - route: "batch-inventory-sync"
12      handler-name: "InventorySyncJob"
13      props:
14        page-size: 500
15    - route: "batch-product-catalogue-sync"
16      handler-name: "ProductCatalogueSyncJob"
17      props:
18        query: "ct-catalogue-search.graphql"
19        page-size: 500
20    
21    - route: "commercetools.connect.category.upsert"
22      handler-name: "CategoryUpsert"
23      props:
24        query: "ct-category.graphql"
25    - route: "commercetools.connect.customer.upsert"
26      handler-name: "CustomerUpsert"
27      props:
28        query: "ct-customer.graphql"
29    - route: "commercetools.connect.product.upsert"
30      handler-name: "ProductUpsert"
31      props:
32        query: "ct-product.graphql"
33    - route: "commercetools.connect.order.create"
34      handler-name: "OrderCreateHandler"
35      props:
36        query: "ct-order.graphql"
37        mutation: "ct-updateorderNumber.graphql"
38    - route: "fc.connect.order.webhook.order-status-update"
39      handler-name: "OrderStatusUpdateHandler"
40      props:
41        query: "ct-order.graphql"
42        mutation: "ct-updateorder.graphql"
43    - route: "fc.connect.order.webhook.consignment-status-update"
44      handler-name: "ConsignmentStatusUpdateHandler"
45      props:
46        query: "ct-order.graphql"
47        mutation: "ct-updateorder.graphql"
48    - route: "commercetools.connect.inventory.upsert"
49      handler-name: "InventoryUpsertHandler"
50      props:
51        query-inventories: "ct-inventories.graphql"
52        query-channel: "ct-channel.graphql"
53        mutation-create-inventory: "ct-createinventory.graphql"
54        mutation-update-inventory: "ct-updateinventory.graphql"
55    - route: "commercetools.connect.location.upsert"
56      handler-name: "LocationUpsertHandler"
57      props:
58        query-channel: "ct-channel.graphql"
59        mutation-create-channel: "ct-createchannel.graphql"
60        mutation-update-channel: "ct-updatechannel.graphql"
61    - route: "fc.connect.order.webhook.fulfilment-status-update"
62      handler-name: "FulfilmentStatusUpdateHandler"
63      props:
64        query: "ct-order.graphql"
65        mutation: "ct-updateorder.graphql"        
66

If you intend in keeping route configuration in the yml files, please note that there have been some changes to the configuration property name:
- `name` property has been renamed to “route” and the “handler” has changed to `handler-name`.
- There is also a new way to group routes. All routes must be under a new parent “route:” property and each kind of route goes under its type

1  routes:
2    message: 
3    job:
4    notification:

commercetools Connector v2.0.0 Migration Steps

Key Points

Steps

New version of the connector

Java Changes

Configuration Required Changes

Configuration Optional Changes

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links

New version of the connector

Java Changes

Configuration Required Changes

Configuration Optional Changes