Mastering Data Modeling with Liferay Objects

Course Overview

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.

  1. Sign in as the Clarity Admin user.

    • Username: admin@clarityvisionsolutions.com

    • Password: learn

  2. Open the Global Menu (Global Menu), go to the Control Panel tab, and click Picklists.

  3. Click Add (Add).

  4. For Name, enter Application States and click Save.

  5. Begin editing the picklist.

  6. 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

    Edit the picklist.
     
  7. Set the picklist’s ERC to D4B8_APPLICATION_STATES.

    Edit the picklist.

  8. 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.

  1. Open the Global Menu (Global Menu), go to the Control Panel tab, and click Objects.

  2. Go to the Distributor Management folder and begin editing the Distributor Application object.

  3. Go to the Fields tab and click Add (Add).

  4. 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

    Add the applications state field.
  5. 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.

  1. While editing the Distributor Application object, go to the State Manager tab.

  2. Click Application State.

  3. 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
     

    Set these flow values in the Application State setting.

  4. 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

  1. While editing the Distributor Application object, go to the Layouts tab and begin editing Basic Layout.

  2. Go to the Layout tab.

  3. Click Add Field for the General Details block.

  4. Select Application State, select the Two Column layout, and click Save.

    Add the State Field to Your Layout.

  5. Click Save for the layout.

Adding the State Field to Your View

  1. Go to the Views tab and begin editing Basic View.

  2. Go to the View Builder tab.

  3. Click Add (Add), select the Application State field, and click Save.

    Add the State Field to Your View.

  4. Drag and drop fields to reorder them:

    1. ID

    2. Applicant Name

    3. Business Name

    4. Create Date

    5. Application State

    6. Status

  5. Click Save for the view.

Using the State Field

  1. Open the Global Menu (Global Menu), go to the Applications tab, and click Distributor Applications.

  2. 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.

  3. Update the state field to On Hold and click Save.
    Notice that available options depend on the field’s current value.

  4. Begin editing the same application.

  5. 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.

  1. Open a terminal window and go to this folder in the course workspace: liferay-course-objects/client-extensions/liferay-clarity-etc-spring-boot/.

  2. Run this command to deploy the microservice client extension.

    blade gw clean deploy
  3. Verify it deploys successfully.

    2024-12-15 01:16:09.157 INFO  [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED liferayclarityetcspringboot_7.4.13 [1489]
  4. Run this command to start the Spring Boot service:

    blade gw bootRun
  5. 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.

@RequestMapping("/workflow/action/application")
@RestController
public class WorkflowActionApplicationRestController
	extends BaseRestController {
	@PostMapping
	public ResponseEntity post(
			@AuthenticationPrincipal Jwt jwt, @RequestBody String json)
		throws Exception {
		log(jwt, _log, json);
		WebClient.Builder builder = WebClient.builder();
		WebClient webClient = builder.baseUrl(
			lxcDXPServerProtocol + "://" + lxcDXPMainDomain
		).defaultHeader(
			HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE
		).defaultHeader(
			HttpHeaders.AUTHORIZATION, "Bearer " + jwt.getTokenValue()
		).defaultHeader(
			HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE
		).build();
		JSONObject jsonObject = new JSONObject(json);
		webClient.post(
		).uri(
			jsonObject.getString("transitionURL")
		).bodyValue(
			"{\"transitionName\": \"" + _getTransitionName(jsonObject) + "\"}"
		).exchangeToMono(
			clientResponse -> {
				HttpStatus httpStatus = clientResponse.statusCode();
				if (httpStatus.is2xxSuccessful()) {
					return clientResponse.bodyToMono(String.class);
				}
				else if (httpStatus.is4xxClientError()) {
					return Mono.just(httpStatus.getReasonPhrase());
				}
				Mono mono =
					clientResponse.createException();
				return mono.flatMap(Mono::error);
			}
		).doOnNext(
			output -> {
				if (_log.isInfoEnabled()) {
					_log.info("Output: " + output);
				}
			}
		).subscribe();
		return new ResponseEntity<>(json, HttpStatus.OK);
	}
	private String _getTransitionName(JSONObject jsonObject) {
		JSONObject entryDTOJSONObject = jsonObject.getJSONObject("entryDTO");
		JSONObject applicationStateJSONObject =
			entryDTOJSONObject.getJSONObject("applicationState");
		String applicationStateKey = applicationStateJSONObject.getString(
			"key");
		if (Objects.equals(applicationStateKey, "approved") ||
			Objects.equals(applicationStateKey, "denied")) {
			return "review";
		}
		return "auto-approve";
	}
	private static final Log _log = LogFactory.getLog(
		WorkflowActionApplicationRestController.class);
}

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.

  1. 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/ .

  2. Run this command to deploy the batch client extension.

    blade gw clean deploy

    You can now enable the workflow for the Distributor Application object.

  3. Verify it deploys successfully.

    2024-12-15 01:21:56.006 INFO  [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED liferayclaritybatchcreateworkflowdefinition_7.4.13 [1490]
    
  4. Open the Global Menu (Global Menu), go to the Applications tab, and click Process Builder.

  5. Confirm Distribution Manager Approval appears.
    Confirm Distribution Manager Approval appears.

  6. Go to the Configuration tab.

  7. Click Edit for Distributor Application and select Distribution Manager Approval.
    Click Edit for Distributor Application and select Distribution Manager Approval.

  8. 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.

Examining the Workflow Definition.

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.

  1. Open the Global Menu (Global Menu), go to the Applications tab, and click Distributor Applications.

  2. Click Add (Ad), fill out the form, and click Save.
    Fill out the form and click Save.

  3. Return to the Distributor Applications overview page and verify the entry’s workflow status is ‘Approved’.
    Verify the entry’s workflow status is ‘Approved’.

  4. Begin editing the entry, set its state field to Under Review, and click Save.

  5. Verify the entry’s workflow status is ‘Approved’.

  6. Begin editing the entry, set its state field to Approved, and click Save.

  7. Verify the entry’s workflow status is ‘Pending’.
    Verify the entry’s workflow status is ‘Pending’.

  8. Open the Personal Menu, go to Notifications, and click the new workflow notification.

  9. Assign the review task to yourself and approve it.

  10. 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.

  • Exercise: Adding a Picklist for Application States

  • Exercise: Adding the Application State Field

  • Exercise: Managing State Flow

  • Exercise: Testing the Application State Field

  • Exercise: Setting Up the Workflow Action Client Extension

  • Exercise: Setting Up the Workflow Definition

  • Exercise: Testing Clarity’s Workflow

  • Conclusion

Loading Knowledge

Capabilities

Product

Education

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy