Get started with brX Content integration
Next: Development Environment
The intent of this tutorial is to give you, as developer, an introduction to brX and help you get up and running. It focuses on a technical developer audience, and on the Content part of brX.
High Level Overview
Let’s dive right into it. You have been granted access to a dedicated brX account (login URL, access credentials and more). Upon configuring your password, you can log into the brX UI at the login URL.
Sample SPA + Channel
If you navigate to the Experience manager app, you will find a "BrX SaaS" channel pre-populated there. That channel powers a reference SPA, maintained and hosted by Bloomreach. The reference SPA makes use of your account’s pre-populated configuration, through the Delivery API, such that you can manage content and configuration of that channel through the brX UI. Try it out!
We expect the first thing a new brX developer might want to do is to get started with their own frontend application. To do so, retrieve a copy (git clone) of the reference SPA, so you can run it locally and make and test your changes. Check the reference SPA’s README for instructions on how to run it locally. By using a clone of the reference SPA, you don’t have to worry much about the brX configuration just yet, so you can get acquainted with the SPA SDK used by the SPA, as well as the Delivery API output.
For the local SPA to work, you need to tell it how to access the back-end (Delivery API), and in order to be able to manage content and configuration of your SPA, you need to tell brX how to load your local SPA into the Experience Manager. The former is done through the SPA’s .env file. The Delivery API's Pages endpoint base URL will look like <your-brx-host>/delivery/site/v1/channels/brxsaas/pages. The latter is done by creating a new Development project in the Projects app, associating the desired channel(s) with it and setting a project- or user-specific “SPA URL” for the Experience manager to load.
When you’re familiar with how the SPA interacts with the brX back-end, you’ll reach a point where you want to make more significant changes to the back-end configuration than what you can do in the Experience manager only. You’ll want to start making developer changes. Developer changes can include updates to channel configuration, such as adding a new component to the catalog via the Site Management API or simply rearranging components in a standard page template. You can also change content models or edit the content itself, and test this alongside your configuraton changes before updating the live production site.
Channel configuration is accessed and updated through the Site Management API. You can access it at <your-brx-host>/management/site/v1/channels, and you need to obtain and use an authorization token. You can explore the Site Management API through this URL: <your-brx-host>/management/site/v1/api-docs. Your changes to the channel configuration will be associated with the developer project created when setting up your local SPA, and you must select that project when previewing your changes in the Experience Manager.
Content modelling, i.e. defining the document types you need in your Content module, is exposed through the Document Type Editor. You can access it in the brX UI. Navigate to the Content app and then select Document Types from the Documents drop-down.
The Document Type Editor links changes to document types with an in-progress developer project. At this time, only one developer project at a time may include document type changes.
Reviewing and Publishing your Changes
When your changes to the frontend and the back-end configuration have completed, you want to integrate them into your live workspace in a controlled way. Use the Projects workflow to do so: first, deploy your new version of the frontend to a publicly accessible URL and update the channel’s frontend URL to point to the new version of the SPA. Ensure that the SPA works as expected. Next, put the project into review state and have it reviewed and approved. Finally, merge your project into the live workspace. You should now be able to access the new frontend outside of the Experience manager, while it successfully connects to your updated brX back-end.
Next: Development Environment