Promoting Content to New Environments

Liferay DXP 2026.Q1+

Liferay Archive (LAR) files allow for transferring content, data structures, and even whole sites between Liferay environments. Previously, exports always handled entities via the staging framework, which internally handles data with an XML structure.

As of Liferay DXP 2026.Q1, many entities in Liferay are handled internally as JSON, via the batch framework. These entries use external reference codes as unique identifiers between environments, which is more flexible and robust.

Batch-supported entities also bring several new features to LAR exports and imports, including lazy references to content, instance-level LAR export/imports, and improved import error reporting.

This added flexibility reinforces LAR exports and imports as a reliable way to promote and replicate content between environments. Some entities, however, don’t yet use the batch framework, so they don’t support these features. See the supported entity types for more information.

Note

Batch-supported entities always use Mirror, as do instance imports. Mirror with overwriting is available for site, asset library, and widget imports. Copy as New is deprecated.

Lazy References

You can import batch-supported entries into another environment without importing referenced content. The included “lazy references” do not appear until the referenced content is also imported.

With lazy references, you can promote your content more flexibly, without worrying about missing reference errors for the referenced content. It also means that you can import any subset of that content in any order, as long as it also uses the batch framework.

Important

A batch-supported entity never carries its referenced content to Live automatically, regardless of what it references. This covers a reference to another entity, a parent page, content shown in a widget, and content shown in a fragment. You must select that content in the publish process. An entity the batch framework does not handle still carries a referenced batch-supported entity to Live with it.

Because they use lazy references, batch-supported entities do not include any referenced content in your LAR exports automatically. Carefully ensure your exports include the referenced content you also want to persist.

Publishing to Live through Liferay Staging uses the same import path. This means batch-supported entities do not carry their referenced content to Live automatically. See Understanding Batch-Supported Publishing for more information.

Instance-Level Content

You can export instance-level content, such as object definitions or roles with similar functionality to site-level content. All eligible entities for instance-level exports use the batch framework.

You can export instance-scoped entities similarly to site-scoped entities.

The scope of your LAR export (site or instance) also determines its import scope. See Exporting Data for more information.

Import Error Reporting

Because of lazy references, LAR imports can still complete even with some errors related to specific content. You can view the specific error details for an import process by clicking View Report Entries on the Import page.

Some errors don't prevent LAR imports from completing.

Click a specific error entry to see its details.

See Importing Data with a LAR File for more information.

Batch-Supported Entity Types

These entities use the batch framework for LAR exports and imports as of Liferay DXP 2026.Q1, except where a badge notes a later version.

Entities	Instance or Site Level
Accounts	Instance
Account Groups	Instance
Categories	Site
Liferay DXP 2026.Q3+ Countries	Instance
Object Definitions	Instance
Object Entries	Instance and Site
Organizations	Instance
Pages and Page Templates	Site
Picklists	Instance
Roles	Instance
Tags	Site
Liferay DXP 2026.Q3+ User Groups	Instance
Vocabularies	Site

A countries export also includes their regions, and a user groups export also includes their role assignments. Regions aren’t a selectable entity type here, so a countries export is the way to move them.

Future updates may add batch framework support for more entity types.

Note

Publications are not supported for LAR exports or imports. Support is not planned for a future update.

Promoting Pages with the Page Management API

Liferay DXP 2026.Q3+ Release Feature

You can also promote pages through the Page Management API. It identifies entities by external reference code rather than internal ID, so one request body resolves in every target environment. Pages, their components, and the entities they reference carry these codes, with a few exceptions: out-of-the-box fragments are referenced by fragment key, widget page layout templates by template ID, and widget instances by widget name and instance ID.

Enabling the API

Enable Page Management API (LPD-35443) on each instance that receives direct API requests. Every request to these endpoints checks this flag.

Two other flags apply only to particular operations:

Feature Flag	Required For
Private Pages (LPD-38869)	Listing, creating, or modifying private pages. Send `privateLayout=true` with these requests, since they address public pages by default. Reading or deleting a page by external reference code takes no `privateLayout` parameter.
Widget Pages (LPD-76864)	Creating a widget page or a widget page template. Reading and updating existing widget pages works without it.

Find these on the Deprecation tab under Instance Settings → Feature Flags. They’re enabled on upgraded installations, and disabled on new installations and instances.

Reading and Writing Site Pages

In the Headless Admin Site application (/o/headless-admin-site/v1.0), site pages are at the /sites/{siteExternalReferenceCode}/site-pages endpoint. A PUT to /sites/{siteExternalReferenceCode}/site-pages/{sitePageExternalReferenceCode} creates the page when no page carries that external reference code and updates it when one does. For the base URL and authentication, see Site API Basics.

The API covers these entities:

Content pages
Display page template folders
Display page templates
Master pages
Page template sets
Page templates
Utility pages

Set type on every request, matching the value to the page:

`type`	Page Type
`ContentPage`	Content page
`EmbeddedPage`	Embedded
`LinkToPagePage`	Link to a Page of This Site
`LinkToURLPage`	Link to URL
`PageSetPage`	Page Set

A request body without type creates a widget page, and bypasses the Widget Pages flag check, which runs only on an explicit WidgetPage value. A page’s name and friendly URL are localized maps (name_i18n and friendlyUrlPath_i18n) rather than plain strings.

These types cover the other page types the API reaches; the linked article describes Liferay DXP’s full set of page types.

Page Specifications

A page specification describes a content page’s contents as page experiences, each holding a tree of page elements such as containers, grids, fragment instances, and widget instances. A content page always has a draft layout and a published layout, each with its own page specification.

Send a page specification as part of the site page request rather than as a standalone entity. Send both of a content page’s specifications: when you create a page you can send one and Liferay DXP derives the other from it, but updating an existing page requires both.

A page’s specifications and friendly URL history aren’t returned by default. When you read a page you intend to promote, request them with nestedFields=pageSpecifications,friendlyUrlHistory. The friendly-url-history sub-resource lists the redirects a page accumulated under earlier URLs.

Warning

A page read without nestedFields carries no page specifications. Sending that response to an environment that doesn’t have the page yet creates an empty page and returns a success response.

Publishing a Promoted Page

A promoted content page arrives unpublished. Its published specification carries a Draft status, and the page returns a 404 at its friendly URL until it’s approved. To publish the page, send Approved as the status on its page specifications in the site page request.

Warning

The page-specifications/{pageSpecificationExternalReferenceCode}/publish endpoint appears in the API contract without an implementation. It returns 204 with an empty body and publishes nothing. Set the specification status instead.

Unresolved References

Promote referenced entities before or with the pages that use them.

Important

A page specification can reference an entity the target environment doesn’t have yet, such as a fragment, master page, display page template, collection, or experience. The request still succeeds. Liferay DXP stores the reference as an external reference code rather than a resolved ID, so the page finds the entity as soon as one with that code exists in the environment. Until then the page renders an empty region where that entity belongs, with no error.