Asynchronous Virtual Instance Operations

Liferay DXP 2026.Q4+

When you add, delete, copy, export, or import a virtual instance, the operation runs in the background. These operations behave the same way on the Virtual Instances page and through the /batch endpoints of the headless API. Only a system administrator (omniadmin) can open the Virtual Instances page and start these operations.

Starting an Operation

You can start these operations from the Virtual Instances page: Global Menu () → Control Panel → Virtual Instances.

Operation	Available
Add	Always
Delete	On every instance except the default
Copy	On every instance except the default, with database partitioning enabled
Export	On every instance except the default, on MySQL or PostgreSQL
Import	With database partitioning enabled

For Add, Copy, and Import, Liferay checks the values you enter before the operation starts and displays an error for invalid values. Otherwise, a message confirms that the operation started, and it runs in the background. If the operation fails after it starts, you receive a notification that identifies the reason. If it succeeds, reload the page to see the change in the list.

Reading the Notification

When an operation ends, you receive a notification that names the instance and says whether it succeeded. A failure notification gives the reason, and an Export success notification names the new schema. To read a notification, click your User Profile Menu → Notifications. Liferay DXP sends no email for these notifications.

Important

An Add notification can arrive shortly before the new instance finishes initializing. If the instance’s site doesn’t load yet, wait a moment and try again.

Running an Operation Through the Headless API

Each operation has an asynchronous endpoint in the Portal Instances API:

Operation	Method and Path
Add	`POST /o/headless-portal-instances/v1.0/portal-instances/batch`
Delete	`DELETE /o/headless-portal-instances/v1.0/portal-instances/batch`
Copy	`POST /o/headless-portal-instances/v1.0/portal-instances/copy/batch`
Export	`POST /o/headless-portal-instances/v1.0/portal-instances/export/batch`
Import	`POST /o/headless-portal-instances/v1.0/portal-instances/import/batch`

When a /batch task ends, the user who sent the request receives the notification described in Reading the Notification. The standard endpoints send no notification.

The request body is a JSON array, so one request can carry several items. Each item in the array takes this form:

Add: The instance object that POST /portal-instances takes. See the create example in Managing Virtual Instances with the Headless API.
Delete: portalInstanceId, the instance’s Web ID.
Copy: sourcePortalInstanceId, name, virtualHost, and webId, plus an optional destinationCompanyId.
Export: portalInstanceId, the instance’s Web ID.
Import: schemaName, plus optional name, virtualHost, and webId.

Each request needs an OAuth2 bearer token, as described in Using the Headless API to Migrate Liferay Instances. To delete an instance, the token’s scopes must cover DELETE on Liferay.Headless.Portal.Instances. To follow the task, they must also cover GET on Liferay.Headless.Batch.Engine. In the example below, replace [token] with your token.

This example deletes the instance whose Web ID is www.able.com:

curl -X DELETE \
    "http://localhost:8080/o/headless-portal-instances/v1.0/portal-instances/batch" \
    -H "Authorization: Bearer [token]" \
    -H "Content-Type: application/json" \
    -d '[{"portalInstanceId": "www.able.com"}]'

The endpoint returns a 202 response whose body is a Batch Engine import task, the record Liferay DXP uses to track the background work. Every /batch operation returns an import task, including Delete and Export. Note the task’s id, because you use it to follow the task.

A request from a user who isn’t an omniadmin still returns 202, and so does an item with an invalid value, such as a virtual host already in use. The item then fails inside the task, and the failure notification gives the reason.

Following the Task

You can follow the task with either of these methods:

Polling: Send GET /o/headless-batch-engine/v1.0/import-task/[id] until executeStatus is COMPLETED or FAILED. See Get the ImportTask Status for an example.
Callback: Pass an http or https URL in the optional callbackURL query parameter instead of polling. When the task ends, Liferay DXP sends one POST request to that URL with a JSON body that maps the task’s id to its executeStatus, such as {"1234": "COMPLETED"}.

These settings in Global Menu () → Control Panel → Instance Settings → Batch Engine → Batch Engine Task Configuration apply to callbacks:

Callback URL Local Network Access Enabled: Enable this setting to send callbacks to a local network address.
Callback URL Hosts Allowed: List the hosts that can receive a callback. Leave the list blank to send callbacks to any host.

Reading the Results

To read the result of Add, Copy, or Import, send GET /o/headless-portal-instances/v1.0/portal-instances/[webId] with the new instance’s Web ID.

To list the items that failed, send GET /o/headless-batch-engine/v1.0/import-task/[id]/failed-items/report.

By default, in a request with several items, the task stops at the first failure. Items before the failure stay complete, and the task skips the items after it. To process the remaining items after a failure, add the importStrategy=ON_ERROR_CONTINUE query parameter to the request.

Operational Limits

One copy and one import run at a time on each node. Through the /batch endpoints, a second copy or import still returns 202. Its task then fails. Liferay DXP doesn’t serialize these operations across nodes, so in a cluster start one copy or import at a time.
By default, Liferay DXP deletes all completed tasks every 14 days, regardless of when each task finished. This means it can remove tasks that finished only minutes before the cleanup process runs. To avoid losing a task’s details, review the task as soon as it finishes. You can configure this behavior under system settings: Global Menu () → Control Panel → System Settings → Batch Engine → Batch Engine Task Configuration → Completed Tasks Cleaner Scan Interval.
Liferay DXP reruns any task that runs longer than the Orphanage Threshold setting. The default is 30 minutes. To avoid a rerun during a long copy, export, or import, raise the threshold under system settings: Global Menu () → Control Panel → System Settings → Batch Engine → Batch Engine Task Configuration → Orphanage Threshold.
You can’t cancel a submitted task.
A failed copy deletes the schema it was copying into. A failed import moves the data back into the lexported_[companyId] schema, so you can import it again.