Importing and Exporting Clarity's Bulk Data

Batch engine APIs provide a high-performance approach to interacting with large data sets. Clarity's developers want to test importing and exporting with batch APIs to understand how they can empower Clarity to manage object data at scale through bulk imports, exports, and updates. This approach ensures dashboards are supplied with historical and up-to-the-minute information.

In these exercises, you'll perform batch operations for Clarity's Tickets object.

Exercise: Exporting Clarity's Existing Tickets

Here, you'll use the export-task endpoint to create a batch export of existing tickets as the Clarity Admin user.

Sign in using these credentials.
- Username: admin@clarityvisionsolutions.com
- Password: learn
Navigate to the API Explorer at http://localhost:8080/o/api.
In the upper right, click the REST Applications drop-down menu and select headless-batch-engine/v1.0.
Under the ExportTask section, expand the postExportTask endpoint.

Enter these parameters and click Execute:

Parameter	Value
className	com.liferay.object.rest.dto.v1_0.ObjectEntry
contentType	JSON
batchNestedFields	permissions
fieldNames	`description,priority,resolution,subject,suggestions,ticketStatus,type`
taskItemDelegateName	C_Ticket

NOTE
To import object entries, use the object definition as the value for the taskItemDelegateName property. The value's format should be C_ObjectName, where C_ is a prefix followed by the object's name (case-sensitive).

Verify in the Response body that the batch process was submitted:

{
  "className": "com.liferay.object.rest.dto.v1_0.ObjectEntry",
  "contentType": "JSON",
  "errorMessage": "",
  "executeStatus": "STARTED",
  "externalReferenceCode": "70fbff63-fab4-fafe-71d0-33fc0862cfcd",
  "id": 6,
  "processedItemsCount": 0,
  "startTime": "2025-05-20T20:58:31Z",
  "totalItemsCount": 0
}

If the executeStatus is STARTED, the batch engine task was submitted.

Copy the ERC (externalReferenceCode) value for a future step.
In this case, 70fbff63-fab4-fafe-71d0-33fc0862cfcd.
Within the Headless Batch Engine API, expand the getExportTaskByExternalReferenceCode endpoint.
Paste in the previously copied ERC to the externalReferenceCode parameter and click Execute.

Verify that the batch job now lists COMPLETED for the executeStatus:

{
  "className": "com.liferay.object.rest.dto.v1_0.ObjectEntry",
  "contentType": "JSON",
  "endTime": "2025-05-20T20:58:31Z",
  "errorMessage": "",
  "executeStatus": "COMPLETED",
  "externalReferenceCode": "70fbff63-fab4-fafe-71d0-33fc0862cfcd",
  "id": 6,
  "processedItemsCount": 6,
  "startTime": "2025-05-20T20:58:31Z",
  "totalItemsCount": 6
}

Large batch jobs can include thousands of data entries and take longer to complete. You can use this endpoint to check in on a batch job's progress while it's being processed.

Within the Headless Batch Engine API, expand the getExportTaskByExternalReferenceCodeContent endpoint.
Enter the same previously copied externalReferenceCode and click Execute.
Verify that the request's status code is 200 and the Response body includes a "Download file" link.

The downloaded zip file contains a JSON array with all of Clarity's existing Ticket entries, including only the filtered fields specified in the batch export job, and the permissions for each entry, which we requested with the batchNestedFields parameter.

Exercise: Importing Clarity's New Ticket Object Entries

You can create import jobs using the standard Headless Batch Engine API's import-task endpoints. However, Clarity wants to test importing their records using the Ticket object's dedicated batch endpoint instead. Here, you'll create a batch import to populate additional ticket object entries as the Clarity Admin user.

Navigate to the API Explorer at http://localhost:8080/o/api.
Click the REST Applications drop-down menu and select c/tickets.
Under the Ticket section, expand the postTicketBatch endpoint.
Replace the placeholder curly brackets in the Request body with two square brackets.

This prepares your payload to include a JSON array.
In your course workspace, open the exercises/module-3/historic_ticket_data.json file and copy its contents.
In API Explorer, paste the JSON contents between the square brackets and click Execute.

Examine the Request body to verify that the import started:

{
  "className": "com.liferay.object.rest.dto.v1_0.ObjectEntry",
  "contentType": "JSON",
  "errorMessage": "",
  "executeStatus": "STARTED",
  "externalReferenceCode": "5bd670b5-4780-d269-263a-2be27d6a620c",
  "failedItems": [],
  "id": 2603,
  "importStrategy": "ON_ERROR_FAIL",
  "operation": "CREATE",
  "processedItemsCount": 0,
  "totalItemsCount": 10
}

The executeStatus of STARTED indicates that the batch job has started.

From the Response body, copy the job's externalReferenceCode.
In the upper right, click the REST Applications drop-down menu and select headless-batch-engine/v1.0.
Under the ImportTask section, expand the getImportTaskByExternalReferenceCode endpoint.
Paste the copied externalReferenceCode and click Execute.
Verify that the Response body lists COMPLETED with 10 total items imported:

NOTE
If the executeStatus shows FAILED, check the errorMessage field to understand what issue was encountered.
Navigate to the Clarity home page.
Open the Site Menu (), click Page Tree, and navigate to the Tickets page.
You should see 10 additional tickets included on Clarity's dashboard, including historic, closed tickets.

Exercise: Using Batch APIs to Update Clarity's Tickets

In addition to using the batch endpoint to import data, you can use available endpoints to update ticket information. Here, you'll create a batch import to update the resolution and ticket status of two existing tickets as the Clarity Admin user.

Navigate to the Clarity Home page.
Open the Site Menu (), click Page Tree, and navigate to the Tickets page.
Identify these two tickets: one assigned to Emily and one assigned to Neil.

In the following steps, you'll update their status to Closed.
Navigate to the Liferay API Explorer at http://localhost:8080/o/api.
Click the REST Applications drop-down menu and select c/tickets.
Under the Ticket section, expand the putTicketBatch endpoint.
Replace the placeholder curly brackets in the request body with two square brackets.
In your course workspace, open the exercises/module-3/close_tickets.json file and copy its contents.
In API Explorer, paste the JSON contents between the square brackets and click Execute.
Copy the externalReferenceCode parameter's value in the response message.
Click the REST Applications drop-down menu and select headless-batch-engine/v1.0.
Under the ImportTask section, expand the getImportTaskByExternalReferenceCode endpoint.
Paste the copied externalReferenceCode and click Execute.
The executeStatus of the response should indicated "COMPLETED".
Navigate to the Clarity home page.
Open the Site Menu (), click Page Tree, and go to the Tickets page.
Verify the tickets have been resolved and closed.

Conclusion

Excellent! You’ve successfully leveraged dedicated batch APIs to export batch data from Liferay and both imported and updated a set of object entries. You’ve explored both the dedicated batch engine endpoints and an entity-specific batch endpoint. This provides the foundation to migrate large data sets within your Liferay environment using APIs.

Next, you’ll learn how Liferay’s MCP feature connects AI tools directly to your server for real-time code assistance.