liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/integrate-external-data
integrate-external-data
VerifiedBack a Liferay Object with an external data source using the Object Entry Manager CET pattern. Use when the user wants to connect an object to an external REST API, database, or SaaS system rather than storing data in Liferay's own database.
Integrate External Data
The Object Entry Manager pattern lets Liferay Objects delegate storage and retrieval to a microservice. Object CRUD calls proxy to the external service; Liferay UI, workflows, and permissions all work transparently.
When to Invoke
- "Connect this object to our Salesforce data"
- "Back this object with an external REST API"
- "I want Liferay to display records from an external system"
- Called by
manage-objectswhen an object needs external storage
Architecture
Browser / Portal UI
│
▼
Liferay Object (storageType: function#<cet-erc>)
│ delegates CRUD
▼
objectEntryManager CET ←→ External REST API / DB
The CET implements an HTTP server that handles the calls below. <objectERC> is the object definition's external reference code, and <entryERC> is the entry's:
/o/c/<plural> Call | CET Receives |
|---|---|
| List entries | GET <resourcePath>/<objectERC>?companyId=…&languageId=…&page=…&pageSize=…&scopeKey=…&userId=… |
| Create entry | POST <resourcePath>/<objectERC> |
| Read entry by ERC | GET <resourcePath>/<objectERC>/<entryERC> |
| Update entry by ERC | PUT <resourcePath>/<objectERC>/<entryERC> |
| Patch entry by ERC | GET, then PUT, on the same path |
| Delete entry by ERC | DELETE <resourcePath>/<objectERC>/<entryERC> |
Entries are addressed by ERC only. A call by numeric ID, such as GET /o/c/<plural>/<id>, returns 400 UnsupportedOperationException and never reaches the CET. Verified on 2026.Q1.
POST and PUT bodies are wrapped: {"companyId": …, "languageId": …, "objectEntry": {…}, "scopeKey": …, "userId": …}. Read the fields from objectEntry. Its externalReferenceCode is null on a PUT, so take the ERC from the path, and null on a POST without one, so generate it. Verified on 2026.Q1.
Workflow
Define the Object With External Storage
curl \
--data '{
"label": {"en_US": "<Label>"},
"name": "<Name>",
"pluralLabel": {"en_US": "<PluralLabel>"},
"scope": "company",
"storageType": "salesforce"
}' \
--header "Content-Type: application/json" \
--request POST \
--silent \
--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions" \
--user "test@liferay.com:test"
Use "storageType": "salesforce" for native Salesforce integration, or "storageType": "function#<cet-erc>" for the custom CET pattern, where <cet-erc> is the key of the objectEntryManager entry. Any storageType sent over REST needs feature flag LPS-135430, which is off by default. Without it, the create returns 400 ObjectDefinitionStorageTypeException for every value. For the CET pattern, proceed to Scaffold the objectEntryManager CET.
Scaffold the objectEntryManager CET
Call scaffold-client-extension with type objectEntryManager. The CET is a microservice that Liferay calls inbound.
Minimum client-extension.yaml entry:
<workspace-id>-entry-manager:
name: <Name> Entry Manager
oAuth2ApplicationExternalReferenceCode: <workspace-id>-oauth
resourcePath: /object/entry/manager
type: objectEntryManager
The entry takes only these keys. Liferay reaches the microservice at the OAuth entry's .serviceAddress plus resourcePath. liferay-sample-etc-spring-boot on GitHub shows a working example. In Docker, set .serviceAddress to host.docker.internal:<port>.
Implement the Microservice
The microservice must answer the calls above. Use any stack (Spring Boot, Node.js, Python). The request bodies are wrapped as described above, and the responses follow the Liferay Headless delivery envelope:
// GET <resourcePath>/<objectERC> — list response
{
"actions": {},
"facets": [],
"items": [{...}],
"lastPage": 1,
"page": 1,
"pageSize": 20,
"totalCount": 1
}
// GET, POST, or PUT on a single entry — single item response
{
"<fieldName>": "<value>",
"externalReferenceCode": "<entryERC>",
...
}
Liferay authenticates each call with an Authorization: Bearer <JWT> header, issued for the CET's OAuth application. Verify it as liferay-sample-etc-spring-boot does. Liferay sends no other token header. Verified on 2026.Q1.
Wire OAuth
Call setup-oauth to add the companion oAuthApplicationUserAgent entry to client-extension.yaml. The entry manager needs scopes to call back into Liferay when it must resolve related objects or write audit entries.
Minimum scope: the per object scope (c_<name>.everything) for each object it calls back into; Liferay.Headless.Object.everything does not grant /o/c (see rules/oauth-scopes.md). Add Liferay.Object.Admin.REST.everything if the entry manager needs to inspect or modify the object definition itself.
Deploy
Run deploy-and-verify from the client extension root. Then start the microservice separately on the port in the OAuth entry's .serviceAddress.
Verify
# Create an entry — should proxy to the external system
curl \
--data '{"<fieldName>": "test"}' \
--header "Content-Type: application/json" \
--request POST \
--silent \
--url "http://localhost:${PORT}/o/c/<pluralLabel>" \
--user "test@liferay.com:test"
# List entries — should return data from the external system
curl \
--silent \
--url "http://localhost:${PORT}/o/c/<pluralLabel>" \
--user "test@liferay.com:test"
Check the microservice logs to confirm Liferay forwarded the calls. If entries appear empty, the microservice's list response format may not match the expected envelope (see Implement the Microservice).
Troubleshoot
| Symptom | Check |
|---|---|
| 500 on entry creation | Microservice unreachable at the OAuth entry's .serviceAddress; check network and port |
| 401 from microservice | Bearer JWT validation failing; see the token details below |
400 ObjectDefinitionStorageTypeException on create | Enable LPS-135430, and set storageType to function#<cet-erc> |
| Empty list from Liferay | Microservice returns nonenvelope JSON; wrap in the Headless page envelope |
The token is RS256, signed by the single key at /o/oauth2/jwks, and carries no kid, so do not require a kid match. Its aud and client_id match the .oauth2.user.agent.audience and .oauth2.user.agent.client.id routes. Verified on 2026.Q1.
Success Signal
TODO / inferred — verify against a running bundle. The ### Verify step above (POST then GET on /o/c/<pluralLabel> return external system records; microservice logs show forwarded CRUD calls) is the observable completion check; confirm on a live bundle.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |