Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/manage-data-sets

manage-data-sets

Verified

Create and configure Liferay Data Sets (Frontend Data Sets) over object entries through the data-set-admin API — table, list, and card views, columns and renderers, filters, default sort, row and creation actions, custom renderer and filter client extensions — then place the Data Set fragment on a page and move the definition between environments. Use when the user asks for a table, list, or card grid of object entries, a filterable listing, or a Data Set that renders nothing or crashes.

Manage Data Sets

A Data Set is a configurable table, list, or card view over a REST collection, usually an object's /o/c/<plural>. It is built from the Data Set definition (the data-set-admin API) and the Data Set fragment placed on a page. The definition itself is stored as entries of the system object L_DATA_SET, with one related object per child type.

Everything below was verified live on 2026.Q3.2: writes read back over the API, the rendered page checked in a browser, and admin UI shapes captured for comparison.

When to Invoke

  • "Show the books in a table", "a filterable list of …", "cards of …", "add a column / filter / sort / row action"
  • A Data Set fragment shows nothing, "No Results Found", or "An unexpected error occurred"
  • Moving a Data Set to another environment

Page placement is manage-pages, grants are manage-roles-permissions, and renderer or filter CETs are scaffold-client-extension.

Prerequisites

  • Feature flag LPS-164563 (note the LPS prefix). Without it, data-set-admin returns 404. On 2026.Q1 and 2026.Q2 it also needs LPD-34594 (Root Object Definitions), and stays off while that one is off. See feature-flags.
  • Verified on 2026.Q3 only. On 2026.Q2 the API and the page fragment exist as below; on 2026.Q1 the page fragment differs (see "Place the Data Set Fragment").
  • The module has no version segment: /o/data-set-admin/data-sets; /o/data-set-admin/v1.0/… returns 404.
  • The OpenAPI spec is per resource, not at the module root: /o/data-set-admin/<resource>/openapi.json for actions, cards-sections, client-extension-filters, data-sets, date-filters, list-sections, selection-filters, snapshots, sorts, and table-sections. Read required fields there. data-sets also exposes batch, export-batch, permissions, and validate.

Workflow

Create the Data Set

curl \
	--data '{
		"defaultItemsPerPage": 20,
		"externalReferenceCode": "<PROJECT>_<PURPOSE>_DS",
		"label": "<Display Name>",
		"listOfItemsPerPage": "10, 20, 50",
		"restApplication": "/c/<plural>",
		"restEndpoint": "/",
		"restSchema": "<ObjectDefinitionName>"
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/data-set-admin/data-sets" \
	--user "test@liferay.com:test"
  • Always choose the ERC. It is the only portable pointer, and the page fragment references the Data Set by it. The admin UI cannot set one: it generates a UUID, which a later PATCH of externalReferenceCode can rename.
  • The fetch URL is "/o" + restApplication + restEndpoint. So restApplication starts with / (/c/<plural>), and restEndpoint is / for an object. "object-admin" produces /oobject-admin/, a 404, and an empty fragment.
  • A versioned Headless module (e.g. Accounts) splits the path as restApplication: "/headless-admin-user", restEndpoint: "/v1.0/accounts". Put the version in restEndpoint, or it is dropped.
  • restSchema is not part of the URL. Set it to the object's name (restSchema: "ObjectEntry" still renders).
  • label and listOfItemsPerPage are plain strings. A map or an array is silently stored as its Java toString() ({en_US=…}, "[10, 20, 50]") and shown that way in the admin list. label_i18n and objectDefinitionId do not exist and are ignored.
  • Display switches:
    • active: false hides the whole fragment, with no request and no message;
    • defaultVisualizationMode (table | list | cards, lowercase);
    • hideManagementBarInEmptyState;
    • showSearch (adds &search=);
    • snapshotsEnabled (views saved by the user, stored separately in /o/data-set-admin/snapshots).
  • POST /data-sets/validate takes {"values": {…}}. {} returns a 500 NPE, and it does not catch a label whose value is a map.

Add Children — Only Through the Nested Path

Columns, sorts, filters, actions, and view sections are separate entries linked to the Data Set. Only the nested path works:

POST   /o/data-set-admin/data-sets/by-external-reference-code/<DS-ERC>/dataSetToDataSet<Child>
GET    /o/data-set-admin/data-sets/by-external-reference-code/<DS-ERC>/dataSetToDataSet<Child>
PATCH  /o/data-set-admin/data-sets/by-external-reference-code/<DS-ERC>/dataSetToDataSet<Child>/<child-erc>
DELETE /o/data-set-admin/data-sets/by-external-reference-code/<DS-ERC>/dataSetToDataSet<Child>/<child-erc>   → 204

The child types are Actions, CardsSections, ClientExtensionFilters, DateFilters, ListSections, SelectionFilters, Sorts, and TableSections. /data-sets/{id}/… works too.

  • The root collections (/o/data-set-admin/table-sections, …) answer 409 "Conflict with postObjectEntry" / getObjectEntriesPage to every call.
  • The references back to the Data Set on a child are r_dataSetToDataSet<Child>_l_dataSetERC / _l_dataSetId, with an _l_ infix.
  • A nested PUT returns 404. …/disassociate fails because the relationship is required. Change a child with PATCH, or remove it with DELETE.
  • Children can also go inline in the create body, as arrays named dataSetToDataSet<Child>: one call builds the whole Data Set.
  • Ordering. The *Order fields on the Data Set (tableSectionsOrder, sortsOrder, …) are empty when built from the UI, but tableSectionsOrder is writable and sets column order: a comma separated list of child ERCs. Unknown ERCs are ignored, and unlisted columns come last.
  • PUT /data-sets/by-external-reference-code/<DS-ERC> with the child arrays inline is an idempotent upsert (verified on 2026.Q3.5): it creates the set when the ERC is new, and otherwise keeps the set's ID and upserts each child by its ERC in place (same child IDs; a PATCHed label and order come back to the body's values). So one PUT per Data Set, safe to run again, is the scripted way to create or restore a definition. A POST of an existing ERC answers 400 "This external reference code is already in use" and changes nothing.

Columns (dataSetToDataSetTableSections)

{
	"fieldName": "title",
	"label_i18n": {
		"en_US": "Title"
	},
	"renderer": "default",
	"rendererType": "internal",
	"sortable": true,
	"type": "string"
}
  • type is required but neither validated nor rendered. The UI writes string, number, integer, or boolean; a Date field becomes string. The renderer decides the display.
  • The renderer keys that ship with the product: default (raw value; a picklist prints as JSON, a date as ISO), label (pill), date, dateTime (local time), boolean (Yes/No), status (workflow badge), link, image, actionLink, and quantitySelector. An unknown or missing key falls back to default. rendererType is "" on columns generated by the UI and "internal" once edited, and both render the same.
  • Dot notation:
    • genre.name / genre.key read a picklist;
    • <relationshipName>.<field> (e.g. authorToBooks.authorName) reads the related entry, and the fragment adds nestedFields itself;
    • the raw FK field shows the numeric ID.
  • Header sort sends sort=<field>:asc|desc and works on direct fields. On a dotted field, the source answers 400 "Unable to sort by property: …", and the table silently keeps its order. So set sortable: false there, as the UI does. On a system object module (e.g. /accounts), only a fixed set of system properties sorts; source the Data Set from a child custom object instead, and show the parent through the reverse relationship's dot notation.
  • Never define two columns on the same fieldName. The table renders one cell per distinct field, and every following column shifts under the wrong header.
  • A column's active: false is ignored at render. Delete the column instead.
  • CSS hooks: cells are .cell-<fieldName>, with dots becoming hyphens (.cell-authorToBooks-authorName), and headers are th.cell-<fieldName>. The markup itself is fixed.
  • The UI generates no column on create. "Add Fields" → "Assign from Data Source" lists the fields, related ones included. Via the API, add every column yourself.

Filters

Give every filter a label: a date filter without label_i18n never appears. Use one filter per field: the UI enforces it, the API does not, and two filters on one field share their value.

Date:

{
	"fieldName": "publicationDate",
	"label_i18n": {
		"en_US": "Published"
	},
	"type": "date"
}

It emits filter=(publicationDate ge …) and (publicationDate le …).

Picklist (dataSetToDataSetSelectionFilters):

{
	"fieldName": "genre",
	"include": true,
	"label_i18n": {
		"en_US": "Genre"
	},
	"multiple": true,
	"preselectedValues": "[]",
	"source": "<LIST_TYPE_DEFINITION_ERC>",
	"sourceType": "OBJECT_PICKLIST"
}

It emits filter=(genre in ('…')), and multiple: false gives radio buttons with eq.

Relationship:

{
	"fieldName": "r_<rel>_c_<parent>ERC",
	"include": true,
	"itemKey": "externalReferenceCode",
	"itemLabel": "<labelField>",
	"label_i18n": {
		"en_US": "Author"
	},
	"multiple": true,
	"preselectedValues": "[]",
	"restApplication": "/c/<parent-plural>",
	"restEndpoint": "/",
	"restSchema": "<ParentName>",
	"source": "/o/c/<parent-plural>",
	"sourceType": "API_REST_APPLICATION"
}

This is the UI's shape: filter on the …ERC twin with itemKey: "externalReferenceCode". The numeric FK with itemKey: "id" also works, since the ID is sent quoted.

  • include: false is not honored. Visitors have a runtime Exclude toggle instead.
  • preselectedValues had no clear effect in testing; one form made the Filter button disappear.

Static parameters. additionalAPIURLParameters (e.g. filter=genre eq 'sf') is joined to the visitor's own filters with and. On 2026.Q3.2 it was static: no native dynamic token mapping, so the known workaround was a globalJS CET that rewrites fetch for URLs carrying liferaydds=true (verified on 2026.Q2.11). On 2026.Q3.5 the parameters take tokens, with LPD-38564 off (verified live): FDSAPIURLBuilder._interpolateTokens replaces, in order, the fragment's apiURLTokenMappings (behind LPD-38564: release, off by default, on 2026.Q3; hidden dev on 2026.Q1 and 2026.Q2, so only feature.flag.LPD-38564=true enables it there), then whatever an FDSAPIURLResolver registered for restApplication + "/" + restSchema returns, then the defaults {scopeKey}, {siteId}, {userExternalReferenceCode}, and {userId}. An unresolved {token} is still sent literally and matches nothing.

  • A filter on a custom object that depends on the current user needs a resolver, since no default token names the user's account or anything beyond the user. An OSGi component does it: @Component(property = "fds.rest.application.key=/c/<plural>/<ObjectName>", service = FDSAPIURLResolver.class), getSchema() returning the object name, and resolve(String baseURL, HttpServletRequest) returning StringUtil.replace(baseURL, "{myToken}", value) (commerce's AccountEntryFDSAPIURLResolver is the pattern). Verified with filter=r_<rel>_accountEntryERC eq '{agentAccountERC}' filled with the signed in user's person account ERC: each user's page fetched only their own rows.
  • Read the result off the rendered page: the fragment's props carry "apiURL" (the endpoint plus nestedFields) and, as a separate key present only when it has a value, "additionalAPIURLParameters" with the tokens already replaced; the browser fetches apiURL + "&" + additionalAPIURLParameters. curl the page as the user and read both keys; the rows themselves are fetched on the client.

Default Sort (dataSetToDataSetSorts)

{
	"default": true,
	"fieldName": "publicationDate",
	"label_i18n": {
		"en_US": "Newest"
	},
	"orderType": "desc"
}

A Sorts entry without label or label_i18n breaks the whole fragment ("An unexpected error occurred."), with NullPointerException: … "labelI18n" is null at CustomFDSSerializer.serializeSorts in the log. Either field is enough, since the other is filled in. The initial request then carries sort=<field>:<orderType>. The UI always writes orderType: "asc"; set desc over the API.

Actions (dataSetToDataSetActions)

{
	"label_i18n": {
		"en_US": "View"
	},
	"permissionKey": "",
	"target": "link",
	"type": "item",
	"url": "/web/<site>/c_<objectname>/{friendlyUrlPath}"
}
  • type: item (per row; a lone row action shows as a button) or creation (a primary button in the management bar).
  • target: link, modal (an iframe modal), sidePanel, and the untested async and headless.
  • url substitutes row fields at the top level: {id}, {friendlyUrlPath}, {externalReferenceCode}, {title}.
  • Link to an entry's default Display Page Template with /web/<site>/c_<objectname>/{friendlyUrlPath}. <objectname> is the object name, lowercased and singular, which is the default friendlyURLSeparator. It needs no ID that is specific to an environment. The alternative /web/<site>/e/<dpt-url>/<classNameId>/{id} also works, but classNameId differs per environment. There is no DPT URL based on an ERC on 2026.Q3.2.
  • permissionKey (e.g. "UPDATE") hides the action from users lacking that permission on the entry (verified with a user holding only VIEW).
  • confirmationMessage_i18n shows a native window.confirm.
  • Order fields. itemActionsOrder / creationActionsOrder stay empty.

List and Card Views

dataSetToDataSetListSections / dataSetToDataSetCardsSections entries are {"fieldName": "<field>", "name": "title" | "description" | "image" | "symbol"}, and dot notation works. With two or more views the fragment shows a view switcher. defaultVisualizationMode chooses the first view; empty or unknown falls back to Cards when a Cards view exists. rendererName on a list section does not apply a custom renderer.

Custom Renderers and Filters (CETs)

  • Cell renderer (fdsCellRenderer CET): the column takes "renderer": "LXC:<cet-key>", "rendererType": "clientExtension". The module's default export is ({value, itemData}) => HTMLElement, where itemData is the whole row, so a cell can depend on sibling fields.
  • Filter (fdsFilter CET): a dataSetToDataSetClientExtensionFilters entry {"clientExtensionEntryERC": "LXC:<cet-key>", "fieldName": "<field no other filter uses>", "label_i18n": {…}}. The default export is an object: descriptionBuilder(selectedData) builds the chip, htmlElementBuilder({filter, setFilter}) builds the panel, and oDataQueryBuilder(selectedData) returns the OData, e.g. an OR across fields that the standard filters cannot express. The LXC: prefix is mandatory. Without it the entry saves, and the render logs No frontend data set filter client extension exists with the external reference code ….
  • Escaping. Escape user values in OData built by hand (replace(/'/g, "''")). Fetch option data with Liferay.Util.fetch.

Place the Data Set Fragment

The fragment references the Data Set by ERC. On a release carrying the LPD-102157 fix (on master, and in a 2026.Q3 hotfix; check the release notes for your patch), the selection is a real item reference that the site initializer tree and the live API can author, and that survives export. Without the fix, only the Page Editor can select the Data Set.

In the tree (layouts/<page>/page-definition.json):

{
	"definition": {
		"fragment": {
			"key": "com.liferay.frontend.data.set.fragment.web.internal.fragment.renderer.FDSFragmentRenderer"
		},
		"fragmentConfig": {
			"itemSelector": {
				"className": "[$OBJECT_DEFINITION_CLASS_NAME:DataSet$]",
				"externalReferenceCode": "<DS-ERC>"
			}
		}
	},
	"type": "Fragment"
}
  • On 2026.Q1 the renderer is still FDSAdminFragmentRenderer (below), and the key above does not exist. Place the Data Set with the Page Editor there; this was not verified on 2026.Q1.
  • The key is the renderer class, with no siteKey. className is the L_DATA_SET definition's class name (DataSet is its name), never the backing object's.
  • A 2025.Q3 export names the old renderer, com.liferay.frontend.data.set.admin.web.internal.fragment.renderer.FDSAdminFragmentRenderer, with an itemSelector carrying classNameId, classPK, itemType, and title. That renderer does not exist on 2026.Q3.5, and a fragment element whose renderer is missing is dropped with its children and no log line. Rewrite it to the key above with the itemSelector that has two keys; the token resolves to the instance's own #XXXX suffix in editablevalues. The Data Set is looked up by ERC on every render, so it may be created after the page is imported, and renaming its ERC takes the fragment off the page without a new import.
  • Over a live PUT of the whole page, the same reference goes under fragmentConfigurationFieldValues.itemSelector = {"type": "Item", "value": {"itemExternalReference": {"className": …, "externalReferenceCode": …}}}, with defaultFragmentKey = the renderer class.
  • Verify on the rendered page, not by a GET.

Order of operations: the definition applies live, so edits show on reload with no redeploy. Placement is page composition: a redeploy of the initializer applies the page again, and live edits made on that page are overwritten. The Data Set only has to exist at render time: the fragment renders nothing until it exists and has at least one view.

Visibility

Only the source entries matter. Guest needs VIEW on the object's entries (rules/guest-access.md) and nothing on the Data Set definition itself. Without it, the fragment shows the standard "No Results Found", and REST returns 200 with no items.

Moving a Data Set Between Environments

POST /data-sets/export-batch exports the definition without its children. Instead:

  1. GET /o/data-set-admin/data-sets/by-external-reference-code/<DS-ERC>?nestedFields=dataSetToDataSetActions,dataSetToDataSetCardsSections,dataSetToDataSetClientExtensionFilters,dataSetToDataSetDateFilters,dataSetToDataSetListSections,dataSetToDataSetSelectionFilters,dataSetToDataSetSorts,dataSetToDataSetTableSections.

  2. Strip what is this instance's, not the definition's: id, dateCreated, dateModified, creator, the HATEOAS actions, friendlyUrlPath and friendlyUrlPath_i18n, objectEntryFolderId and objectEntryFolderExternalReferenceCode, keywords, taxonomyCategoryBriefs, status, scopeId, and on each child the r_…_l_dataSetERC / r_…_l_dataSetId references back to the Data Set and the dataSetToDataSet<Child>ERC parent field. Keep every externalReferenceCode (and label_i18n, defaultLanguageId). All of these are in a 2025.Q3.2 GET body (verified against the database's L_<companyId>_DataSet* tables).

    • An older instance's tableSectionsOrder holds numeric child IDs, not ERCs: a set built in the UI on 2025.Q3.2 stored 47861,47857,… (the TableSections entry IDs). Map each ID to its child's ERC before posting; the target takes ERCs there ("Add Children — Only Through the Nested Path" → "Ordering").
  3. POST it to /data-sets (or /data-sets/batch) as one nested item.

Child ERCs are unique per instance. Importing again on the same instance with unchanged child ERCs fails as a whole (No ObjectEntry exists with the key {r_dataSetToDataSet…_l_dataSetId=…}), so rename them for a copy.

Deleting a Data Set is permanent and cascades to its children (no recycle bin). The same ERC can be created again afterwards.

Not Verified

  • The async and headless action targets.
  • preselectedValues.
  • Using the dataset.everything OAuth scope for real calls: it is accepted at CET deploy time, but no call was made with it.
  • The fetch workaround for dynamic parameters on 2026.Q3.

Success Signal

  • The page shows real rows for the intended audience, and each column shows the expected value.
  • Filters emit the expected OData and narrow the rows.
  • The default sort is applied on load, and actions open the right target.
  • GET …?nestedFields=… lists every child under the chosen ERC.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall