liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/manage-data-sets
manage-data-sets
VerifiedCreate 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 theLPSprefix). Without it,data-set-adminreturns404. On 2026.Q1 and 2026.Q2 it also needsLPD-34594(Root Object Definitions), and stays off while that one is off. Seefeature-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/…returns404. - The OpenAPI spec is per resource, not at the module root:
/o/data-set-admin/<resource>/openapi.jsonforactions,cards-sections,client-extension-filters,data-sets,date-filters,list-sections,selection-filters,snapshots,sorts, andtable-sections. Read required fields there.data-setsalso exposesbatch,export-batch,permissions, andvalidate.
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
PATCHofexternalReferenceCodecan rename. - The fetch URL is
"/o" + restApplication + restEndpoint. SorestApplicationstarts with/(/c/<plural>), andrestEndpointis/for an object."object-admin"produces/oobject-admin/, a404, 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 inrestEndpoint, or it is dropped. restSchemais not part of the URL. Set it to the object'sname(restSchema: "ObjectEntry"still renders).labelandlistOfItemsPerPageare plain strings. A map or an array is silently stored as its JavatoString()({en_US=…},"[10, 20, 50]") and shown that way in the admin list.label_i18nandobjectDefinitionIddo not exist and are ignored.- Display switches:
active: falsehides 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/validatetakes{"values": {…}}.{}returns a500NPE, and it does not catch alabelwhose 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, …) answer409 "Conflict with postObjectEntry"/getObjectEntriesPageto 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
PUTreturns404.…/disassociatefails because the relationship is required. Change a child withPATCH, or remove it withDELETE. - Children can also go inline in the create body, as arrays named
dataSetToDataSet<Child>: one call builds the whole Data Set. - Ordering. The
*Orderfields on the Data Set (tableSectionsOrder,sortsOrder, …) are empty when built from the UI, buttableSectionsOrderis 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 onePUTper Data Set, safe to run again, is the scripted way to create or restore a definition. APOSTof an existing ERC answers400 "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"
}
typeis required but neither validated nor rendered. The UI writesstring,number,integer, orboolean; a Date field becomesstring. The renderer decides the display.- The
rendererkeys 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, andquantitySelector. An unknown or missing key falls back todefault.rendererTypeis""on columns generated by the UI and"internal"once edited, and both render the same. - Dot notation:
genre.name/genre.keyread a picklist;<relationshipName>.<field>(e.g.authorToBooks.authorName) reads the related entry, and the fragment addsnestedFieldsitself;- the raw FK field shows the numeric ID.
- Header sort sends
sort=<field>:asc|descand works on direct fields. On a dotted field, the source answers400 "Unable to sort by property: …", and the table silently keeps its order. So setsortable: falsethere, 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: falseis ignored at render. Delete the column instead. - CSS hooks: cells are
.cell-<fieldName>, with dots becoming hyphens (.cell-authorToBooks-authorName), and headers areth.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: falseis not honored. Visitors have a runtime Exclude toggle instead.preselectedValueshad 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, andresolve(String baseURL, HttpServletRequest)returningStringUtil.replace(baseURL, "{myToken}", value)(commerce'sAccountEntryFDSAPIURLResolveris the pattern). Verified withfilter=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 plusnestedFields) and, as a separate key present only when it has a value,"additionalAPIURLParameters"with the tokens already replaced; the browser fetchesapiURL + "&" + additionalAPIURLParameters.curlthe 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) orcreation(a primary button in the management bar).target:link,modal(an iframe modal),sidePanel, and the untestedasyncandheadless.urlsubstitutes 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 objectname, lowercased and singular, which is the defaultfriendlyURLSeparator. It needs no ID that is specific to an environment. The alternative/web/<site>/e/<dpt-url>/<classNameId>/{id}also works, butclassNameIddiffers 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 onlyVIEW).confirmationMessage_i18nshows a nativewindow.confirm.- Order fields.
itemActionsOrder/creationActionsOrderstay 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 (
fdsCellRendererCET): the column takes"renderer": "LXC:<cet-key>","rendererType": "clientExtension". The module's default export is({value, itemData}) => HTMLElement, whereitemDatais the whole row, so a cell can depend on sibling fields. - Filter (
fdsFilterCET): adataSetToDataSetClientExtensionFiltersentry{"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, andoDataQueryBuilder(selectedData)returns the OData, e.g. anORacross fields that the standard filters cannot express. TheLXC:prefix is mandatory. Without it the entry saves, and the render logsNo 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 withLiferay.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.classNameis theL_DATA_SETdefinition's class name (DataSetis itsname), 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 anitemSelectorcarryingclassNameId,classPK,itemType, andtitle. 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 theitemSelectorthat has two keys; the token resolves to the instance's own#XXXXsuffix ineditablevalues. 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": …}}}, withdefaultFragmentKey= 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:
-
GET /o/data-set-admin/data-sets/by-external-reference-code/<DS-ERC>?nestedFields=dataSetToDataSetActions,dataSetToDataSetCardsSections,dataSetToDataSetClientExtensionFilters,dataSetToDataSetDateFilters,dataSetToDataSetListSections,dataSetToDataSetSelectionFilters,dataSetToDataSetSorts,dataSetToDataSetTableSections. -
Strip what is this instance's, not the definition's:
id,dateCreated,dateModified,creator, the HATEOASactions,friendlyUrlPathandfriendlyUrlPath_i18n,objectEntryFolderIdandobjectEntryFolderExternalReferenceCode,keywords,taxonomyCategoryBriefs,status,scopeId, and on each child ther_…_l_dataSetERC/r_…_l_dataSetIdreferences back to the Data Set and thedataSetToDataSet<Child>ERCparent field. Keep everyexternalReferenceCode(andlabel_i18n,defaultLanguageId). All of these are in a 2025.Q3.2 GET body (verified against the database'sL_<companyId>_DataSet*tables).- An older instance's
tableSectionsOrderholds numeric child IDs, not ERCs: a set built in the UI on 2025.Q3.2 stored47861,47857,…(theTableSectionsentry IDs). Map each ID to its child's ERC before posting; the target takes ERCs there ("Add Children — Only Through the Nested Path" → "Ordering").
- An older instance's
-
POSTit 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
asyncandheadlessaction targets. preselectedValues.- Using the
dataset.everythingOAuth scope for real calls: it is accepted at CET deploy time, but no call was made with it. - The
fetchworkaround 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |