Integrate External Data
Apps & Automationintegrate-external-dataIntegrate External Data is an Agent Skill for apps & automation published in the liferay/liferay-portal repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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. Maps to "Integration with External Systems and Data" in "Mastering Data Modeling with Liferay Objects".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/liferay/liferay-portal/blob/HEAD/workspaces/clarity-solution-workspace/.workspace-rules/skills/integrate-external-data/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/integrate-external-data, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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-objectswhenstorageType: ext-Serviceis specified
Architecture
Browser / Portal UI
│
▼
Liferay Object (storageType: ext-Service)
│ delegates CRUD
▼
objectEntryManager CET ←→ External REST API / DB
The CET implements an HTTP server that handles five operations Liferay calls:
| Liferay Call | CET Endpoint |
|---|---|
| Create entry | POST / |
| Read entry | GET /<id> |
| Update entry | PUT /<id> |
| Delete entry | DELETE /<id> |
| List entries (paged) | GET / with ?page=&pageSize=&filter= |
Workflow
Define the Object With ext-Service 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 "[email protected]:test"
Use "storageType": "salesforce" for native Salesforce integration, or "storageType": "ext-Service" for the custom CET pattern. For ext-Service, 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:
baseURL: "http://host.docker.internal:<microservice-port>"
name: <Name> Entry Manager
oAuthApplicationHeadlessServerExternalReferenceCode: <workspace-id>-oauth
objectDefinitionRestContextPath: "/o/c/<pluralLabel>"
type: objectEntryManager
Where:
baseURLis the address Liferay uses to reach the microservice (usehost.docker.internalin Docker environments)objectDefinitionRestContextPathmatches the published object's plural label
Implement the Microservice
The microservice must respond to the five endpoints above. Use any stack (Spring Boot, Node.js, Python). The request and response bodies follow the Liferay Headless delivery envelope:
// GET / — list response
{
"actions": {},
"facets": [],
"items": [{...}],
"lastPage": 1,
"page": 1,
"pageSize": 20,
"totalCount": 1
}
// POST / — single item response
{
"id": 123,
"<fieldName>": "<value>",
...
}
Liferay sends the X-Liferay-Token header with each call for the CET to verify authenticity.
Wire OAuth
Call setup-oauth to add the companion oAuthApplicationHeadlessServer 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: Liferay.Headless.Object.everything. 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 declared in baseURL.
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 "[email protected]:test"
# List entries — should return data from the external system
curl \
--silent \
--url "http://localhost:${PORT}/o/c/<pluralLabel>" \
--user "[email protected]: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 baseURL; check network and port |
| 401 from microservice | X-Liferay-Token validation failing; verify the token algorithm |
| CET not linked to object | objectDefinitionRestContextPath must match exactly; redeploy after fix |
| Empty list from Liferay | Microservice returns nonenvelope JSON; wrap in the Headless page envelope |