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 and import Clarity’s object entries with JSON data and batch API 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
   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).

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": "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.

7. Copy the ERC (externalReferenceCode) value for a future step.
   In this case, 70fbff63-fab4-fafe-71d0-33fc0862cfcd.

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

9. Paste in the previously copied ERC to the externalReferenceCode 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-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.

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

12. Enter the same previously copied externalReferenceCode 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 create import jobs with the Headless Batch Engine API’s import-task endpoints, Clarity would like to test leveraging the Ticket object’s dedicated batch endpoint to import some historic data records. 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, open 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": "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.

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:

    
     
    NOTE
    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 dedicated batch APIs to export batch data from Liferay and import 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 review what you've learned before completing the course.