Configure brX GraphQL Service

Introduction

The brX GraphQL Service reads the environment configuration from .env file to integrate with the Commerce Backend Platform. The .env file contains the connection information to the Commerce Backend Platform and other configuration options.

GraphQL Commerce URLs

The brX GraphQL Service is available at the following URLs:

Additionally, any requests to the GraphQL Server should include the br-acct-env request header. The value should match your Bloomreach Content account name, defined as part of the Bloomreach Content instance URL https://[account_name].bloomreach.io.

If you are not using these URLs in both staging and production, please make sure to update your configurations as explained in the following paragraphs.

Backend

Please execute the following steps:

Please repeat the steps above for all the Content channels dealing with the GraphQL Commerce.

Frontend

If your front-end implementation uses the Commerce React Components library, then:

  • Make sure that your front-end implementations use the latest version of the library
  • Add (or edit) the accountEnvId parameter to any occurrence of the CommerceConnectorProvider React component, like the following:
<CommerceConnectorProvider
   graphqlServiceUrl={graphqlServiceUrl}
   ...
   accountEnvId="[account_name]"
 >
 …
 </CommerceConnectorProvider>

If your front-end does not use the Commerce React Components library, please make sure to update your GraphQL client(s), in order to inject the requested header.

Once both the front-end and back-end changes have been tested, execute the following steps in this order:

  • Deploy the new front-end changes
  • Merge your project to the core branch

Environment Configuration File

The brX GraphQL Service requires the environment configuration file named .env in the project root folder. An example file is provided as .env.dist in the project root folder, so you can copy the file to .env first and edit the content with correct information.

The .env file consists of the three groups of configuration options:

  1. General Options: the options which are generally applied to the brX GraphQL Service, regardless of the specific Commerce Backend Platform.
  2. Bloomreach Search and Merchandising Connection Settings: the connection settings to integrate with Bloomreach Search and Merchandising.
  3. Commerce Backend Platform Connection Settings: the connection settings to integrate with the specific Commerce Backend Platform(s).

An example .env file looks like the following (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 options are supported:

Property Name (* required field)DescriptionDefault Value
APOLLO_INTROSPECTIONIf set to 'true', the Apollo Server Introspection technique is enabled to provide detailed information about a GraphQL API's schema.'false'
APOLLO_PLAYGROUNDIf set to 'true', the Apollo Server GraphQL Playground, the in-browser IDE for GraphQL development and workflow, is enabled to provide developers with features such as theme change, automatic schema reloading, HTTP headers configuration, query history and GraphQL subscription support.'false'
CORS_ORIGINThe allowed origin which wants to access the brX GraphQL Service as a Cross-Origin Resource Sharing target.
If this is not set or set to an empty string, then the brX GraphQL Service allows access to the clients sending a valid 'Origin' request header.
If set to '*', then the brX GraphQL Service allows access to any clients.
If set to a specific URL (e.g, https://www.example.com), then the brX GraphQL Service allows access only to the clients which are originated from the URL.
TOKEN_REFRESH_ENABLEDIf set to 'true', the Refreshing Access Token request against Access Management is enabled on the brX GraphQL Service. This option has been disabled by default since v14.3.0.
DEFAULT_CONNECTOR_IDbrX GraphQL Services reads the Commerce Connector ID from the HTTP request header named 'connector'. If the GraphQL client does not provide a valid Commerce Connector ID value, then this variable is used instead.'brsm'
DEFAULT_LANGUAGEThe default language code for the client.'en'
DEFAULT_COUNTRYThe default country code for the client.'US'
DEFAULT_CURRENCYThe default currency code for the client.'USD'
RESPONSE_TIME_HEADER_ENABLEDIf set to 'true', the internal response time in milliseconds measured in the brX GraphQL Service is passed in the X-Response-Time response header.

brX Discovery and Commerce Backend Platform Connection Settings and Connector IDs

BrX Discovery and the following Commerce Backend Platforms are supported (differentiated by each unique 'connector' identifier in request header):

How to request configuration changes?

Please use our support channel to request configuration changes, including properties name and value(s).