Bloomreach Content

Alokai with Bloomreach Content is a powerful software combination that empowers businesses to create engaging and personalized digital experiences for their customers. This guide presents how to add the Bloomreach Content module to your Storefront.

Bootstrapping Bloomreach Content with Alokai Storefront

To use the Bloomreach Content integration in your Storefront, perform the following steps:

npx @vsf-enterprise/storefront-cli add-module cms-bloomreach-content

- BLOOMREACH_CONTENT_ENVIRONMENT=<alokai-bloomreach-content-environment>
+ BLOOMREACH_CONTENT_ENVIRONMENT=<your-bloomreach-content-environment>

Bootstrapping Bloomreach Content

Before you start using Bloomreach Content, you need to set up your Bloomreach Content environment and import the integration schemas for content types, folders, components, menus and layouts. They are aligned with our out-of-the-box frontend components. Here you will learn how to import them into your Bloomreach Content environment using our Bloomreach Content Manager tool.

Overview

Bloomreach Content comes equipped with powerful Management APIs, which provide developers the flexibility to interact with the CMS using a fully programmatic approach. Instead of navigating through the UI, developers can construct schemas for their data models and efficiently upload them to their Bloomreach Content environment using tools like Postman.

While this improvement alone is significant, certain tasks like creating projects, adding channel branches, manually sending individual requests, and then merging projects still demand attention, and the correct sequence of actions is crucial.

Alokai takes this a step further by simplifying the entire process. Our Bloomreach Content Manager serves as an additional abstraction layer built on top of the Management APIs. It enables developers to concentrate solely on writing Typescript schemas for their artifacts without worrying about other tasks.

With a single command, developers can instruct the manager to synchronize the schemas on their behalf. This automation not only saves valuable time but also ensures a hassle-free experience, allowing developers to savor their moments while the tool takes care of the rest.

Prerequisites

• Bloomreach Content environment with two channels: en and de,
• Bloomreach Content auth token with management permissions,

Generate auth token

You are going to need a dedicated auth token. Go to your Bloomreach Content dashboard and follow the instructions in this guide to create a new token with the following permissions:

Save the auth token for later. We will use it in the next chapters of this tutorial.

Get integration schemas

To copy the default schemas provided by Alokai into your Storefront project, execute the following command from its root directory:

npx @vsf-enterprise/cms-cli bloomreach-content:schemas

If the command execution is successful, a new /schemas directory will appear:

  └── schemas
      ├── component-groups
      │   └── ...
      ├── components
      │   └── ...
      ├── content-types
      │   └── ...
      ├── folders
      │   └── ...
      ├── layouts
      │   └── ...
      ├── menus
      │   └── ...
      ├── routes
      │   └── ...
      └── index.ts

Import integration schemas

Default schemas provided by Alokai, are available in the apps/storefront-middleware/sf-modules/cms-bloomreach-content/schemas directory. To upload them into your Bloomreach Content environment, navigate to the schemas directory

cd apps/storefront-middleware/sf-modules/cms-bloomreach-content/schemas

and use the following command of the CMS CLI:

npx @vsf-enterprise/cms-cli bloomreach-content:manager \
  -h <brx_host> \
  -t <brx_auth_token> \
  -p <schemas_dir_path> \

Remember to replace the placeholders in the above command with the actual values:

Under the hood, the command will read the schema present in the schemas/index.ts file and pass it on to Bloomreach Content Manager. The Manager will then execute a sequence of requests to the Bloomreach Management API, populating your environment with data from the schemas.

export default {
  // ...
  channelsOperations: {
-   'en': {
+   'my-channel': {
      // ...
    }
  },
};

A series of green check marks in the terminal will indicate a successful bootstrapping. At this point, you are done with the Manager and you can proceed to create your first components and pages.

Bloomreach Content Manager

The primary objective of the Manager is to grant you complete independence during the initial phase of working with Bloomreach Content and Alokai. It allows you to populate your environment with default schemas, after which you can choose to discontinue its usage.

Alternatively, you have the option to leverage its capabilities throughout your development journey with Alokai, enabling you to create new schemas, update existing ones, and remove any that are no longer required. This guide explains the process in more detail.

Creating Artifacts

Suppose you wish to create a new Example component in your frontend and establish a corresponding structure in Bloomreach Content. While you have the option to follow the manual approach using the UI, you can also opt to write schemas and let the manager handle the uploading process for you.

import { ContentType } from "@vsf-enterprise/bloomreach-content-manager";

export const exampleContentType: ContentType = {
  name: 'vuestorefront:example',
  type: 'Document',
  presentation: {
    layout: 'one-column',
    displayName: 'Example'
  },
  fields: [
    {
      name: 'component',
      type: 'String',
      defaultValue: ['Example'],
      presentation: {
        displayType: 'Simple',
        caption: 'Component',
      }
    },
    {
      name: 'title',
      type: 'String',
      presentation: {
        displayType: 'Simple',
        caption: 'Title',
      },
      required: true
    },
    {
      name: 'subtitle',
      type: 'String',
      presentation: {
        displayType: 'Simple',
        caption: 'Subtitle',
      },
      required: true
    },
    {
      name: 'button',
      type: 'FieldGroup',
      fieldGroupType: 'vuestorefront:button',
      presentation: {
        caption: 'Button',
      }
    },
    {
      name: 'styles',
      type: 'FieldGroup',
      multiple: true,
      fieldGroupType: 'vuestorefront:styles',
      presentation: {
        caption: 'Style',
        hint: 'Adding properties such as margin and padding for various screen resolutions'
      }
    }
  ]
}

import { Folder } from "@vsf-enterprise/bloomreach-content-manager";

export const exampleFolder: Folder = {
  path: '/content/documents/en/example',
  type: 'folder',
  allowedDocumentTypes: ['vuestorefront:example']
};

import { ComponentDefinition } from "@vsf-enterprise/bloomreach-content-manager";

export const exampleComponent: ComponentDefinition = {
  id: 'vuestorefront/example',
  extends: 'base/component',
  label: 'Vuestorefront Example',
  icon: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTc2IiBoZWlnaHQ9IjE3NiIgdmlld0JveD0iMCAwIDE3NiAxNzYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxwYXRoIGQ9Ik03OS4yMTY1IDUuOTI0MDFDNzcuNjQ2MiA2LjkwMDUzIDc2LjEwNTIgOC40NDE0NyA3My4wMjM0IDExLjUyMzRDNjkuOTQxOCAxNC42MDQ4IDY4LjQwMDQgMTYuMTQ2MyA2Ny40MjQgMTcuNzE2NUM2NC4xOTIgMjIuOTE0IDY0LjE5MiAyOS40OTYgNjcuNDI0IDM0LjY5MzVDNjguNDAwMyAzNi4yNjM1IDY5Ljk0MDkgMzcuODA0MSA3My4wMjE1IDQwLjg4NDhMNzMuMDIzIDQwLjg4NjRDNzYuMTA0OSA0My45NjgyIDc3LjY0NjIgNDUuNTA5NSA3OS4yMTY1IDQ2LjQ4NkM4NC40MTQgNDkuNzE4IDkwLjk5NiA0OS43MTggOTYuMTkzNSA0Ni40ODZDOTcuNzYzOCA0NS41MDk1IDk5LjMwNDggNDMuOTY4NSAxMDIuMzg3IDQwLjg4NjdDMTA1LjQ2OSAzNy44MDQ4IDEwNy4wMDkgMzYuMjYzOCAxMDcuOTg2IDM0LjY5MzVDMTExLjIxOCAyOS40OTYgMTExLjIxOCAyMi45MTQgMTA3Ljk4NiAxNy43MTY1QzEwNy4wMDkgMTYuMTQ2MiAxMDUuNDY5IDE0LjYwNTMgMTAyLjM4NyAxMS41MjM0Qzk5LjMwNDggOC40NDE1NCA5Ny43NjM4IDYuOTAwNTMgOTYuMTkzNSA1LjkyNDAxQzkwLjk5NiAyLjY5MjAyIDg0LjQxNCAyLjY5MTk4IDc5LjIxNjUgNS45MjQwMVoiIGZpbGw9IiMwMkM2NTIiLz4KPHBhdGggZD0iTTk5LjQ5MjggMTAyLjM0MUwxMzUuMzUzIDY2LjQ4MDRDMTM2LjgzOSA2NC45OTQ2IDEzOC42MDMgNjMuODE2MSAxNDAuNTQ0IDYzLjAxMkMxNDIuNDg1IDYyLjIwNzkgMTQ0LjU2NiA2MS43OTQxIDE0Ni42NjcgNjEuNzk0MUMxNDguNzY4IDYxLjc5NDEgMTUwLjg0OCA2Mi4yMDc5IDE1Mi43OSA2My4wMTJDMTU0LjczMSA2My44MTYxIDE1Ni40OTUgNjQuOTk0NiAxNTcuOTggNjYuNDgwM0wxNzYgODQuNDk5OEMxNzUuODkxIDg0LjYwOCA4OCAxNzIuNSA4OCAxNzIuNUwwIDg0LjQ5OTlDMC4yMzg3NDUgODQuMjYxOCA5Ljk4MTYgNzQuNTE4OCAxOC4yMDkyIDY2LjI5MUMxOS42OTQxIDY0LjgwNTkgMjEuNDU3MSA2My42Mjc5IDIzLjM5NzMgNjIuODI0MkMyNS4zMzc2IDYyLjAyMDUgMjcuNDE3MiA2MS42MDcgMjkuNTE3MyA2MS42MDcxQzMxLjYxNzQgNjEuNjA3MyAzMy42OTY5IDYyLjAyMTIgMzUuNjM3MSA2Mi44MjUyQzM3LjU3NzIgNjMuNjI5MiAzOS4zMzk5IDY0LjgwNzUgNDAuODI0NiA2Ni4yOTI4TDc2Ljg3NDMgMTAyLjM0MkM3OC4zNTk1IDEwMy44MjcgODAuMTIyNyAxMDUuMDA1IDgyLjA2MzIgMTA1LjgwOUM4NC4wMDM3IDEwNi42MTMgODYuMDgzNSAxMDcuMDI2IDg4LjE4MzggMTA3LjAyNkM5MC4yODQyIDEwNy4wMjYgOTIuMzYzOSAxMDYuNjEyIDk0LjMwNDMgMTA1LjgwOEM5Ni4yNDQ3IDEwNS4wMDQgOTguMDA3NyAxMDMuODI2IDk5LjQ5MjggMTAyLjM0MVoiIGZpbGw9IiMwMkM2NTIiLz4KPC9zdmc+Cg==',
  ctype: 'Example',
  parameters: [
    {
      name: 'document',
      displayName: 'Document',
      valueType: "string",
      required: true,
      config: {
        pickerConfiguration: 'cms-pickers/documents-only',
        type: 'contentpath',
        pickerInitialPath: "example",
        pickerSelectableNodeTypes: [
          'vuestorefront:example'
        ]
      }
    },
    {
      name: 'document-template-query',
      displayName: 'Document template query',
      valueType: "string",
      defaultValue: "new-vuestorefront-example-document",
      hidden: true
    } as any,
    {
      name: 'root',
      displayName: 'Root document folder',
      valueType: "string",
      defaultValue: 'example',
      hidden: true
    },
    {
      name: 'parameter',
      displayName: 'Document parameter',
      valueType: "string",
      defaultValue: "document",
      hidden: true
    }
  ]
};

npx @vsf-enterprise/cms-cli bloomreach-content:manager \
  -h <brx_host> \
  -t <brx_auth_token> \
  -p <schemas_dir_path>

import type { Operations } from '@vsf-enterprise/bloomreach-content-manager';
import { accordionComponent } from './components';
import { accordionContentType } from './content-types/documents';
import { accordionFolder } from './folders';

export default {
  contentType: {
    createOrUpdate: [accordionContentType],
  },
  folder: {
    createOrUpdate: [accordionFolder],
  },
  channelsOperations: {
    en: {
      component: {
        createOrUpdate: [accordionComponent],
      },
    },
  },
} as Operations;

Deleting artifacts

The Manager not only allows you to create and update your Bloomreach Content artifacts, but it also lets you delete them. The default schema object includes separate fields for accepting schemas to facilitate artifact deletion.

For instance, suppose you intend to delete the vuestorefront:example component. You can achieve this with the following schema:

import type { Operations } from '@vsf-enterprise/bloomreach-content-manager';

export default {
  channelsOperations: {
    'en': {
      component: {
        remove: [
          { groupName: 'vuestorefront', componentName: 'example' },
        ]
      },
    }
  },
} as Operation;

Similarly, you can remove the example folder:

import type { Operations } from '@vsf-enterprise/bloomreach-content-manager';

export default {
  folder: {
    remove: [
      { folderPath: 'content/documents/en/example' },
    ],
  },
} as Operations;

and the vuestorefront:example content type:

import type { Operations } from '@vsf-enterprise/bloomreach-content-manager';

export default {
  contentType: {
    remove: [
      { contentTypeName: 'vuestorefront:example' },
    ],
  },
} as Operations;

The removal operations must be executed in a specific order, aligned with the interdependencies between these artifacts. After successfully deleting the artifacts, it is essential to manually delete their corresponding create/update schemas located in the /schemas directory. This manual cleanup ensures that the schemas remain in sync with the current state of the system after the removal process.

Renaming artifacts

In addition to creating, updating, and removing artifacts, certain artifacts also support a rename operation. For instance, you can rename a content type or update the path of a folder using Manager's support for such actions. To rename the vuestorefront:example content type, you would run the Manager with the following object:

import type { Operations } from '@vsf-enterprise/bloomreach-content-manager';

export default {
  contentType: {
    rename: [
      {
        contentTypeName: 'vuestorefront:example',
        newName: 'vuestorefront:newexample',
        displayName: 'New Example'
      }
    ]
  },
} as Operations;

To rename the corresponding folder:

import type { Operations } from '@vsf-enterprise/bloomreach-content-manager';

export default {
  folder: {
    moveOrRename: [
      {
        srcPath: 'content/documents/en/example',
        dstPath: 'content/documents/en/newexample'
      }
    ]
  },
} as Operations;

Rename/move requests operate independently from the create/update schemas discussed in the Creating artifacts section. As a result, after sending a rename/move request, it is essential to manually update the create/update schema in the /schemas directory for the corresponding artifact. This ensures that the schema aligns with the changes made through the rename/move request.

Managing the root index file

Using the Manager offers the advantage of version-controlling your Bloomreach Content schemas alongside your Vue or React components. However, you will also have the root schemas/index.ts file in the repository, which is likely to undergo frequent updates while working with the Manager. Most of these changes may not be suitable for committing to the remote repository. Therefore, it is advisable to exclude the schemas/index.ts script from being version-controlled.

One viable solution to address this situation is to commit only the initial "empty shell" version of the schemas/index.ts file to your remote repository:

import type { Operations } from '@vsf-enterprise/bloomreach-content-manager';

export default {
  resourceBundle: {
    createOrUpdate: [],
    remove: []
  },
  contentType: {
    createOrUpdate: [],
    rename: [],
    remove: []
  },
  folder: {
    createOrUpdate: [],
    remove: [],
    moveOrRename: []
  },
  channelsOperations: {
    'en': {
      componentGroup: {
        createOrUpdate: [],
        remove: []
      },
      component: {
        createOrUpdate: [],
        remove: []
      },
      layout: {
        createOrUpdate: [],
        remove: []
      },
      menu: {
        createOrUpdate: [],
        remove: []
      },
      route: {
        createOrUpdate: [],
        remove: []
      }
    }
  }
} as Operations;

Then, to exclude it from being version-controlled, you can utilize the git update-index command.

git update-index --assume-unchanged ./schemas/index.ts

By using the --assume-unchanged option, you ensure that any future changes to the script remain local and do not impact the repository's version history. This approach streamlines your version control process, maintaining a cleaner and more efficient workflow for your project. It also grants you the freedom to utilize the schemas/index.ts file fully for creating, updating, and removing artifacts with your schemas.

If you ever need to version-control the file again, you can easily revert the exclusion by running the command:

git update-index --no-assume-unchanged ./schemas/index.ts'.