brX GraphQL Service FAQ

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

Is the brX GraphQL Service required for Bloomreach Commerce Accelerator?

The brX GraphQL Service is optional in Bloomreach Commerce Accelerator v14.x. You can run the Commerce Accelerator without the brX GraphQL Service. The accelerator includes HstComponents, templates, webfiles, configurations, and content.

Install and configure the brX GraphQL Service if you plan to:

• Build a new GraphQL client application, such as a GraphQL-based single-page application (SPA)
• Enable Open UI-based Pickers that interact with the brX GraphQL Service

Which Commerce Connectors does the brX GraphQL Service support?

The brX GraphQL Service uses the connector request header to determine which Commerce Connector implementation module to invoke, based on the specified Connector ID. For a list of available Connector IDs, see Configure the brX GraphQL Service.

How does authentication and authorization work?

Each request to the brX GraphQL Service must include an access token. The service validates authentication and authorization using its internal Access Manager components. For more information, see Access Management.

How does the brX GraphQL Service handle date and time values?

All date and time fields in the brX GraphQL Service schema use ISO 8601 formatted strings. Supported formats include:

Format (Java SimpleDateFormat pattern)	Examples
yyyy-MM-dd	"2021-12-31"
yyyy-MM-dd'T'HH:mm:ss	"2021-12-31T23:59:59"
yyyy-MM-dd'T'HH:mm:ssX	"2021-12-31T23:59:59Z", "2021-12-31T23:59:59+00:00", "2021-12-31T23:59:59-05:00"
yyyy-MM-dd'T'HH:mm:ss.SSS	"2021-12-31T23:59:59.815"
yyyy-MM-dd'T'HH:mm:ss.SSSX	"2021-12-31T23:59:59.815Z", "2021-12-31T23:59:59.815+00:00", "2021-12-31T23:59:59.815-05:00"

For example, the Order type in the schema is defined as follows:

  "Purchase order abstraction"
  type Order {
    "The identifier of this purchase order"
    id: String!
    "The creation date of this order in ISO 8601 date format"
    creationDate: String!
    "...SNIP..."
  }
copy

The creationDate field in the response will be an ISO 8601 formatted string. Applications must parse these date and time values as needed.

When mutating entities, format any date and time fields as ISO 8601 strings. For example, the mutation to update customer details uses the following input type:

  "The customer detail input data used when updating the customer's detail information"
  input CustomerDetailInput {
    "The E-Mail address of the customer"
    email: String!
    "...SNIP..."
    "The customer's date of birth in ISO 8601 date format"
    dateOfBirth: String
  }
copy

Set the dateOfBirth field to an ISO 8601 formatted string, such as "1999-05-25".

How do I pass faceting and filtering parameters to brSM API calls?

The Bloomreach Discovery API supports faceting and filtering using the fp parameter. For details, see the Faceting and filtering documentation.

To pass faceting and filtering parameters in a GraphQL query, use the QueryHintInput.facetFieldFilters argument. For example, the following input results in a brSM API call with URL parameters such as &fq=color: "red" OR "purple"&fq=size: "10":

query {
  findItemsByKeyword(text: "", limit: 200,
    queryHint:{
      facetFieldFilters: [
        { id: "color", values: ["red","purple"] },
        { id: "size", values: ["10"] }
      ]
    }
  ) {
    //...
    items {
      //...
    }
  }
}

How do I append or override request parameters for brSM API calls?

By default, the brX GraphQL Service generates backend API URLs automatically for Bloomreach Discovery. You can append or override request parameters using the QueryHintInput.params argument in your GraphQL query.

For example, to add a segment parameter and override the ref_url parameter:

query {
  findItemsByKeyword(text: "", limit: 200,
    queryHint:{
      params: [
        { name: "segment", values: ["customer_tier:Premium"] },
        { name: "ref_url", values: ["http://www.example.com"] }
      ]
    }
  ) {
    //...
    items {
      //...
    }
  }
}

How do I include extra custom fields from the brSM API response?

By default, the brX GraphQL Service extracts only the fields defined in the GraphQL Schema.

To include additional custom fields, configure the BRSM_CUSTOM_ATTR_FIELDS and BRSM_CUSTOM_VARIANT_ATTR_FIELDS environment variables. For details, see Bloomreach Discovery Connector Configuration.

You can also override these settings per request using the QueryHintInput.customAttrFields and QueryHintInput.customVariantAttrFields arguments. For example, the following query includes the custom fields "brand" and "score" at the product item level, and "color_code" at the variant level:

query {
  findItemsByKeyword(text: "", limit: 200,
    queryHint: {
      customAttrFields: ["brand","score"],
      customVariantAttrFields: ["color_code"],
    }
  ) {
    //...
    items {
      //...
    }
  }
}

How do I sort product search results?

The brX GraphQL Service supports sorting and ordering fields for product search operations. Use the sortFields parameter in queries such as findItemsByKeyword to specify a comma-separated list of product fields for sorting. For example, sortFields: "field1,field2,-field3" sorts by field1 and field2 ascending, and field3 descending.

The following example sorts results by purchasePrice in ascending order:

query {
  findItemsByKeyword(text: "", limit: 200, sortFields: "purchasePrice") {
    //...
    items {
      //...
    }
  }
} 

Sorting behavior may vary depending on the commerce backend connector. Some connectors may not support sorting by multiple fields and will use only the first field in sortFields.

The sortFields values in the GraphQL query are mapped internally to commerce backend fields. For example, in the Bloomreach Discovery connector, purchasePrice maps to the sale_price field. If a field is not mapped, the specified field name is used as-is.