Configuring the Discovery Plugin

The Discovery plugin retrieves its configuration from three sources, which are merged at request time: a global JCR node shared by all channels, optional per-channel overrides, and coded defaults for any unset values. Only three credential values are required for a functional installation; all other settings are optional.

ON THIS PAGE

How resolution works
The global configuration node
Injecting credentials
Environments and staging
Per-channel overrides
The product field list (fl)
Sort options
Picker field mapping
Circuit breaker tuning
Verifying configuration

How resolution works

Global JCR node            Per-channel hst:channelinfo
─────────────────────      ───────────────────────────
accountId                  discoveryAccountId (override)
domainKey                  discoveryDomainKey (override)
apiKey                     discoveryApiKeyEnvVar (override)
authKey                    discoveryAuthKeyEnvVar (override)
defaultFieldList     ←     discoveryDefaultFieldList (override)
defaultPageSize
defaultSort
sortOptions
environment

Global node: Shared by all channels. Use this for deployment-wide settings such as credentials, the default field list, page size, and sort options.
Per-channel overrides: Optional. Configure these on hst:channelinfo if different channels require different Discovery accounts or catalog schemas.
At request time, the plugin uses the channel override if set; otherwise, it falls back to the global node value; if neither is set, the coded default applies.

Credential values (accountId, domainKey, apiKey, authKey, environment) are resolved in this order: environment variable → system property → JCR. This allows you to keep secrets out of JCR in production environments.

The global configuration node

The plugin reads configuration from a single, fixed JCR node:

/hippo:configuration/hippo:modules/brxm-discovery/hippo:moduleconfig/discoveryConfig

Bloomreach console showing discoveryConfig node properties

You can create this node using your project's bootstrap configuration:

definitions:
  config:
    /hippo:configuration/hippo:modules/brxm-discovery/hippo:moduleconfig/discoveryConfig:
      jcr:primaryType: brxdis:discoveryConfig
      brxdis:accountId: 'your-account-id'
      brxdis:domainKey: 'your-domain-key'
      brxdis:apiKey: ''
      brxdis:authKey: ''
      brxdis:environment: 'PRODUCTION'
      brxdis:defaultPageSize: 12
      brxdis:defaultSort: ''

Only accountId, domainKey, and apiKey are required. Leave apiKey (and authKey, if used) blank in the JCR and inject them using environment variables. See Injecting credentials for details. The node itself is optional; if it does not exist, the plugin uses environment variables, system properties, and coded defaults for configuration.

Injecting credentials

For instructions on generating or rotating your API key and auth key, refer to the Discovery API Key Management documentation.

Setting	Environment variable	System property	JCR property	Required
Account ID	BRXDIS_ACCOUNT_ID	brxdis.accountId	brxdis:accountId	Yes
Domain Key	BRXDIS_DOMAIN_KEY	brxdis.domainKey	brxdis:domainKey	Yes
API Key	BRXDIS_API_KEY	brxdis.apiKey	brxdis:apiKey	Yes
Auth Key	BRXDIS_AUTH_KEY	brxdis.authKey	brxdis:authKey	No — required only for recommendation/visual-search features that use the v2 Pathways API
Environment	BRXDIS_ENVIRONMENT	brxdis.environment	brxdis:environment	No — defaults to PRODUCTION

Production (containers / Kubernetes):

env:
  - name: BRXDIS_ACCOUNT_ID
    valueFrom: { secretKeyRef: { name: discovery-credentials, key: accountId } }
  - name: BRXDIS_DOMAIN_KEY
    valueFrom: { secretKeyRef: { name: discovery-credentials, key: domainKey } }
  - name: BRXDIS_API_KEY
    valueFrom: { secretKeyRef: { name: discovery-credentials, key: apiKey } }

Local development:

mvn -P cargo.run cargo:run \
  -Dbrxdis.accountId=YOUR_ACCOUNT_ID \
  -Dbrxdis.domainKey=YOUR_DOMAIN_KEY \
  -Dbrxdis.apiKey=YOUR_API_KEY

accountId and domainKey are identifiers and can be stored in JCR if needed. apiKey and authKey are secrets and should be provided via environment variables or system properties in production environments.

Environments and staging

Set the environment to STAGING to direct all Discovery API calls to Bloomreach's staging tier:

API	Production	Staging
Search / category	core.dxpapi.com	staging-core.dxpapi.com
Recommendations (Pathways)	pathways.dxpapi.com	pathways-staging.dxpapi.com
Autosuggest	suggest.dxpapi.com	staging-suggest.dxpapi.com

If you explicitly set a base URI (brxdis:baseUri, brxdis:pathwaysBaseUri, brxdis:autosuggestBaseUri), that value takes precedence over the environment-derived default. Changes to the environment property in JCR are applied on the next request; a restart is not required.

Per-channel overrides

Use per-channel configuration when your deployment includes multiple channels that require different Discovery accounts or catalog schemas. This configuration is exposed through the plugin's DiscoveryChannelInfo interface and can be edited in Channel Manager under Channel Settings.

Channel settings form for Bloomreach Content Discovery plugin configuration

Group	Properties
Credentials	discoveryAccountId, discoveryDomainKey, discoveryApiKeyEnvVar, discoveryAuthKeyEnvVar
Schema	discoveryDefaultFieldList, discoveryCatalogName
Pixel tracking	discoveryPixelsEnabled, discoveryPixelConsentCookie, discoveryPixelTestData, discoveryPixelDebug, discoveryPixelRegion
Visual search	discoveryVisualSearchEnabled, discoveryVisualSearchWidgetId

discoveryApiKeyEnvVar and discoveryAuthKeyEnvVar are pointers to environment variables, not secrets themselves. This ensures secrets are not stored in JCR, even at the channel level.

/hst:hst/hst:configurations/<your-site>/hst:workspace/hst:channel/hst:channelinfo:
  jcr:primaryType: hst:channelinfo
  discoveryAccountId: '7291'
  discoveryDomainKey: 'petstore-uk'
  discoveryApiKeyEnvVar: BRXDIS_API_KEY_PETSTORE_UK
  discoveryDefaultFieldList: 'pid,title,thumb_image,url,price,brand,sale_price,description'

To enable channel-level overrides, set hst:channelinfoclass on the channel node to DiscoveryChannelInfo (or a composite interface that extends your project's existing channel-info type):

/hst:hst/hst:configurations/<your-site>/hst:workspace/hst:channel:
  jcr:primaryType: hst:channel
  hst:channelinfoclass: org.bloomreach.forge.discovery.site.component.info.DiscoveryChannelInfo

For details on pixel tracking fields, see Pixel Tracking & Consent. For visual search fields, see Recommendations & Visual Search.

The product field list (fl)

The field list determines which product attributes Discovery returns. These fields are available in ProductSummary.attributes for templates and the Page Model API.

The default field list includes all attributes used by the bundled templates:

pid,title,thumb_image,url,price,brand,sale_price,description

If your catalog includes custom attributes (for example, pet_type, tags), set brxdis:defaultFieldList on the global node or discoveryDefaultFieldList per channel to the complete list you require. The value you set replaces the default; it does not append to it.

Sort options

The sort dropdown in the component editor and the sortOptions key in the Page Model API both use the brxdis:sortOptions property:

brxdis:sortOptions:
  - 'price asc=Price: Low to High'
  - 'price desc=Price: High to Low'
  - 'name asc=Name: A-Z'
  - 'name desc=Name: Z-A'

Each entry uses the format value=Display label. If this property is not set, the plugin uses the four options shown above as defaults.

Picker field mapping

The CMS picker (used by the Category and Recommendation document pickers and the REST endpoints under ws/discovery/picker/) requires mappings for product ID, title, image, and price fields. These settings are defined only on the global JCR node. There are no environment variable, system property, or per-channel overrides for these properties, as they describe your catalog schema.

Property	JCR property	Default
ID field	brxdis:pickerIdField	pid
Title field	brxdis:pickerTitleField	title
Image field	brxdis:pickerImageField	thumb_image
Price field	brxdis:pickerPriceField	price

/hippo:configuration/hippo:modules/brxm-discovery/hippo:moduleconfig/discoveryConfig:
  brxdis:pickerIdField: 'pid'
  brxdis:pickerTitleField: 'title'
  brxdis:pickerImageField: 'thumb_image'
  brxdis:pickerPriceField: 'price'

Change these properties only if your feed uses different field names. For example, if your feed uses productName for the title, set brxdis:pickerTitleField: 'productName'. Ensure that any field you set here is also included in the field list (fl), or the picker request will not retrieve it.

Circuit breaker tuning

All outbound Discovery calls use a per-host Resilience4j circuit breaker (CircuitBreakerDiscoveryTransport). This isolates failures or slow responses from one Discovery API (such as recommendations) so they do not affect others (such as search). The circuit breaker opens after a threshold of failures within a sliding window and blocks new calls for a cooldown period before retrying.

These settings are intended for operational tuning and are resolved in this order: environment variable → system property → coded default. They are not available in JCR, as they are meant to be adjusted per deployment environment.

Setting	Environment variable	System property	Default
Failure rate threshold (%)	BRXDIS_CB_FAILURE_RATE_THRESHOLD	brxdis.cb.failureRateThreshold	50
Sliding window size (calls)	BRXDIS_CB_SLIDING_WINDOW_SIZE	brxdis.cb.slidingWindowSize	20
Minimum number of calls	BRXDIS_CB_MINIMUM_NUMBER_OF_CALLS	brxdis.cb.minimumNumberOfCalls	10
Wait duration in open state (seconds)	BRXDIS_CB_WAIT_DURATION_IN_OPEN_STATE_SECONDS	brxdis.cb.waitDurationInOpenStateSeconds	30

With the default settings: after at least 10 calls in a rolling window of 20, if 50% or more fail, the breaker opens and blocks further calls for 30 seconds before allowing a test call.

mvn -P cargo.run cargo:run \
  -Dbrxdis.cb.failureRateThreshold=40 \
  -Dbrxdis.cb.waitDurationInOpenStateSeconds=60

Verifying configuration

GET http://localhost:8080/cms/ws/discovery/picker/search?q=shirt

You should receive a JSON array of products. If you receive a 404 or an empty error response, review your configuration.

Symptom	Likely cause
ConfigurationException: Discovery accountId is required	Credentials not set; check environment variables
Product grid empty, no error shown	`accountId` or `domainKey` do not match your Discovery account
Custom attribute missing from attributes	Not included in `defaultFieldList`

For additional troubleshooting steps and error scenarios, see Troubleshooting.