Adding Custom Business Logic to Clarity's Distributor Management App

Clarity's distributor management app requires automations to manage workflow states, execute actions, and notify stakeholders of status changes. You've already imported Clarity's object model for this application. Decoupling the application is critical for maximizing performance when handling complex functionalities and business logic. Now, it's time to implement a microservice client extension to offload account creation for Clarity's approved distributor applications.

Exercise: Configuring the Microservice Client Extension

Here, you'll set up the structure for Clarity's microservice client extension handling distributor management actions.

Open a file explorer and navigate to the client-extensions/ folder in your course workspace.
Create a new folder named clarity-distributor-mgmt-action.
You'll use this folder to consolidate the microservice actions for Clarity's distributor management app.

Note: It's considered best practice to group all the components for a specific application within a single client extension project.
From the exercises/module-2/liferay-sample-etc-spring-boot/ folder, move these files to the clarity-distributor-mgmt-action/ folder:
- build.gradle
- Dockerfile
- LCP.json
Now that you've included the basic configuration files for a client extension project leveraging Spring Boot, you can create the client-extension.yaml file.
Within the clarity-distributor-mgmt-action/ folder, create a new file named client-extension.yaml.
Open the file with a text editor or IDE.
Add this code snippet:
```
assemble:
    - fromTask: bootJar
```
This assemble block configures the build process to trigger the bootJar task and include its output (a .jar file) in the resulting LUFFA.
Insert a new line in the client-extension.yaml and add this code snippet:
```
clarity-distributor-mgmt-action-oauth-application-user-agent:
    .serviceAddress: localhost:58081
    .serviceScheme: http
    name: Clarity Distributor Mgmt Action OAuth Application User Agent
    scopes:
        - Liferay.Headless.Admin.User.everything
    type: oAuthApplicationUserAgent
```
This definition block configures an OAuth headless user agent configuration client extension, specifying its name and required scope. This secures communication between the microservice and Liferay DXP.

Note: Including the Liferay.Headless.Admin.User.everything scope is crucial for the client extension to create new accounts for approved distributor users.

Insert a new line and add this code snippet:

clarity-distributor-mgmt-action-object-action-account:
    name: Clarity Distributor Mgmt Action Account
    oAuth2ApplicationExternalReferenceCode: clarity-distributor-mgmt-action-oauth-application-user-agent
    resourcePath: /distributor/mgmt/create-account
    type: objectAction

Save the file.

Great! Now that you've configured the microservice client extension, you'll include the source code for the distributor management app's business logic.

Exercise: Including Clarity's Business Logic in the Client Extension

Here, you'll start creating the source code that includes the business logic for Clarity's distributor management app.

Within the client-extensions/clarity-distributor-mgmt-action/ folder of the course workspace, create these three folders:
- src/
- src/main/
- src/main/resources/
From the exercises/module-2/liferay-sample-etc-spring-boot/src/main/resources/ folder, move these files into the clarity-distributor-mgmt-action/src/main/resources/ folder:
- application.properties
- application-default.properties
Open the application.properties file with a text editor or IDE, and examine its contents.
For this client extension, you'll leverage the spring.config.import property to add additional property files and mark specific files as optional.
Open the application-default.properties file, and examine its contents.

Note: The current content of this file is from the Liferay Sample Workspace. Next, you'll need to update the liferay.oauth.application.external.reference.codes property with the client extension's OAuth 2.0 application reference.
For the liferay.oauth.application.external.reference.codes property, delete the existing reference codes.

Configure the property with the value clarity-distributor-mgmt-action-oauth-application-user-agent.
Your file should resemble this:

[...]
#
# OAuth
#

liferay.oauth.application.external.reference.codes=clarity-distributor-mgmt-action-oauth-application-user-agent

liferay.oauth.urls.excludes=/ready
[...]

Save the file.
In clarity-distributor-mgmt-action/src/main/, create these folders for the Java source files:
- java/
- java/com/
- java/com/clarityvisionsolutions/
- java/com/clarityvisionsolutions/distributor/
- java/com/clarityvisionsolutions/distributor/actions/
Navigate to the clarity-distributor-mgmt-action/src/main/java/com/clarityvisionsolutions/distributor/actions/ folder and create three new files:
- DistributorMgmtSpringBootApplication.java
- ReadyRestController.java
- CreateAccountActionRestController.java

Open the DistributorMgmtSpringBootApplication.java file with a text editor or IDE, and add this code snippet:

package com.clarityvisionsolutions.distributor.mgmt.actions;

import com.liferay.client.extension.util.spring.boot.ClientExtensionUtilSpringBootComponentScan;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Import;

@Import(ClientExtensionUtilSpringBootComponentScan.class)
@SpringBootApplication
public class DistributorMgmtSpringBootApplication {

    public static void main(String[] args) {
        SpringApplication.run(DistributorMgmtSpringBootApplication.class, args);
    }

}

This is a reusable, boilerplate piece of code that annotates the current Java class as a Spring Boot application and imports a Liferay provided class.

Save the file.

Open the ReadyRestController.java file with a text editor or IDE, and add this code snippet:

package com.clarityvisionsolutions.distributor.mgmt.actions;

import com.liferay.client.extension.util.spring.boot.BaseRestController;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RequestMapping("/ready")
@RestController
public class ReadyRestController extends BaseRestController {

    @GetMapping
    public String get() {
        return "READY";
    }

}

This Java class is a boilerplate Spring Boot controller that checks if a service is running and ready to accept requests.

Save the file.

Open the CreateAccountActionRestController.java file with a text editor or IDE, and add this code snippet:

package com.clarityvisionsolutions.distributor.mgmt.actions;

import com.liferay.client.extension.util.spring.boot.BaseRestController;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Invoked when a new user account has been created.
*/
@RequestMapping("/distributor/mgmt/create-account")
@RestController
public class CreateAccountActionRestController extends BaseRestController {

    @Autowired
    public CreateAccountActionRestController(
            UserCreatedRequestQueueManager queueManager) {

        _queueManager = queueManager;
    }

    /**
     * Invoked when a new user account has been created.
     *
     * @param jwt the JWT token
     * @param json the user creation request in JSON format
     * @return the response entity
     * @throws Exception if an error occurs
     */
    @PostMapping
    public ResponseEntity<String> post(
            @AuthenticationPrincipal Jwt jwt, @RequestBody String json)
            throws Exception {

        log(jwt, _log, json);

        // Create the request instance

        UserCreatedRequest request = new UserCreatedRequest(json, jwt);

        // Enqueue the request

        _queueManager.enqueue(request);

        // Return a success response

        return new ResponseEntity<>(json, HttpStatus.OK);
    }

    private static final Log _log = LogFactory.getLog(
            CreateAccountActionRestController.class);

    private final UserCreatedRequestQueueManager _queueManager;

}

This script follows an asynchronous approach for handling business logic for objects. It queues the object action's request, handles it in a different thread named _queueManager, and sends a response back to Liferay.

Note: By not blocking the initial request and instead handling it asynchronously, you ensure performance is not compromised if the object action's logic is slow.

Save the file.
From the exercises/module-2/action-classes/ folder, move these files into the client-extension/clarity-distributor-mgmt-action/src/main/java/com/clarityvisionsolutions/distributor/actions folder:
- TaskExecutorConfig.java
- UserCreatedRequest.java
- UserCreatedRequestProcessorService.java
- UserCreatedRequestQueueManager.java
Note: These files contain the required resources for the object action to perform the asynchronous logic. This code leverages standard Spring Framework classes and libraries that are outside the scope of this course. To learn more, see official Spring Framework documentation.

Now that you've fully configured and populated the microservice client extension, you can deploy it to your Liferay instance.
Open a terminal and navigate to the client-extensions/clarity-distributor-mgmt-action/ folder in your course workspace.
Run this command to build and deploy the client extension:
```
blade gw clean deploy
```

Verify it deploys successfully.

INFO  [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED claritydistributormgmtaction_7.4.13 [1464]

Run this command from the client-extensions/clarity-distributor-mgmt-action/ folder to start the Spring Boot service:
```
blade gw bootRun
```
When the application starts, go to http://localhost:58081/ready. If the application is ready for use, the page displays “READY”.

Great! Now that you've deployed and started the microservice client extension, you can create the object action to trigger the account creation functionality.

Exercise: Adding and Executing the Account Setup Object Action

Here, you'll add an object action that leverages the microservice client extension you deployed in the previous exercise. Then, you'll create a new distributor application and execute the object action to create a new account.

In your Liferay instance, open the Global Menu (), go to the Control Panel tab, and click Objects.
Click the Distributor Application object.
Go to the Actions tab and click Add ().

Enter these values in the Basic Info tab:

Field	Value
Action Label	`Set Up Account`
Action Name	`setUpAccount`
Description	`Create a business account for an approved application.`
Active	Yes

Go to the Action Builder tab and set these values:

Field	Value
Trigger	Standalone
Action	`object-action-executor[function#clarity-distributor-mgmt-action-object-action-account]`
Error Message > Message	`Failed to set up the business account.`

Click Save.
Now that you've created the Set Up Account object action, you can execute it to automatically create distributor accounts.
Open the Global Menu (), go to the Applications tab, and click Distributor Applications.
Click Add () to start creating a new application.

Fill out the fields with these values:

Field	Value
Applicant Name	`Richard Howard`
Applicant Email Address	`richard.howard@howardsvision.com`
Business Name	`Howard's Vision`
Business Website URL	`https://www.howardsvision.com`
Business Phone Number	`555-867-5309`
Business Tax ID Number	`7618231`
Application State	Open

Click Save.
Go back to the Distributor Applications menu.
Click Actions () for the entry you created and select Set Up Account.
Once triggered, the object action will call the Spring Boot application and execute the asynchronous logic you implemented earlier.
Check the terminal window where you executed the bootRun command and see the Spring Boot application's response.
In you Liferay instance, open the Global Menu (), go to the Control Panel tab, and click Accounts.
Verify that the Howard's Vision account was created.
Go to the Users tab and verify the applicant was associated with the account and assigned the Account Administrator role.

Conclusion

Congratulations! You've added custom business logic to Clarity's distributor management app, offloading account creation to a microservice. By leveraging this microservice client extension, Clarity's environment is better equipped to maximize performance when handling complex functionalities.

Next, you'll review what you've learned before moving on to the next module.

Loading Knowledge

Capabilities

View All Capabilities

Product

Education

Connect