Bootstrapping Bloomreach Content

Alokai ships with a set of 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 channels, 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,
• Bloomreach Content auth token with management permissions,
• @vsf-enterprise/cms-cli version 2.0.0 or higher.

Generating 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.

Importing the default 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

Installing Bloomreach Content Manager

The schemas you have just imported into your project use types and interfaces provided by our @vsf-enterprise/bloomreach-content-manager package. Install it by running the following command from the root of your project:

yarn add -W @vsf-enterprise/bloomreach-content-manager

Bootstrapping

To upload the default Alokai schemas into your Bloomreach Content environment, navigate to the /schemas directory

cd 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': {
      // ...
    }
  },
};

export default {
  // ...
  channelsOperations: {
    'en': {
      // ...
    },
    'de': {
      // ...
    }
  },
};

After a successful bootstrapping process, a series of green check marks in the terminal will indicate the completion. At this point, your journey with the Manager can conclude and you can proceed to create your first components and pages.

If your sole objective was to perform the initial environment bootstrap, you may choose to delete the /schemas directory from your project entirely and no longer utilize the tool. However, you can also choose to delve deeper into its capabilities.

General usage

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

First and foremost, the Manager provides functionality to create and update your Bloomreach Content artifacts. However, it also offers the ability to 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;

Subsequently, 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'.