Introduction

Liferay's Batch Engine is the workhorse behind bulk data movement into Liferay. Instead of creating records one REST call at a time, you POST (or PUT, or DELETE) an array of items to a /batch endpoint for the entity you care about — Objects, Commerce catalogs, channels, product specifications, whatever — and the Batch Engine takes it from there. It queues the work as an asynchronous import task, processes the records, and updates that task's status as it goes, from INITIAL through to COMPLETED (or FAILED).

That async, fire-and-forget model is exactly what you want when an external system needs to push thousands of records into Liferay without waiting around for a synchronous response. It's also exactly what makes the next question so important: once you've fired that batch off, how do you know what actually happened to it?

Problem Overview

This came up for real on a large-scale B2B commerce project we've been building. The setup is a common one:

• Product data — categories, specifications, products, pricing, you name it — lives in an external PIM system, not in Liferay.

• An integration middleware layer owns the sync: it reads from the PIM and calls Liferay's Headless Batch APIs to push data in.

• Liferay is the consumer, not the source of truth. From Liferay's side, batches just show up.

And, inevitably, some of those batches fail. The reasons vary:

• Invalid data — a field that doesn't match the expected format or type;

• Duplicate data — an external reference code or any other field that's already in use;

• Internal Batch Engine errors — timeouts, constraint violations, anything else that can go wrong mid-import.

Here's the problem: Liferay doesn't ship a UI for any of this. When the middleware team says "we pushed 500 products and something failed," the only way to find out what, exactly, is to go spelunking through application logs or query the database directly — and that's assuming you have that kind of access to a client's environment in the first place. 

But Liferay already has the answer. Every batch import task the Batch Engine runs is persisted — its status, timing, item counts, and errors — in its own tables (BatchEngineImportTask and BatchEngineImportTaskError). The data we needed was sitting right there. It just wasn't visible to anyone.

Solution Overview

So we built Batch Import Audit: a Control Panel tool that puts the Batch Engine's own record-keeping in front of the people who actually need it — support engineers, integration developers, and admins — without anyone touching a database client.

The tool adds a new Monitoring category to the Control Panel, with a Batch Import Audit app underneath it. Conceptually, the relationship to the underlying data is simple:

• BatchEngineImportTask the source for the main list: one row per import task, with its class name, execute status, initiating user, start/end time, and total vs. processed item counts.

• BatchEngineImportTaskError is the source for what went wrong: when a task fails, this is where the record-level detail lives — which item failed, and why.

The list view gives you every import task the Batch Engine has ever run, newest first, with filters for:

• Initiator — which user (or integration account) triggered the import

• Execute Status — e.g. completed, failed, in progress

• Class Name — which entity type was being imported (catalogs, channels, products, etc.)

• External Reference Code — find the task that touched a specific record, by its ERC

The details view is where the actual troubleshooting happens. Open any task and you get its full metadata — batch size, content type, import strategy, operation, timing — along with the original request payload, unpacked and pretty-printed exactly as it was submitted. For failed tasks, this is also where the task-level error information and the underlying error records surface, so you can see not just that something failed, but which record and why, without ever leaving the browser.

You can view and easily copy the task content of the failed batch import task, to analyze it separately: in your IDE or using AI.

If you want to find out when/how a specific entity was imported - you can perform a search using it's ERC field, and see the task details:

Summary

For any project where Liferay is on the receiving end of a data pipeline it doesn't control — PIM systems, ERPs, legacy migrations — batch import failures aren't a matter of if, they're a matter of when. Batch Import Audit doesn't change how the Batch Engine works; it just makes the information the Batch Engine was already recording actually visible, so troubleshooting a failed import is a filter and a click instead of a support ticket and a database query.

If you're dealing with the same kind of integration setup and this looks useful, the code is available in this repo — take a look, adapt it, or open an issue with questions, feedback, or ideas for where it should go next.

Leave your comments and feedback.

Stand with Ukraine  

Enjoy 😏