Configure brX GraphQL Service

Info: The brX GraphQL Service feature in Bloomreach Content requires a standard or premium license. Contact Bloomreach for licensing details.

Overview

The brX GraphQL Service uses an environment configuration file (.env) to connect to your Commerce Backend Platform. This file defines connection details and other configuration options required for integration.

Environment Configuration File

The brX GraphQL Service expects a .env file in the project root directory. A sample file named .env.dist is provided in the project root. Copy .env.dist to .env and update the values to match your environment.

The .env file contains three groups of configuration options:

General Options: Settings that apply to the brX GraphQL Service regardless of the Commerce Backend Platform.
Bloomreach Discovery Connection Settings: Parameters required to connect to Bloomreach Discovery.
Commerce Backend Platform Connection Settings: Parameters for connecting to your selected Commerce Backend Platform(s).

Example .env file (lines starting with # are comments):

# 1. General Options

NODE_ENV=production
LOG_LEVEL=info 
DEBUG_TRACE_PAYLOAD=false
APOLLO_INTROSPECTION=true
APOLLO_PLAYGROUND=true
JWK_KEYSTORE={ ...SNIP... }
DEFAULT_CONNECTOR_ID=...SNIP...

# 2. brSM Connection Settings

BRSM_API=...SNIP...
BRSM_SUGGEST_API=...SNIP...
BRSM_ACCOUNT_ID=...SNIP...
BRSM_DOMAIN_KEY=...SNIP...

# 3. Commerce Backend Platform Connection Settings (commercetools in this example)

COMMERCETOOLS_API_BASE_URL=...SNIP...
COMMERCETOOLS_AUTH_BASE_URL=...SNIP...
COMMERCETOOLS_PROJECT_KEY=...SNIP...
COMMERCETOOLS_CLIENT_ID=...SNIP...
COMMERCETOOLS_CLIENT_SECRET=...SNIP...
COMMERCETOOLS_SCOPE=...SNIP...

# ... More Commerce Backend Platform Connection Options may follow ...
#

General Options

The following environment variables are supported:

Property Name	Description	Default Value
NODE_ENV	Sets the environment for Express and Apollo Server. For example, setting this to `development` enables detailed logging for HTTP requests. Setting it to `production` disables development features such as the Apollo Server GraphQL Playground.
PORT	Specifies the port on which the brX GraphQL Service runs.	4000
LOG_LEVEL	Sets the minimum log level for output. The service uses the Winston logging library. Refer to the Winston documentation for available log levels.	'info'
DEBUG_TRACE_PAYLOAD	If set to `true`, the service logs responses from the Commerce Backend Platform for debugging. Do not enable this in production environments.	'false'
APOLLO_INTROSPECTION	Enables Apollo Server Introspection to expose detailed schema information if set to `true`.	'false'
APOLLO_PLAYGROUND	Enables the Apollo Server GraphQL Playground in-browser IDE for development if set to `true`.	'false'
JWK_KEYSTORE	Defines the keystore configuration used to generate secure, encrypted access tokens for visitors. See Access Management in brX GraphQL Service for details.
CORS_ORIGIN	Specifies the allowed origin for Cross-Origin Resource Sharing (CORS). If unset or empty, the service allows requests with a valid 'Origin' header. Use `*` to allow all origins, or specify a URL to restrict access.
TOKEN_REFRESH_ENABLED	Enables the Refreshing Access Token request for Access Management if set to `true`. Disabled by default since v14.3.0.
DEFAULT_CONNECTOR_ID	If the HTTP request does not provide a valid Commerce Connector ID in the `connector` header, the service uses this value.	'brsm'
DEFAULT_LANGUAGE	Sets the default language code for clients.	'en'
DEFAULT_COUNTRY	Sets the default country code for clients.	'US'
DEFAULT_CURRENCY	Sets the default currency code for clients.	'USD'
RESPONSE_TIME_HEADER_ENABLED	If set to `true`, the service includes the internal response time (in milliseconds) in the `X-Response-Time` response header.

Supported Connectors and Connector IDs

The brX GraphQL Service supports Bloomreach Discovery and several Commerce Backend Platforms. Each platform is identified by a unique connector value in the request header.

Supported connectors:

Bloomreach Discovery Connector Configuration (connector header: brsm)
Commercetools Connector Configuration (connector header: commercetools)
SAP Connector Configuration (connector header: sap)
Shopify Connector Configuration (connector header: shopify)
Shopizer Connector Configuration (connector header: shopizer)
BigCommerce Connector Configuration (connector header: bigcommerce)