Implementing Clarity's Approval Workflow
Clarity wants to define a custom state field for tracking an application’s progress and triggering additional business logic. They also want to implement a workflow for reviewing and approving changes made to applications. Currently, all updates to an application are approved automatically, regardless of the selected state. Since Clarity plans to associate additional business logic with the approved and denied states, the workflow must check the applicationState
field and require manager review if one of these values is selected.
Exercise: Adding a Picklist for Application States
Here you’ll add a picklist for storing possible distributor application states as the Clarity Admin user.
-
Sign in as the Clarity Admin user.
-
Username:
admin@clarityvisionsolutions.com
-
Password:
learn
-
-
Open the Global Menu (
), go to the Control Panel tab, and click Picklists. -
Click Add (
). -
For Name, enter
Application States
and click Save. -
Begin editing the picklist.
-
Add these items:
Name Key External Reference Code Open
open
APPLICATION_STATE_OPEN
Under Review
underReview
APPLICATION_STATE_UNDER_REVIEW
Approved
approved
APPLICATION_STATE_APPROVED
Denied
denied
APPLICATION_STATE_DENIED
Withdrawn
withdrawn
APPLICATION_STATE_WITHDRAWN
On Hold
onHold
APPLICATION_STATE_ON_HOLD
-
Set the picklist’s ERC to
D4B8_APPLICATION_STATES
.
-
Click Save.
Now that you’ve added the picklist, you can use it in object definitions to define a state field.
Exercise: Adding the Application State Field
State fields enable you to track an object entry's status throughout its lifecycle. Here you’ll use the picklist to define a state field in the Distributor Application object.
-
Open the Global Menu (
), go to the Control Panel tab, and click Objects. -
Go to the Distributor Management folder and begin editing the Distributor Application object.
-
Go to the Fields tab and click Add (
). -
Enter these details:
Field Value Label Application State
Field Name applicationState
Type Picklist Picklist Application States Mandatory Yes Mark as State Yes Default Value Open
- Click Save.
This adds a state field to the Distributor Application object. This field uses the Application States picklist to define its possible values. Once created, you can determine valid state transitions.
Exercise: Managing State Flow
By themselves, state fields don’t enforce any rule for state transitions. But you can define custom transition rules in the object’s State Manager tab. Here you’ll determine valid transitions for the state field.
-
While editing the Distributor Application object, go to the State Manager tab.
-
Click Application State.
-
Set these flow values:
Field Value Open Under Review, Withdrawn Under Review Approved, Denied, Withdrawn, On Hold Approved Under Review Denied Under Review Withdrawn Open On Hold Open, Under Review -
Click Save.
This configuration ensures that updates to the state field follow the defined process, adhering to Clarity's business processes. You can now test it.
Exercise: Testing the Application State Field
To practice using the application state field, you must first add the field to the object’s layout and view. Here you’ll make these changes before setting your state flow.
Adding the State Field to Your Layout
-
While editing the Distributor Application object, go to the Layouts tab and begin editing Basic Layout.
-
Go to the Layout tab.
-
Click Add Field for the General Details block.
-
Select Application State, select the Two Column layout, and click Save.
-
Click Save for the layout.
Adding the State Field to Your View
-
Go to the Views tab and begin editing Basic View.
-
Go to the View Builder tab.
-
Click Add (
), select the Application State field, and click Save.
-
Drag and drop fields to reorder them:
-
ID
-
Applicant Name
-
Business Name
-
Create Date
-
Application State
-
Status
-
-
Click Save for the view.
Using the State Field
-
Open the Global Menu (
), go to the Applications tab, and click Distributor Applications. -
Begin editing an existing application.
Notice that even though the entry was created before the state field was added, it’s set to the default value. -
Update the state field to On Hold and click Save.
Notice that available options depend on the field’s current value. -
Begin editing the same application.
-
Update the state field to Under Review and click Save.
Notice that the options are different.
Now that you’ve added a state field, Clarity wants to add a workflow process that requires review when users update the field to ‘approved' or ‘denied’.
Exercise: Setting Up the Workflow Action Client Extension
The course workspace includes a pre-built workflow action client extension. This Spring Boot microservice assists in managing status transitions based on an entry's state field. Here you'll set it up and examine how it works.
-
Open a terminal window and go to this folder in the course workspace:
liferay-course-objects/client-extensions/liferay-clarity-etc-spring-boot/
. -
Run this command to deploy the microservice client extension.
-
Verify it deploys successfully.
-
Run this command to start the Spring Boot service:
-
When the application starts, go to http://localhost:58081/ready. If the application is ready for use, the page says “READY.”
This Spring Boot project includes two microservice client extensions: a workflow action and an object action. For now, you'll focus on the workflow action.
Examining the Client Extension Code
This client extension defines a REST controller (WorkflowActionApplicationRestController
) that handles workflow actions for distributor applications. Essentially, it automates the process of moving an application through its workflow based on the entry’s applicationState
value.
This microservice uses a JSON Web Token (JWT) for authentication and a JSON payload with the application's state and transition URL. By reading the application's state field, this action determines the correct workflow transition:
-
For ‘approved’ or ‘denied’ states, it transitions the application to a ‘review’ workflow node.
-
For other states, it transitions the application to an ‘auto-approve’ workflow node.
Finally, it uses a WebClient to send an authenticated HTTP POST request to the transition URL. This automates the process of moving applications through different workflow stages within Liferay while ensuring significant state changes are reviewed.
With the workflow action deployed and ready, you can use it in Clarity’s workflow definition.
Exercise: Setting Up the Workflow Definition
Workflow definitions in Liferay determine the nodes, transitions, and actions of your approval workflows. Here you'll deploy a workflow definition that uses the microservice client extension you deployed in the previous exercise.
-
Open a new terminal window and go to this folder in the course workspace:
liferay-course-objects/client-extensions/liferay-clarity-batch-create-workflow-definition/
. -
Run this command to deploy the batch client extension.
You can now enable the workflow for the Distributor Application object.
-
Verify it deploys successfully.
-
Open the Global Menu (
), go to the Applications tab, and click Process Builder. -
Confirm Distribution Manager Approval appears.
-
Go to the Configuration tab.
-
Click Edit for Distributor Application and select Distribution Manager Approval.
-
Click Save.
This enables the workflow for the Distributor Application object. Now, any changes made to distributor applications must go through its approval process.
Examining the Workflow Definition
The provided definition includes five nodes: Start, Machine Review, Manager Review, Update, and Approved.
The Machine Review node uses the workflow action client extension to check each application’s state field. If the value equals approved
or denied
, the application is directed to the Manager Review node for approval by a Business Development Manager. Otherwise, the Machine Review node automatically directs the application to the Approved node.
Exercise: Testing Clarity’s Workflow
Now that you've enabled the workflow for the Distributor Application object, it's time to test the process and ensure it functions as expected.
-
Open the Global Menu (
), go to the Applications tab, and click Distributor Applications. -
Click Add (
), fill out the form, and click Save.
-
Return to the Distributor Applications overview page and verify the entry’s workflow status is ‘Approved’.
-
Begin editing the entry, set its state field to Under Review, and click Save.
-
Verify the entry’s workflow status is ‘Approved’.
-
Begin editing the entry, set its state field to Approved, and click Save.
-
Verify the entry’s workflow status is ‘Pending’.
-
Open the Personal Menu, go to Notifications, and click the new workflow notification.
-
Assign the review task to yourself and approve it.
-
Verify the entry’s workflow status is ‘Approved’.
Conclusion
Great! You’ve set up an approval workflow that requires manager review for resolved applications. Next, you’ll learn how to use object actions to implement business logic.
Capabilities
Product
Education
Contact Us