Introduction
The Content Batch Import API enables developers to import large amounts of content into a Bloomreach Content project.
How it works
The batch import works by uploading a JSON lines file, also known as an NDJSON or new line delimited JSON file. Each file line contains a JSON object representing a single document or page in the same format used by the Content Management API. These objects make references to the content types and page layouts previously defined in the target channel using the Content Type Management API and Site Management API, which define the expected structure for the data.
The response from the initial upload POST request is a job identifier that the caller can use to poll for the operation status. When the operation is complete, the caller can obtain a report of the operation containing all successful and failed items in the batch.
A successfully imported document or page will be added to a development project in the Projects app, where it can be reviewed before publication. Content items can be edited or deleted individually, or the entire project can be deleted to remove all imported data before importing a revised batch.
In case of failed items, the API cleans up as much as possible (for example, delete or revert unfinished/corrupted documents). It can also easily be cleaned up via the Projects app in the Bloomreach Content UI.
We recommend importing content in batches up to several hundred documents or pages at a time to facilitate the review and editing process for content authors. Dividing batches along natural boundaries within a site is a recommended strategy, such as working with each site section as a separate batch.
Development project scope
All operations are performed within the context of a developer project, and all writes are performed on an unpublished variant of a page or document associated with the project. No changes are made to the live site until after a Site Admin approves and merges the project.
Advantages
Advantages of using the Batch Import:
- It takes care of references between documents that otherwise the client needs to cater for (import documents in proper order)
- It allows developers to focus on the export process from the legacy system, and using one file instead of many makes the process much easier
- It is much more performant: it dramatically removes the overhead of making separate API requests per document
Tutorial
Follow the Import Content step-by-step tutorial on how to use the Batch Import.
API base URL
https://<your_brx_host>.bloomreach.io/management/content-import/v1
Authorization
The Content Import API is a protected management API requiring token authorization. See API Authorization for instructions on how to obtain and use a token.
Updates and conflict prevention
When updating an existing document or page, you must include the entire resource, including all its existing unchanged properties. It's not possible to update only a subset of properties. Read more about how to handle updates and conflict prevention.
API reference
- Content Import Batch Operations
- Open API Specification (JSON) (Open in Swagger)
- Refer to the Folder-based authorization guide to learn how to specify read or write access restrictions for individual users on individual folders.
Developer tools
To aid developers in working and learning the Content Batch Import API, the following tools and resources are provided:
Public environment
If you don't have access to a Bloomreach Content environment yet, you can use the Public Developer Environment. Follow the instructions to retrieve an authentication token and explore the APIs.
Run in Postman
Import the Content Batch Import API collection and try the endpoints in Postman. The collection provides many examples of how the endpoints can be used.
The only thing needed to use the Postman collection is to set up the environment variables:
brxHost: the URL of your Bloomreach Content environmentx-auth-token: the Authentication token