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 interact with their object data and populate dashboards with historic data sets.

In these exercises, you’ll export Clarity’s object entries and import JSON data with batch endpoints.

Exercise: Exporting Clarity’s Existing Tickets

Here, you’ll leverage the export-task endpoint to create a batch export of Clarity’s existing Ticket object entries.

1. Sign in as the Clarity Admin user.

   • Username: admin@clarityvisionsolutions.com

   • Password: learn

2. Navigate to the API Explorer at http://localhost:8080/o/api.

3. In the upper right, click the REST Applications drop-down menu and select headless-batch-engine/v1.0.

4. Under the ExportTask section, expand the postExportTask endpoint.
   

5. Enter these parameters and click Execute:

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

6. 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": "91346fb5-253e-211b-605c-ff3fa4a57bfe",
   	"id": 18,
   	"processedItemsCount": 0,
   	"startTime": "2025-03-27T23:05:31Z",
   	"totalItemsCount": 0
   }
   

   Copy
   The current executeStatus should list STARTED, confirming submission of the batch engine task.

7. Copy the ID value for a future step. In this case: 18.

8. Within the Headless Batch Engine API, expand the getExportTask endpoint.

9. Paste in the previously copied ID to the exportTaskId parameter and click Execute.

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

    {
    	"className": "com.liferay.object.rest.dto.v1_0.ObjectEntry",
    	"contentType": "JSON",
    	"endTime": "2025-03-27T23:05:31Z",
    	"errorMessage": "",
    	"executeStatus": "COMPLETED",
    	"externalReferenceCode": "91346fb5-253e-211b-605c-ff3fa4a57bfe",
    	"id": 18,
    	"processedItemsCount": 8,
    	"startTime": "2025-03-27T23:05:31Z",
    	"totalItemsCount": 8
    }
    

    Copy
    Batch jobs can include thousands of data entries, extending the required time to complete tasks. You can use this endpoint to check in on a batch job’s progress while it’s being processed.

11. Within the Headless Batch Engine API, expand the getExportTaskContent endpoint.

12. Enter the same previously copied ID for the exportTaskId and click Execute.
    

13. Verify that the request's status code is 200 and the Response body includes a “Download file” link.
    

The downloaded file contains a JSON array containing all of Clarity’s existing Ticket entries, including only the filtered fields specified within the batch export job.

Exercise: Importing Clarity’s New Ticket Object Entries

While you can also create import jobs with the Headless Batch Engine API’s import-task endpoints, Clarity would like to test leveraging the Ticket object’s batch endpoint to import a historic data set. Here, you’ll create a batch import to populate additional ticket object entries.

1. Navigate to the API Explorer at http://localhost:8080/o/api.

2. In the upper right, click the REST Applications drop-down menu and select c/tickets.

3. Under the Ticket section, expand the postTicketBatch endpoint.

4. Replace the placeholder curly brackets in the Request body with two square brackets.
   
   
   This prepares your payload to include a JSON array.

5. In your course workspace, navigate to the exercises/module-3/historic_ticket_data.json file and copy its contents.

6. In API Explorer, paste the JSON contents between the square brackets and click Execute.

7. Examine the Request body to verify that the import started:

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

   Copy
   The executeStatus of INITIAL indicates that the batch job has started.

8. From the Response body, copy the job’s externalReferenceCode.

9. In the upper right, click the REST Applications drop-down menu and select headless-batch-engine/v1.0.

10. Under the ImportTask section, expand the getImportTaskByExternalReferenceCode endpoint.

11. Paste the copied externalReferenceCode and click Execute.
    

12. Verify that the Response body lists COMPLETED with 10 total items imported:

    

    
    While you can also create import jobs with the Headless Batch Engine API’s import-task endpoints, Clarity would like to test leveraging the Ticket object’s batch endpoint to import a historic data set. Here, you’ll create a batch import to populate additional ticket object entries.

    If the executeStatus shows FAILED, check the errorMessage field to understand what issue was encountered.

13. Navigate to the Clarity home page

14. 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.

Conclusion

Excellent! You’ve successfully leveraged batch engine APIs to export batch data from Liferay and import a set of object entries. This provides the foundation to migrate large data sets within your Liferay environment using APIs.

Next, you’ll review what you've learned before completing the course.