Overview This guide walks through creating two OSGi modules in Liferay 7.4 and sharing a Java package between them using the standard API + Implementation pattern. This is the most common and correct approach for exposing reusable services in a Liferay-based architecture. In OSGi, a bundle (module) does not expose its internal packages by default — everything is private unless explicitly exported. To share code between modules, the standard practice is to split functionality into: · An API module — contains interfaces/DTOs and exports the package · A Service (Implementation) module — implements the interface, imports the package, and registers the implementation as an OSGi component/service The consuming module then simply imports the API package and looks up the service using @Reference injection. Step 1: Create the API Module Using Liferay Workspace + Blade CLI, generate a new API module: blade create -t api -p com.sgc.greeting greeting-api This generates a Gradle module unde...
The 2-Step Approver Workflow is a built-in Kaleo workflow definition in Liferay DXP 7.4 that enforces a mandatory two-level human approval process before any submitted content becomes live on the portal. It is the most commonly deployed workflow in enterprise Liferay projects
What is Kaleo Workflow? Kaleo is Liferay's built-in workflow engine implementing BPMN 2.0-style process definitions in XML. It supports States, Tasks, Forks, Joins, and Conditions and integrates natively with Liferay's asset framework - enabling approval workflows for Web Content, Documents, Blogs, and any custom asset type. |
1.1 Why use a 2-Step Approver workflow?
Enforces governance: no content goes live without two independent reviewers
Separates review (editorial) from approval (managerial) responsibilities
Fully auditable: every step is logged with user, timestamp, and comment
Reduces errors and compliance risk in government and enterprise portals
Integrates with Liferay Notifications so all stakeholders are alerted automatically
1.2 Workflow at a Glance
DRAFT / CREATED Initial State |
STEP 1: REVIEW Reviewer Role |
STEP 2: APPROVE Approver Role |
APPROVED / LIVE Terminal State |
Rejection at either step returns the content to the 'created' (Draft) initial state, and the author is notified to make corrections before re-submitting.
2. Workflow States & Transitions
The 2-Step Approver Workflow consists of exactly four nodes: two State nodes and two Task nodes. The diagram below describes each node in detail.
0 Step |
CREATED (Initial State) Actor: System - auto-triggered on content submission This is the entry point of the workflow. When an author submits content for workflow processing, it automatically enters this state. No manual action is needed here. The system immediately fires the transition to the Review task. Transitions: created → review (automatic) |
1 Step |
REVIEW (Task Node - Step 1) Actor: Reviewer Role First human checkpoint. A user assigned to the Reviewer role receives an email notification and sees the task in 'My Workflow Tasks'. The reviewer reads the content, may leave a comment, and either approves (moves to Step 2) or rejects (returns to Draft). Transitions: Approve → approve task | Reject → created (Draft) |
2 Step |
APPROVE (Task Node - Step 2) Actor: Approver Role Second and final human checkpoint. The Approver performs a managerial or compliance review. If satisfied, they approve and the content moves to the terminal state. If not, they reject and the content returns to Draft for the author to revise. Transitions: Approve → approved (Live) | Reject → created (Draft) |
3 Step |
APPROVED (Terminal State) Actor: System -auto-triggered on L2 approval The workflow ends here. The content status changes to Approved and the asset becomes Live/Published on the portal. The system sends a notification email to the original author confirming publication. Transitions: Workflow complete - no further transitions |
2.1 Transition Summary Table
From State / Task |
Transition Name |
Target Node |
Triggered By |
created |
review |
review (task) |
System (automatic) |
review (task) |
approve |
approve (task) |
Reviewer — clicks Approve |
review (task) |
reject |
created (state) |
Reviewer — clicks Reject |
approve (task) |
approved |
approved (state) |
Approver — clicks Approve |
approve (task) |
reject |
created (state) |
Approver — clicks Reject |
3. Kaleo Workflow XML Definition
The complete XML definition for the 2-Step Approver workflow is shown below. This file is imported into Liferay DXP via Control Panel → Process Builder → Workflows → Add (+) → Source tab.
<?xml version="1.0"?> <workflow-definition xmlns="urn:liferay.com:liferay-workflow_7.4.0"> <name>2-Step-Approver</name> <description>Two-step approval workflow</description> <version>1</version>
<!-- Initial State --> <state> <name>created</name> <initial>true</initial> <transitions> <transition> <name>to review</name> <target>review</target> </transition> </transitions> </state>
<!-- Review Task --> <task> <name>review</name> <assignments> <roles> <role> <role-name>Reviewer</role-name> </role> </roles> </assignments> <transitions> <transition> <name>reviewed</name> <target>reviewed</target> </transition> <transition> <name>reject</name> <target>created</target> </transition> </transitions> </task>
<!-- Intermediate State --> <state> <name>reviewed</name> <transitions> <transition> <name>to approve</name> <target>approve</target> </transition> </transitions> </state>
<!-- Approve Task --> <task> <name>approve</name> <assignments> <roles>a <role> <role-name>Approver</role-name> </role> </roles> </assignments> <transitions> <transition> <name>approved</name> <target>approved</target> </transition> <transition> <name>reject</name> <target>created</target> </transition> </transitions> </task>
<!-- Final State --> <state> <name>approved</name> <terminal>true</terminal> </state>
</workflow-definition> |
Important — Role Name Matching The role names inside the XML (e.g., 'Reviewer', 'Approver') must EXACTLY match the Role names created in Liferay Control Panel → Users → Roles. The match is case-sensitive. 'reviewer' and 'Reviewer' are treated as two completely different roles. |
4. Real-World Example
The following is a realistic, end-to-end walkthrough of the 2-Step Approver workflow as used on the any Government Scheme Configurator Portal. This example traces a complete journey: from content submission through both approval steps to publication.
4.1 Scenario Context
Field |
Value |
Portal | Scheme Configurator |
Asset Type |
Web Content Article (Scheme Description) |
Workflow Assigned |
2-Step-Approver |
Content Author |
Ravi Sharma (Content Writer — regular user) |
L1 Reviewer |
Anita Desai (Editor — assigned to Reviewer role) |
L2 Approver |
Suresh Patil (Deputy Secretary — assigned to Approver role) |
Content Title |
PM Kisan Yojana — Updated Eligibility Criteria 2025 |
4.2 Step-by-Step Walkthrough
Step 0 - Author Submits the Content
Ravi Sharma logs in as a regular portal user (not an Administrator) and navigates to:
Site Menu → Content & Data → Web Content → Add → Basic Web Content
Fills in Title: 'PM Kisan Yojana - Updated Eligibility Criteria 2025'
Writes the article body with the updated scheme details
Clicks Submit for Workflow (NOT Save as Draft - the button changes when workflow is active)
Portal Behaviour After submission, the Web Content article status shows 'Pending'. It does NOT appear on the live site. The Kaleo engine creates a new Workflow Instance and fires the automatic transition from 'created' to the 'review' task. An email notification is sent to all users holding the Reviewer role. |
Step 1 - L1 Reviewer (Anita Desai) Reviews the Content
Anita Desai (Reviewer) receives an email notification and logs in to the portal:
Clicks on the User Avatar (top-right) → My Workflow Tasks
Navigates to the 'Assigned to My Roles' tab — sees the pending task
Clicks on 'PM Kisan Yojana — Updated Eligibility Criteria 2025'
Clicks Assign to Me (required before actioning)
Reviews the content for editorial quality, grammar, and factual accuracy
Clicks Actions (⋮) → Approve (or Reject with a comment if needed)
In this example, Anita approves the article. The workflow transitions from 'review' task to 'approve' task. An email is sent to all users holding the Approver role.
What happens on Rejection? If Anita had clicked Reject, the content would return to the 'created' state. Ravi Sharma (the author) would receive an email notification. The article status would show 'Pending' again (back in Draft). Ravi must revise and re-submit for the process to start over from Step 1. |
Step 2 — L2 Approver (Suresh Patil) Final Approval
Suresh Patil (Deputy Secretary -Approver role) receives the email notification and logs in:
Goes to User Avatar → My Workflow Tasks → Assigned to My Roles
Sees the article in the queue - now at the 'approve' task stage
Clicks the task title to open the full content preview
Clicks Assign to Me
Reviews for policy compliance, legal accuracy, and ministerial alignment
Adds a comment: 'Approved -content aligns with current scheme guidelines.'
Clicks Actions (⋮) → Approve
The workflow reaches the 'approved' terminal state. The article status changes from 'Pending' to 'Approved'. .
Author Notification Ravi Sharma (the author) receives an automatic email notification confirming that his article 'PM Kisan Yojana — Updated Eligibility Criteria 2025' has been approved and is now live on the portal. The notification is sent by the Kaleo engine on entry to the terminal 'approved' state. |
5. Configuration - Setup Guide
5.1 Create the Workflow Definition
Login as Portal Administrator
Go to Control Panel → Process Builder
Click Add (+) on the Workflows tab
In the Source tab, paste the XML from Section 3 of this document
Click Save - Liferay validates the schema
Confirm the workflow appears in the list as '2-Step-Approver'
5.2 Create Roles in Liferay
Go to Control Panel → Users → Roles
Click Add (+) → Regular Role → Name: Reviewer → Save
Click Add (+) → Regular Role → Name: Approver → Save
For each role: click the role name → Assignees → Users → Add user
Role Scope Both Reviewer and Approver should be Regular Roles (Portal scope) so they work across all sites. If your project uses Site Roles, the users must be assigned the role on the specific site where the workflow is active. |
5.3 Assign Workflow to Web Content
Navigate to your Site → Content & Data → Web Content
Click Options (gear icon) → Configuration
In the Workflow tab, set Web Content Article → 2-Step-Approver
Click Save
5.4 Verify the Workflow is Active
Log in as a regular (non-admin) user
Submit a new Web Content Article
Confirm status shows 'Pending' (not immediately Live)
Log in as Reviewer - task should appear in My Workflow Tasks
Complete the full approval chain and confirm content goes Live
6. Troubleshooting
Issue |
Root Cause |
Fix |
Task not in My Workflow Tasks |
User not assigned to Reviewer/Approver role |
Control Panel → Roles → add user to correct role |
Email notifications not sent |
SMTP not configured or notification XML missing |
Server Admin → Mail → configure SMTP server |
Workflow does not trigger on submit |
Workflow not assigned to asset type |
Site Config → Workflow → select 2-Step-Approver |
XML import fails with schema error |
Wrong namespace or malformed XML |
Check xmlns value matches Liferay 7.4 namespace |
Admin user bypasses workflow |
By design - Portal Admins skip workflow |
Always test as a non-admin regular user |
Content stuck at Review |
Reviewer has not assigned task to themselves |
Reviewer must click 'Assign to Me' first |
Comments
Post a Comment