commercetools Configurations
Introduction
Bloomreach Experience Manager can be instantaneously integrated with commercetools when using Bloomreach Accelerator: B2C Commerce. The boot application contains all the configurations needed to interact with your commercetools instance.
This page focuses on two points:
- How to connect to your commercetools instance
- A high-level description of commercetools connector configurations.
Connect a commercetools instance
commercetools is a cloud based commerce API solution. The Bloomreach Accelerator: B2C Commerce boot application already provides a CRISP resource able to connect to your instance. The related configuration can be found at the following repository path:
/hippo:configuration/hippo:modules/crispregistry/hippo:moduleconfig/crisp:resourceresolvercontainer/commercetools
You need to provide your specific connection properties explained in the table below:
| Property name | Description |
| commercetools.baseUrl | The base url of your commercetools instance (e.g https://api.sphere.io/<name_of_your_project> |
| commercetools.accessTokenUri |
The uri need to obtain your access token throught the credentials flow (e.g. https://auth.sphere.io/oauth/token?grant_type=client_credentials&scope=manage_project:<name_of_your_project>) |
| commercetools.clientId | OAuth 2 client id generated for your project |
| commercetools.clientSecret | OAuth 2 client secret generated for your project |
| commercetools.username | Your commercetools username |
| commercetools.password | Your commercetools password |
Those API client data can be configured directly in your commercetools instance, more specifically on the following page: https://mc.commercetools.com/<project_name>/settings/developer/api-clients.
Those properties can be defined directly in the hst.properties. The Bloomreach Accelerator: B2C Commerce Boot Application contains a root folder called conf: among others, this folder contains a properties file called hst.properties. You can define the properties as in the example below (replace project name):
.. commercetools.baseUrl = https://api.sphere.io/<project_name>/ commercetools.accessTokenUri = https://auth.sphere.io/oauth/token?grant_type=client_credentials&scope=manage_project:<project_name> commercetools.clientId = <client_id> commercetools.clientSecret = <client_secret> commercetools.username = <commercetools_username> commercetools.password = <commercetools_password> ..
Connector configurations
The Bloomreach Accelerator: B2C Commerce boot application already provides a commerce connector definition for commercetools: you can find it in the Default Commerce Connector Set document, under the commerce-connectors folder, with the Connector ID with value commercetools.
This connector is "associated" by name to a specific mapping bundle document: in this specific case with the resource bundle document with ID "starterstore.mapping.commercetools". You will find this document in the mappings folder, under administration.
The Resource space property matches with commercetools CRISP resource name.
The table below contains all the Connector components used for the commercetools connector. For each component you will find a short description and all the context "variables" (resolved at runtime) needed to perform the external request.
|
Component ID |
Description | Context Variables |
|
productDetail |
Retrieve the details of product |
externalReferenceId: the product id (specified in the URL) |
| productList | Retrieve a list of products |
|
| facetList | Return a list of products filtered by the facet |
locale: the text search locale, useful for multi language search starterstoreQueryParam_query: string query parameter (moreover, facet values can be customized in the configuration) |
| productSearch | Return a list of products based on the query parameter |
starterstoreQueryParam_pageSize: the limit of your query result. starterstoreQueryParam_offset: the offset of your query result locale: the text search locale, needed for multi language search starterstoreQueryParam_query: string query parameter starterstoreQueryParam_facetQuery: used to filter the query by facet values categories: used to filter the query by category id |
| productSearchByCategory | Like productSearch, but using a categories filter. |
externalReferenceId: the category id specified starterstoreQueryParam_pageSize: the limit of your query result. starterstoreQueryParam_offset: the offset of your query result locale: the text search locale, needed for multi language search starterstoreQueryParam_query: string query parameter starterstoreQueryParam_facetQuery: used to filter the query by facet values |
| categoriesList | Return a list of categories | |
|
categoryDetail |
Fetch the details of a specific category | externalReferenceId: the category id specified in the request |
| categorydecorator | This component is used by the category decorator document type, more specifically by the external document picker plugin. | |
| productdecorator | This component is used by the product decorator document type, more specifically by the external document picker plugin. |
starterstoreQueryParam_query: string query parameter specified in the modal window id: in case this parameter is specified, then the search result will display only the product with that id |
| createCustomer | Create a new customer |
anonymousCartId: if present, this represent anonymous cart id associated to the user before the registration process. customer: represent the Customer object containing user data |
| getCustomer | Retrieve customer data | storeUser: Bloomreach Accelerator: B2C Commerce user object |
| updateCustomer | Update customer data | customer: represent the Customer object containing e-commerce user data |
| deleteCustomer | Delete customer from the back-end | |
| cartCreate | Cart creation |
cartCurrency: specify the currency of the cart, useful in case of multi-currency country: needed to establish the availability of a product in specific region/country storeUser: Bloomreach Accelerator: B2C Commerce user object |
| cartDelete | Cart Deletion | cartId |
| cartProductList | Retrieve a cart object containing the status of the cart, including the assigned product | cartId |
| cartProductAdd | Add a new or existing product to the cart. |
cartVersion: cart revision cartProductId: product Id |
|
cartProductUpdate |
Update the item quantity |
cartVersion: cart revision cartItemId: id of the item to be updated cartItemQuantity: new quantity of the cart item |
| cartProductRemove | Remove a product from the cart |
cartVersion: cart revision cartItemId: id of the item to be removed |
|
cartCustomerUpdate |
Update the cart "owner" |
cartVersion: cart revision storeUser: Bloomreach Accelerator: B2C Commerce user |
| authenticateCustomer | User authentication against commercetools instance |
anonymousCartId: anonymous cart associated to the user before the authentication process customer: represent the Customer object containing user data |
| orderQuery | Retrieves the list of orders for a specific user | storeUser: Bloomreach Accelerator: B2C Commerce user object |
| changeCustomerPassword | Replace customer password |
customerInBackend: Customer object with the latest revision customer: represent the Customer object containing the new user data |
| updateCustomerAddresses | Update customer addresses |
customerInBackend: Customer object with the latest revision customer: represent the Customer object containing new user data
|
| updateCustomerDefaultAddresses | Set the customer default address |
customerInBackend: Customer object with the latest revision customer: represent the Customer object containing new user data |
| removeCustomerAddresses | Remove customer addresses |
customerInBackend: Customer object with the latest revision customer: represent the Customer object containing new user data |
| paymentCreate | Create a payment entry in the commercetools instance |
cartId cartCurrency: useful in case of multi-currency website cartAmount: total amount of cart products |
| orderCreate | Create an order in the commerce backend |
cartVersion: cart revision cartId |
| cartShipmentMethodUpdate | Update the cart shipment method |
cartId cartVersion: cart revision shippingMethodReference: an internal reference to the shipment method |
| cartShipmentAddressUpdate | Update the cart shipment address |
cartId cartVersion: cart revision address: Address object defined in Bloomreach Accelerator: B2C Commerce |
When copying products from commercetools into brSM, a "link" needs to be created between the original product stored in the commerce backend and the related copy stored in brSM. In other words, brSM needs to store product specific data which can be used to retrieve the same product from the commerce backend.
brSM provides a standard field, called variant, in which product SKUs can be stored. In case products are copied from commercetools, the SKU must contain the value stored in the product key field.