Create an integration server

Use our sample template to create an integration server that integrates InStore with Composable Commerce.

We provide modifiable templates that include the InStore modular store, InStore core modules, Composable Commerce, and a secure integration layer so the components can communicate. This guide describes how to build the integration server, which is sometimes referred to as a backend-for-frontend (BFF) server.

We recommend using the integration server, but you can choose a component-based microservice approach instead if you prefer.

Set up one integration server per InStore tenant environment. For example, if you have one test environment and one production environment, set up two integration servers.

What is the integration server

The integration server handles tasks that InStore itself does not support, including but not limited to:

Authenticating users of the InStore colleague app via your identity provider
Loading startup configuration
Adding and removing cart items
Loading customer and loyalty information
Loading catalog and discount information
Transferring and tracking your order management system, fulfillment, shipping options, and taxation information

Payment information does not pass through the integration server. Instead, it is communicated directly to the InStore APIs. For more information about the structures that handle cash management and payment operations, see Callbacks and Webhooks.

It is your responsibility to build and maintain the integration server. The template repository is a starting point only, and you must not use it in production environments without first enhancing its security and resiliency.

To use the integration server, you must have credentials that we provide you. If you do not have these, contact the InStore support team.

Prerequisites

Node.js v18.20.5 LTS
A Composable Commerce API client with the scopes required for store operations
A Composable Commerce Project with the following components:
- Product Type
- Types:
  - Cart
  - Order
  - Category
  - LineItem
  - Payment
  - Transaction

You can use our sample Terraform scripts as a starting point to create the default configurations or modify them to suit your needs.

Install the integration template repository

To install the repository, clone the mist-integration-server repository using your preferred method.

Set up and configure the integration server

When setting up your integration server, connect it to your Composable Commerce Project. This is a many-to-one relationship, with all integration servers sharing the same Project.

To set up and configure the integration server, do the following:

Run the following in the mist-integration-server directory:
```
npm install
```
Add a .env file to your server directory that includes InStore, Composable Commerce, and MongoDB environment variables from the tables below. You can use our sample.env file as a template.

InStore environment variables

Parameter	Description
`WEBHOOK_VERIFICATION`	Verification key that you defined in the InStore Center on the Integration Settings tab for the environment.
`CALLBACK_KEY`	Callback key that is defined in the InStore Center on the Integration Settings tab for the environment.
`CUSTOM_PAYMENT_VERIFICATION_KEY`	If you configure a custom payment processor, the verification keys for the payment processor must match the value you define for this variable.
`WHITELISTED_DOMAINS`	Comma-separated list of all frontend apps that connect to the integration server, including your hosted colleague app. This is required for cross-origin resource sharing (CORS) support. For example, add `http://localhost:8080` for the local instance of the Modular Store app.
`SERVER_HOST`	URL for the InStore API server, for example `https://api.us-east-2.aws.commercetools.com/`. It is provided by commercetools.
`IN_STORE_LINEITEM_TYPE`	Value of the key you defined for this custom type. The value must match the value set for this field in the InStore Center on the Project Settings tab.
`IN_STORE_ORDER_TYPE`	Value of the key you defined for this custom type. The value must match the value set for this field in the InStore Center on the Project Settings tab.

Composable Commerce environment variables

Parameter	Description
`CTP_PROJECT_KEY`	Composable Commerce project key
`CTP_CLIENT_ID`	Composable Commerce client ID
`CTP_CLIENT_SECRET`	Composable Commerce API client secret
`CTP_AUTH_URL`	Composable Commerce authorization URL
`CTP_HOST`	Composable Commerce API URL
`CTP_SCOPES`	Composable Commerce scopes

MongoDB environment variables

The following variables are used for user management in the demo instance:

Parameter	Description
`DB_NAME`	Integration database name
`MONGO_USER`	Username
`MONGO_PASSWORD`	Password
`MONGO_HOST`	Database cluster address

(Optional) Update the PORT. The port number defaults to 5001.
Start the application from your local directory using npm start.
Test the server at http://localhost:5001/. The response should be "Hello World!". Adjust the port number if you changed it during the setup.

Populate the InStore Center with integration server data

After establishing the integration server URL, enter it in the InStore Center so the frontend can communicate with the integration server.

On the Integration Settings tab of the Environment page, the following fields require the integration server URL as a prefix:

Webhook URL
Cart Retrieval URL
Token Retrieval URL
Key Sync URL
Return Cart Retrieval URL

Create an integration server

What is the integration server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Prerequisites.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Install the integration template repository.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set up and configure the integration server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

InStore environment variables.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Composable Commerce environment variables.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

MongoDB environment variables.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}