How to Use the Bloomreach Content SaaS Developer Application
Published: 2023-06-20 16:27:51

## Table of Contents
* [Overview](#overview)
* [Featured Functionality](#featured-functionality)
* [Getting Started](#getting-started)
  * [Create an API Token for Each CMS Instance](#create-an-api-token-for-each-cms-instance)
  * [Configure the Developer Extension Application](#configure-the-developer-extension-application)
* [Sample Actions](#sample-actions)
  * [Copying Content Types](#copying-content-types)
  * [Copying Components](#copying-components)

## Overview
Every customer that uses our Bloomreach Content SaaS product has two CMS instances provisioned.
* A Sandbox CMS instance, which is typically used for Development and QA environments
* A Production CMS instance, which is typically use for Acceptance/Staging and Production environments

In order to facilitate the transfer of content and/or configuration from one CMS instance to another, we've created a standalone application that utilizes the Content SaaS [Management APIs](https://documentation.bloomreach.com/content/reference/management-apis).

The application can be accessed at [https://bloomreach-content-ui-extension.netlify.app/](https://bloomreach-content-ui-extension.netlify.app/) or it can be cloned/forked from the public GitHub repository: https://github.com/adampengh/bloomreach-content-saas-ui-extensions

## Featured Functionality
* Copy Content Types between instances
* Copy Pages between channels in a single instance
* Edit Channel configuration/properties
* Copy Channel configuration between instances or between channels in a single instance
  * Copy/Delete Components
  * Copy/Delete Layouts
  * Copy/Delete Routes
  * Copy/Delete Menus
* Batch Export Content
* Batch Import Content

## Getting Started
### Create an API Token for Each CMS Instance
1. Log in to Bloomreach Content using an account with Site Developer privileges.
2. Navigate to Setup > brXM API token management
3. Click on the + API token button in the top right
4. Fill in a Token name, choose an Expiration date, check the Read and/or Write checkboxes for the APIs you want to use the token with, and click on Create. We recommend setting the expiration date as soon as possible, to automatically limit the risk of accidental credential exposure.
5. Copy the token to the clipboard or write it down. This is the only time it will be displayed. We recommend simply creating new tokens at need, rather than attempting to store the token value in a password manager or other long-term storage.

### Configure the Developer Extension Application
When first accessing the application, you will be redirected to the Configuration page. Here you will see configuration settings for a Source Environment and Target Environment.
* The Source Environment is the CMS instance you want to copy content/configuration from or make configuration changes in.
* The Target Environment is the CMS instance where the content/configuration will be copied to.
![Application Configuration](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0kjsvbe0pe56ks6a57l9.png)

In the Source Environment:
1. Enter the namespace of the environment. This is the subdomain portion of the URL immediately before bloomreach.io.
2. Enter the API Token generated [earlier](#create-an-api-token-for-each-cms-instance).
3. Click Save.
4. From the Projects dropdown, either select an existing Developer Project or click the "+" button to create a new Developer Project. 
  * To copy Content Types between instances, there needs to be an active Developer Project that includes Content Type Changes in the Target Environment.

In order to copy content/configuration to the Target Environment, follow the above steps for the Target Environment configuration section.

After the configuration has been set, the configuration is saved in the browser's `localStorage`.

## Sample Actions
### Copying Content Types
1. Click on Content Types from the sidebar navigation
2. Select the Content Types to copy in one of two ways:
  - Click on the copy button next to a single Content Type or
  - Select the checkbox of multiple Content Types, then click the Copy button on the top right of the page
3. In the confirmation modal, review the changes, then click the Copy button

{% embed https://www.youtube.com/embed/mG5WgIa93-w %}

### Copying Components
1. Add the channel to the currently selected Source Environment project. If the channel has already been added, skip to Step 6
2. Click on Projects from the sidebar navigation
3. Click on the Project from the list of Source Projects
4. Click the "Add Channels" button
5. In the modal, select the channels to add and click "Add Channels"
6. Click on Channels from the sidebar navigation
7. Click on the channel from the list of channels in the currently selected Source Environment project
8. Click on the Components tab
9. Select the Components to copy in one of two ways:
  - Click on the copy button next to a single Component or
  - Select the checkbox of multiple Components, then click the Copy button on the top right of the page
{% embed https://www.youtube.com/embed/BxJX4BPVbAk %}