OpenParable
Skip to content
← Back to skills

Manage Object Logic

Development
manage-object-logic

Manage Object Logic is an Agent Skill for development published in the liferay/liferay-portal repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Add business logic to Liferay Objects via object actions, workflow definitions, and notification templates. Use when the user asks to send a notification on create, trigger an action on update, wire a workflow, or automate any response to object entry lifecycle events. Maps to the Business Logic and Automation section of "Mastering Data Modeling with Liferay Objects".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/liferay/liferay-portal/blob/HEAD/workspaces/clarity-solution-workspace/.workspace-rules/skills/manage-object-logic/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/manage-object-logic, 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.

Manage Object Logic

Attach triggers, conditions, and actions to object definitions. The three extension points are object actions (immediate), Kaleo workflows (multistep approval), and notification templates (user facing messages).

When to Invoke

  • "Send a notification when a Book is created"
  • "Trigger a webhook on order update"
  • "Wire an approval workflow to this object"
  • "Run a Groovy script after an entry is deleted"
  • Called by build-site during the logic phase

Prerequisites

Object definition must already exist and be published (see manage-objects). Client Extension actions require the CET to be deployed first (see scaffold-client-extension).

Workflow

Choose the Trigger

TriggerWhen It Fires
onAfterAddAfter an entry is created
onAfterUpdateAfter an entry is updated
onAfterDeleteAfter an entry is deleted
standaloneOn demand, invoked explicitly by a user or API call

Choose the Action Type

Consult rules/object-actions-catalog.md for the full catalog. Summary:

Action TypePayloadNotes
NotificationTemplate IDSends in app or email notification
addObjectEntryDefinition name + field mapCreates an entry in another object
updateObjectEntryEntry ID + field mapUpdates an entry in the same or another object
WebhookURL + secretHTTP POST to external endpoint
Groovy ScriptScript bodyOnly on self hosted or PaaS; not available on Liferay SaaS
Client ExtensionCET objectAction or workflowAction externalReferenceCodeCalls a deployed microservice

Object Action — Notification

Create a notification template first if one does not exist:

curl \
	--data '{
		"body": {"en_US": "A new [%OBJECT_FIELD_NAME%] was created."},
		"description": "",
		"editorType": "richText",
		"name": "<TemplateName>",
		"objectDefinitionExternalReferenceCode": "<objectERC>",
		"recipientType": "user",
		"subject": {"en_US": "New entry created"},
		"type": "email"
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/notification/v1.0/notification-templates" \
	--user "[email protected]:test"

Save the returned id as <template-id>. Then create the action:

curl \
	--data '{
		"active": true,
		"label": {"en_US": "<ActionLabel>"},
		"name": "<actionName>",
		"objectActionExecutorKey": "notification",
		"objectActionTriggerKey": "onAfterAdd",
		"parameters": {
			"notificationTemplateId": <template-id>
		}
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions/<definition-id>/object-actions" \
	--user "[email protected]:test"

Object Action — Webhook

curl \
	--data '{
		"active": true,
		"label": {"en_US": "<ActionLabel>"},
		"name": "<actionName>",
		"objectActionExecutorKey": "webhook",
		"objectActionTriggerKey": "onAfterAdd",
		"parameters": {
			"secret": "<hmac-secret>",
			"url": "<https://endpoint.example.com/hook>"
		}
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions/<definition-id>/object-actions" \
	--user "[email protected]:test"

Object Action — Client Extension

First deploy the objectAction CET via scaffold-client-extension. Then reference its externalReferenceCode:

curl \
	--data '{
		"active": true,
		"label": {"en_US": "<ActionLabel>"},
		"name": "<actionName>",
		"objectActionExecutorKey": "objectAction",
		"objectActionTriggerKey": "onAfterAdd",
		"parameters": {
			"clientExtensionEntryExternalReferenceCode": "<cet-erc>"
		}
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions/<definition-id>/object-actions" \
	--user "[email protected]:test"

The executor key for a Client Extension action is "objectAction" (not "groovy" — that key is only for the inline Groovy executor in §3a/§3b's sibling pattern). See rules/object-actions-catalog.md.

Kaleo Workflow

Deploy a workflow definition when the object requires multistep review or approval.

curl \
	--data '{
		"active": true,
		"name": "<WorkflowName>",
		"title": {"en_US": "<Workflow Title>"},
		"content": "<escaped XML or JSON workflow definition>"
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-workflow/v1.0/workflow-definitions" \
	--user "[email protected]:test"

After creating, associate the workflow with the object definition. The reliable path is the Control Panel (Objects → <Definition> → Actions → Workflow). There is no workflow-definitions/{id}/assign-to-object endpoint; programmatic association is done through the workflow-definition-links resource (POST /o/headless-admin-workflow/v1.0/workflow-definitions/<id>/workflow-definition-links) — confirm the request body against the OpenAPI spec (get-openapi MCP tool, or GET /o/headless-admin-workflow/v1.0/openapi.json) before scripting it, as the link payload (workflow, class name, type pk) is version sensitive.

Verify Object Actions

curl \
	--silent \
	--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions/<definition-id>/object-actions" \
	--user "[email protected]:test" \
	| jq '[.items[] | {name, objectActionTriggerKey, objectActionExecutorKey, active}]'

Confirm each action is "active": true.

Test the Trigger

Create a test entry and check the expected side effect (email received, webhook payload, other entry created):

curl \
	--data '{"<fieldName>": "test value"}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/c/<pluralLabel>" \
	--user "[email protected]:test"

Common Gotchas

Object Action Refire Loop

onAfterUpdate fires on every REST PATCH — including PATCHes made by the action itself. If your action writes back to the same record via REST, it will loop.

Safe path: call ObjectEntryLocalServiceUtil.updateObjectEntry directly from within the Object Action. Direct service layer calls do not retrigger the Object Action — only REST API calls do. Use this pattern for any script that needs to update the same record it is acting on.

Groovy Output Binding

Object Action Groovy scripts have no out binding. Use bare println to write to catalina.out. Using out.println throws No such property: out.

Diagnostic Action Hygiene

Stale diagnostic Object Actions are a silent data hazard: they continue firing on every matching event after a session ends and can revert data changes at unexpected times — often with no error, just a wrong value in the database. Secondary concern: they accumulate output in catalina.out and interleave with real logs.

Rules:

  • Prefix all diagnostic actions with diag- (e.g., diag-check-balance).
  • Delete all diag- actions before shipping — they are not safe to leave running in any persistent environment.
  • Bulk delete when done: filter by name prefix in Control Panel → Objects → [Object] → Actions, or via the Object Admin REST API.

Type Safety in Groovy

Never pass interpolated strings ("${var}") to Liferay Service APIs. Groovy GStringImpl causes cast exceptions. Always use explicit string concatenation: "" + var.