Batch Engine API Basics - Exporting Data
Liferay’s Headless Batch Engine provides REST APIs to import and export data. Call these services to export data from Liferay.
Exporting Data
Start a new Liferay DXP instance by running
Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.
Then, follow these steps:
-
Download and unzip Batch Engine API Basics.
-
To export data, you must have the fully qualified class name of the entity you are exporting. You can get the class name from the API explorer in your installation at
/o/api
. Scroll down to the Schemas section and note down thex-class-name
field of the entity you want to export. -
Use the following cURL script to export accounts from your Liferay instance. On the command line, navigate to the
curl
folder. Execute theExportTask_POST_ToInstance.sh
script with the fully qualified class name of Account andjson
as parameters. Thejson
parameter denotes the format of the exported data. It also supportsjsont
,jsonl
andcsv
formats.The JSON response shows the creation of a new export task. Note the
id
of the task:Importantjsont
is the required format for*.batch-engine-dat.json
files when using in conjunction with batch client extensions.When using
json
orjsonl
as the output format, all fields are exported by default. To specify fields, you must provide an additional query parameter (fieldNames
) with the fields you want to export. Each field must be separated by a comma (,). When usingcsv
as the export format, this is a mandatory query parameter. -
The current
executeStatus
isINITIAL
. It denotes the submission of a task to the Batch Engine. You must wait until this isCOMPLETED
to download the data. On the command line, execute theExportTask_GET_ById.sh
script and replace1234
with the ID of your export task.If the
executeStatus
isCOMPLETED
, you can download the exported data. If not, execute the command again to ensure the task has finished execution. If theexecuteStatus
showsFAILED
, check theerrorMessage
field to understand what went wrong. -
Once the
executeStatus
isCOMPLETED
, you can download the exported data by executing theExportTaskContent_GET_ById.sh
script and replacing1234
with the ID of your export task.This downloads the exported data as a
.zip
file in the current directory. Extract it and use an appropriate application to view the data. -
You can also call the The REST service using the Java client. Navigate out of the
curl
folder and into thejava
folder. Compile the source files: -
Run the
ExportTask_POST_ToInstance
class. Replaceable
with the fully qualified name of the class.For example, export
Account
data:Note the
id
of the export task from the JSON response. -
Run the
ExportTask_GET_ById
class with the following command. Replace1234
with the ID of your export task. -
Once the
executeStatus
showsCOMPLETED
, you can download the data by running theExportTaskContent_GET_ById
class. Replace1234
with the ID of your export task.
Examine the cURL Command
The ExportTask_POST_ToInstance.sh
script calls the REST service with a cURL command.
Here are the command’s arguments:
Arguments | Description |
---|---|
-H "Content-Type: application/json" | Indicates that the request body format is JSON. |
-X POST | The HTTP method to invoke at the specified endpoint |
"http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}/${2}" | The REST service endpoint |
-u "test@liferay.com:learn" | Basic authentication credentials |
Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application that uses Oauth2.
Examine the Java Class
The ExportTask_POST_ToInstance.java
class exports data by calling the Batch Engine related service.
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
ExportTaskResource.Builder builder = ... | Gets a Builder for generating a ExportTaskResource service instance. |
ExportTaskResource exportTaskResource = builder.authentication(...).build(); | Specifies basic authentication and generates a ExportTaskResource service instance. |
exportTaskResource.postExportTask(...); | Calls the exportTaskResource.postExportTask method and passes the data to post. |
Note that the project includes the com.liferay.headless.batch.engine.client.jar
file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api
.
The main
method’s comment demonstrates running the class.
The other example Java classes are similar to this one, but call different ExportTaskResource
methods.
See ExportTaskResource for service details.
Below are examples of calling other Batch Engine export REST services using cURL and Java.
Get the ExportTask Status
You can get the status of an export task by executing the following cURL or Java command. Replace 1234
with the ID of your export task.
ExportTask_GET_ById.sh
Command:
Code:
ExportTask_GET_ById.java
Run the ExportTask_GET_ById
class. Replace 1234
with the ID of your export task.
Command:
Code:
Exporting Data from a Site
You can export data from a site by executing the following cURL or Java command. The example below exports blog posts from a site. Find your Site’s ID and replace 1234
with it. When using another entity, you must also update the fully qualified class name parameter in the cURL script.
ExportTask_POST_ToSite.sh
Command:
Code:
ExportTask_POST_ToSite.java
Run the ExportTask_POST_ToSite
class. Replace 1234
with your site’s ID and able
with the fully qualified name of the class you want to export:
For example, export BlogPosting
data:
Code:
The second parameter is json
and denotes the output format of the exported data. You can also use jsonl
and csv
here. If using CSV, it is mandatory to specify the fields you want to export as a comma separated string and pass it as the fifth parameter in the exportTaskResource.postExportTask()
method.
The JSON response displays information of the newly created export task. Note the id
to keep track of its executeStatus
. Once completed, you can execute ExportTaskContent_GET_ById.[java|sh]
with the export task ID to download the data.
Filtering Data Exports
You can filter the data in your batch exports by including the filter
parameter with a search term at the end of the URL.
For example, this batch command exports blog postings filtered by the title Able (with the query headline eq 'Able'
):
Exporting custom objects with a filter requires Liferay DXP 2025.Q1+/Portal GA132+. Remember to include both the filter
parameter and the taskItemDelegateName
parameter to specify the custom object.
Exporting Custom Objects
To export custom object entries, you must provide the ObjectEntry
class name in the URL and pass the object’s name in the taskItemDelegateName
query parameter. For example, this command exports instance-scoped Able
’s entries:
Exporting Objects with Permissions
Liferay DXP 2025.Q1+/Portal GA132+
You can export custom objects (and modifiable system objects) together with a list of their assigned permissions in a permissions
field. Add the value permissions
to the optional batchNestedFields
parameter in the URL to signal that you want to export permissions with each object.
The permissions for each exported object are provided in a JSON string like this default:
For example, this command uses the batchNestedFields
parameter to export the instance-scoped Able
object’s entries together with their permissions:
You can then import the data you downloaded as well, and the imported object entries keep their assigned permissions.
If you import object entries exported with permissions but the target instance does not contain the same roles for each of them, the import results in an error.
Get Contents of the Exported Data
You can download the exported data with the following cURL and Java commands. Replace 1234
with the export task’s ID. It is then downloaded as a .zip
file in the current directory.
ExportTaskContent_GET_ById.sh
Command:
Code:
ExportTaskContent_GET_ById.java
Command
Code:
The API Explorer lists all of the Headless Batch Engine services and schemas and has an interface to try out each service.