AEM Forms as a Cloud Service Communications Batch Processing

Communications lets you create, assemble, and deliver brand-oriented and personalized communications such as business correspondences, documents, statements, claim processing letters, benefit notices, monthly bills, and welcome kits. You can use Communications APIs to combine a template (XFA or PDF) with customer data to generate documents in PDF, PS, PCL, DPL, IPL, and ZPL formats.

Communications provide APIs for on-demand and scheduled document generation. You can use synchronous APIs for on-demand and batch APIs (asynchronous APIs) for scheduled document generation:

Batch operations batch-operations

A batch operation is a process of generating multiple documents of similar type for a set of records at scheduled intervals. A batch operation has two parts: Configuration (definition) and execution.

Components of a batch operation components-of-a-batch-operations

Cloud configuration: Experience Manger Cloud configuration helps you connect an Experience Manager instance to customer owned Microsoft Azure Storage. It lets you specify the credentials for customer owned Microsoft Azure account to connect to it.

Batch Data Store configuration (USC): Batch data configuration helps you configure a specific instance of Blob storage for Batch APIs. It lets you specify the input and output locations in customer owned Microsoft Azure Blob storage.

Batch APIs: Lets you create a batch configurations and execute the batch runs based on these configurations to merge a PDF or XDP template with data and generate output in PDF, PS, PCL, DPL, IPL and ZPL formats. Communications provide batch APIs for configuration management and batch execution.

Storage: Communication APIs use customer owned Microsoft Azure Cloud storage to fetch customer records and store generated documents. You configure Microsoft Azure Storage in Experience Manager Cloud Service Configuration.

App: Your custom application to use the Batch APIs to generate and consume documents.

Generate multiple documents using batch operations generate-multiple-documents-using-batch-operations

You can use batch operations to generate multiple documents at scheduled intervals.

You can watch the video or perform the instructions below to learn how to generate documents using batch operations. The API reference documentation used in video is available in the .yaml format. You can download the Batch APIs file and upload it to Postman to check functionality of APIs and follow along the video.

Pre-requisites pre-requisites

To use Batch API, the following is required:

Set up your environment setup-your-environment

Before using a batch operation:

Upload customer data (XML files) to Azure Storage upload-customer-data-to-Azure-Storage

On your Microsoft Azure Storage, create containers and upload customer data (XML) to the folders inside the containers.

Create a Cloud configuration create-a-cloud-configuration

The Cloud configuration connects your Experience Manager instance to Microsoft Azure Storage. To create a Cloud configuration:

Your Experience Manager instance is now ready to connect to Microsoft Azure Storage and use it to store and read content, when required.

Create Batch Data Store configuration create-batch-data-store-configuration

Batch data configuration helps you configure containers and folders for input and output. You keep your customer records in Source Folder and generated documents are placed in the Destination Folder.

To create the configuration:

Your Experience Manager instance is now connected to Microsoft Azure Storage and configured to retrieve and send data to specific locations on Microsoft Azure Storage.

Upload templates and other assets to your Experience Manager instance upload-templates-and-other-assets-to-your-AEM-instance

An organization typically has multiple templates. For example, one template each for credit card statements, benefits statements, and claim applications. Upload all such XDP and PDF templates to your Experience Manager instance. To upload a template:

Use batch API to generate documents use-batch-API-to-generate-documents

To use a batch API, create a batch configuration and execute a run based on that configuration. The API documentation provides information about APIs to create and run a batch, corresponding parameters, and possible errors. You can download the API definition file file and upload it to Postman or similar software to test the APIs to create and run a batch operation.

Create a batch create-a-batch

To create a batch, use the POST /config API. Include the following mandatory properties in the body of the HTTP request:

If you specify relative path, also provide a content root. See, API documentation for details of content root.

You can use GET /config /[configName] to see details of the batch configuration.

Run a batch run-a-batch

To run (execute) a batch, use the POST /config /[configName]/execution. For example, to run a batch named wknd-demo, use /config/wknd-demo/execution. The server returns HTTP response code 202 on accepting the request. The API does not return any payload except a unique code (execution-identifier) in header of HTTP response for the batch job running on the server. You can use the execution-identifier to retrieve the status of the batch.

Check status of a batch status-of-a-batch

To retrieve status of a batch, use the GET /config /[configName]/execution/[execution-identifier]. The execution-identifier is included in the header of HTTP response for the batch execution request.

The response of the status request contains the status section. It provides details about status of the batch job, number of records already in pipeline (already read and being processed), and status of each outputType/renderType(number of in-progress, succeeded, and failed items). Status also includes start and end time of batch job along with information about errors, if any. The end time is -1 until batch run actually completes.

View generated documents view-generated-documents

On completion of job, the generated documents are stored to the success folder at the destination location specified in the Batch Data Store configuration. If there are any errors, the service creates a failure folder. It provides information about the type and reason of errors.

Let’s understand with the help of an example: Assume there is an input data file record1.xml and two output types: PDF and PCL. Then the destination location contains two sub-folders pdf and pcl, one for each of the output types. Lets assume PDF generation succeeded, then the pdf sub-folder contains the success sub-folder which in turn contains the actual generated PDF document record1.pdf. Lets assume PCL generation failed, then the pcl sub-folder contains a failure sub-folder which in turn contains an error file record1.error.txt which contains details of the error. Also, the destination location contains a temporary folder called __tmp__ which holds certain files required during batch execution. This folder can be deleted when there are no active batch runs referencing the destination folder.

API reference documentation

The API reference documentation provides detailed information about all the parameters, authentication methods, and various services provided by APIs. The API reference documentation is available in the .yaml format. You can download the Batch APIs file and upload it to Postman to check functionality of APIs.