BSI CDP extension

Customer data Unbundled: Extension Version 3.0.0

The BSI CDP extension enables Magnolia Authors to create multichannel personalized experiences based on insights from BSI without ever leaving the Magnolia UI. This module leverages the personlization feature in Magnolia.

You should be familiar with Personalization before continuing.

Security considerations

You should use the BSI CDP extension to encapsulate rest-based calls of a frontend to third party systems through Magnolia. This way passwords and other critical security information are hidden the browser.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.cdp</groupId>
  <artifactId>magnolia-cdp-bsi</artifactId>
  <version>3.0.0</version>
</dependency>

Configuration

The configuration consists of two parts:

A Rest Endpoint that can be called from the desired frontend
A Rest Client that controls the call to the third party system.
A Trait Definition that defines the user traits used for personalization.

Rest Endpoint

<light-module-name>/restEndpoints/<restEndpointName>

class: info.magnolia.cdp.common.rest.service.ConfiguredRestProxyEndpointDefinition
implementationClass: info.magnolia.cdp.common.rest.service.RestProxyEndpoint
restClientName: <restClientName>
restCallName: <restClientMethodName>

Rest Client

<light-module-name>/restClients/<restClientName>

baseUrl: <URL to the external Service>
securitySchemes:
  b1:
    $type: basic
    username: <username to the third party system>
    password: ''
restCalls:
  <restClientMethodName>:
    method: get
    path: /<path of the method>/${idProperty}
    securityScheme: b1

Frontend call example

await fetch('/.rest/<restClientName>', {
    method: 'POST', (1)
    headers: { 'Content-Type': 'application/json' },
    body: `{"idProperty":"${idProperty}"}`
});

1	The Rest Client can be both `GET` and `POST`, but the Rest Endpoint must be called with `POST`.

Trait Definition

To enable personalization based on user data from BSI, define traits in your Magnolia light module’s personalization configuration. Traits map user data (e.g., from BSI or request parameters) to personalization rules.

The following example defines a trait for the last viewed product category. It captures the category (e.g., via a request parameter like ?category=Kitchenware) and maps it to predefined categories for use in personalization.

Place this trait definition in your light module under the traits directory. For example, if your light module is named my-cdp-module, create the file at:

<your-magnolia-project>/light-modules/my-cdp-module/traits/bsiLastViewedCategory.yaml

name: bsiLastViewedCategory (1)
$type: requestParameterTrait (2)
ruleField:
  $type: comboBoxField
  name: value
  datasource: &datasource
    $type: optionListDatasource
    options:
      - name: Bathroom
        value: 30e3595e-0973-4873-960b-83555f8de813 (3)
      - name: Garden
        value: dba8b1e4-69bb-4e6b-a0ce-764308cb3ca0
      - name: Kitchenware
        value: 4e94006f-a35c-43de-b7f5-4977110ce7b8
      - name: Living
        value: 4d7a73d2-f3bd-475b-9dbe-74888a265d69
valueField:
  $type: comboBoxField
  datasource: *datasource
traitStorageClass: info.magnolia.personalization.trait.storage.StorageAwareTraitCollector$RequestScopedTraitStorage (4)

1	The `name` (`bsiLastViewedCategory`) identifies the trait in personalization rules.
2	The `$type: requestParameterTrait` indicates the trait is populated from a request parameter (e.g., `?category=Kitchenware`).
3	The UUIDs must match content nodes in Magnolia’s JCR repository (e.g., product categories). Verify UUIDs using the JCR Browser or Content Editor app.
4	The `traitStorageClass` stores the trait for the duration of the user’s request, ideal for temporary data like recent browsing activity.

To verify, restart Magnolia and check the Personalization app in AdminCentral; the bsiLastViewedCategory trait should appear in the trait selection dropdown.

Usage

Here, we provide some basic examples of using the CDP integration framework.

Create a content variant

The variant can be configured completely differently in terms of copy or images.

On your desired page, click the Component you want to edit.
Click Edit component and change something to create a component variant.

Example

In the example here, we are choosing a different image for the particular component.

For more on components in Magnolia, see Editing pages.

Choose the variant audience

Select the variant you just created, and click Choose audience.
Define your audience and select the traits. Here, you’ll see traits that are taken directly from BSI. Cool, huh?

BSI CDP extension

Installing with Maven

Configuration

Rest Endpoint

Rest Client

Frontend call example

Trait Definition

Usage

Create a content variant

Choose the variant audience

Location

Main doc sections