Broadleaf Microservices
  • v1.0.0-latest-prod

Export Common Library

See the Import and Export docs.

High Level Overview

Microservices can use the Broadleaf Export Common Library to acquire additional functionality to generate a flat data file (like a CSV or Excel Sheet) from existing records of a given type. This library offers flexibility to:

  • Output data from any persisted domain.

  • Customize mapping from domain field to file column.

  • Customize the file format for the export.

  • Trigger exports and downloads from any view in the admin.

Unlike the Import Service, Export is not its own microservice. The Export functionality is added to existing microservices entirely through the broadleaf-common-dataexport dependency.

Overall Architecture and Flow

export overall architecture

Common Components

The following interfaces are common to all target export implementations of the Broadleaf Export Common Library, and most use cases of Broadleaf may successfully delegate to their Out-Of-Box default implementation.


See the ExportManager Javadocs.

This component is in charge of the high-level logic to coordinate export operations. The out-of-box standard implementation of this component is DefaultExportManager. In almost all scenarios, clients should not need to customize this component. It internally delegates to the ExportService, the ExportProcessor, and the ExportFileWriter


See the ExportService Javadocs.

This is the Service API in charge of Export CRUD-related operations.

Besides methods that work in conjunction with the ExportRepository, the Out-of-Box DefaultExportService has additional methods to update the export status and send notifications at a given point of the flow. For instance, its create() method leverages the messaging configuration to produce a ProcessExportRequest, to be later consumed by the ProcessExportRequestListener and once again delegate to the ExportManager, triggering its processExport() method.


This service provides the ability to retrieve a file for a given export record. Out-of-Box, Broadleaf provides a DefaultExportDownloadService.


This component is responsible for writing the headers and rows of an export to a file. Each file type that needs to be supported should have a dedicated implementation of the ExportFileWriter interface.

Out-of-Box, Broadleaf provides a CSVExportFileWriter implementation.

Target Specific Components

The following components call for implementation of the interfaces provided in the Broadleaf Export Common Library, extension thereof, or newly-added classes in order to meet the requirements specific to the target export implementation.


This component is responsible for executing the actual target-specific export processing behavior for a particular export target.

Each export target must have a dedicated implementation of the ExportProcessor interface to support it.


This component is responsible for providing structural information, such as a map of headers to fields, to define the schema of the output. The defined ExportSpecification is later used to construct a SpecificationPropertiesSerializerModifier in charge of excluding the property names not included in the specification, and converting property names to header names. This component is later consumed by related ExportRowConverters

Each export target must have a dedicated implementation of the ExportSpecification interface to support it.

Row Converter

A class designated to convert the values of each desired POJO field into a row representation via a convert() method. This isolates and abstracts away 'conversion' functionality such that it is not a direct responsibility of the ExportProcessor implementation, providing cleaner code. It may also define any additional methods to map an export record to a row in the desired file type. Most Out-of-Box converters are an extension of AbstractExportRowConverter.

Export row converter classes operate according to the details defined in the ExportSpecification. In order to utilize these details, this component relies on a SpecificationPropertiesSerializerModifier class when creating the ObjectMapper to be used in the conversion process. To support converting complex fields, custom serializers may be added to this SpecificationPropertiesSerializerModifier in a dedicated method in the row converter class.

Each export target should have a dedicated row converter class to support field serialization.

Often times, one converter is responsible for converting one specific entity type to a row representation. Each ExportProcessor implementation can choose to inject and delegate to a particular row converter implementation for row conversion. In some complex cases where many converters are required for a particular ExportProcessor (ex: if the output includes multiple entity types each with their own rows), it may be beneficial to introduce a new ExportRowProducer implementation that itself can inject and delegate to a variety of converters. Then, the ExportProcessor can simply inject and delegate to that ExportRowProducer.


Each export target implementation should have corresponding endpoints that are the direct point of communication with ExportManager. There should be custom endpoints defined for initiating and reading historical Export operations for a specific target, as well as an endpoint for downloading the files from completed export operations.

In common use cases of Broadleaf, these endpoints are exposed using metadata to perform export operations in the admin. For more information on how to do this, visit this documentation.


The Broadleaf Common Data Export Library manages the processing of ProcessExportRequest as they are emmitted to the message broker. Out-of-Box, Broadleaf provides the ProcessExportRequestProducer and ProcessExportRequestProducer Spring Cloud channels to handle export-related notifications. Visit the messaging package Javadocs.

Microservices who consume the export library must configure the requisite message bindings in their application properties.