brX GraphQL Service FAQ

Is the brX GraphQL Service required to run Bloomreach Commerce Accelerator?

In the Bloomreach Commerce Accelerator v14.x the brX GraphQL Service is an optional feature. Without it you can still run the Bloomreach Commerce Accelerator which is basically comprised of HstComponents, templates, webfiles, configurations, and content.

However, if you want to implement a new GraphQL client application such as an GraphQL based SPA, or if you want to enable the Open UI based Pickers interacting with the brX GraphQL Service, then you will need to install and configure the brX GraphQL Service additionally to your environment.

What kind of Commerce Connectors are supported?

The brX GraphQL Service reads the 'connector' request header from the clients to invoke the specific Commerce Connector implementation modules by the specified Connector ID. See Configure the brX GraphQL Service for all available Connector IDs.

How does the authentication/authorization work?

Every request to the brX GraphQL Service should provide an access token, and the brX GraphQL Service handles and validates the authentication and authorization through its internal Access Manager components. See Access Management for further detail.

How are date/time values handled in the brX GraphQL Service?

In the GraphQL schema of the brX GraphQL Service, every date/time data field is defined as an ISO 8601 formatted string type, supporting formats like the following:

Format (using Java SimpleDateFomat letters)	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 GraphQL Schema is defined like the following:

  "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..."
  }

The creationDate field value will be an ISO 8601 formatted string in the response, so applications are supposed to parse the date/time value properly whenever necessary.

When an application wants to mutate an entity through the brX GraphQL Service, it has to format any date/time field value to a string properly. For example, the mutation to update the customer detail requires an argument of the following 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
  }

The dateOfBirth field value is expected to be an ISO 8601 formatted string, so applications are excpeted to format the date input value properly (for example, "1999-05-25").

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

The API of Bloomreach Discovery supports the faceting and filtering parameter, fp. See the Faceting and filtering page for detail.

In order to pass the faceting and filtering parameter when making a GraphQL query request, you need to specify QueryHintInput.facetFieldFilters input argument.

For example, the following input will make a brSM API call with a URL like ...&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 can I append or override request parameters for brSM API calls?

By default, GraphQL queries on the brX GraphQL Service against Bloomreach Discovery generates the backend API call URLs automatically to fulfill the requests. However, it also supports appending or overrriding any request parameters through QueryHintInput.params GraphQL query input argument.

For example, if you want to add the segement parameter and override the ref_url parameter when invoking brSM API URLs, then you can specify the QueryHintInput.params like the following example:

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

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

By default, GraphQL queries on the brX GraphQL Service against Bloomreach Discovery extracts the fields defined in the GraphQL Schema automatically.

However, it also supports the optional configurations to include any extra custom fields by the BRSM_CUSTOM_ATTR_FIELDS and BRSM_CUSTOM_VARIANT_ATTR_FIELDS environment variables. See the Bloomreach Discovery Connector Configuration page for detail.

Furthermore, you can override the optional configurations by specifying QueryHintInput.customAttrFields and QueryHintInput.customVariantAttrFields when making GraphQL queries. For example, the following GraphQL query will make the response include the custom fields in the product item level, "brand" and "score", and the custom fields in the product variant level, "color_code":

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

How to sort products search result ?

The brX GraphQL Service supports the sort/order by fields functionality while triggering operations like products search. Queries like findItemsByKeyword accept a sortFields parameter where to specify a list of product fields - separated by comma - used for sorting. As an example, the sortField param may accept values like "field1,field2,-field3", meaning order by field1 and field2 ascending and field3 descending. Below you can find a very basic example, where the result is supposed to be sorted by purchasePrice (ascending order).

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

Please note that the sorting behaviour may differ based on the commerce backend connector implementation. As an example, sorting by multiple fields may not be supported in some of the external commerce backend. In that case the commerce backend connector may use only the first entry of the sortFields param.

Please also note that the sortFields specified in the GraphQL query are "mapped" internally to the commerce backend fields. As an example, in case of the Bloomreach Discovery connector the purchasePrice is mapped automatically to the sale_price field. In case a field is not mapped internally, the specified field name is used.