Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/integrate-external-data

integrate-external-data

Verified

Back 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-objects when 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> CallCET Receives
List entriesGET <resourcePath>/<objectERC>?companyId=…&languageId=…&page=…&pageSize=…&scopeKey=…&userId=…
Create entryPOST <resourcePath>/<objectERC>
Read entry by ERCGET <resourcePath>/<objectERC>/<entryERC>
Update entry by ERCPUT <resourcePath>/<objectERC>/<entryERC>
Patch entry by ERCGET, then PUT, on the same path
Delete entry by ERCDELETE <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

SymptomCheck
500 on entry creationMicroservice unreachable at the OAuth entry's .serviceAddress; check network and port
401 from microserviceBearer JWT validation failing; see the token details below
400 ObjectDefinitionStorageTypeException on createEnable LPS-135430, and set storageType to function#<cet-erc>
Empty list from LiferayMicroservice 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.

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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall