Content Batch Import API

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 line of the file 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 which 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 takes care to clean up as much as possible (for exampl delete or revert unfinished/corrupted documents). It is also possible to easily clean 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 section of a site 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 and requires authorization using a token. 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

Developer tools

To aid developers in working and learning the Content Batch Import API, the following tools and resources are provided:

Public Environment

In case you don't yet have access to a Bloomreach Content environment, you can Log in to the Public Developer Environment. Follow the instructions to retrieve an authentication token and explore the APIs.

Run in Postman

Easily fork the Content Batch Import API collection and try the endpoints in Postman. The advantage is that in Postman we offer many examples of how the endpoints can be used.

Run in PostmanRun in Postman

The only thing needed to use the Postman collection is to setup the environment variables:

  • brxHost: the URL of your Bloomreach Content environment
  • x-auth-token: the Authentication token

Swagger UI

It's possible to trigger API requests requests directly to a Bloomreach Content environment using the Swagger UI. Via the below URL, explore and try out the Content Batch Import API:

https://<your_brx_host>.bloomreach.io/management/content-import/v1/api-docs