Understanding Microservice Client Extensions

Applications often need to integrate with external systems, react to platform events, or extend platform behaviors without modifying the platform itself. When custom logic is tightly coupled to Liferay's internal services, solutions are harder to maintain, slower to scale, and difficult to upgrade. Microservice client extensions are decoupled, standalone applications that communicate with Liferay through OAuth 2.0-secured headless APIs. This is particularly essential for cloud-native applications and businesses requiring rapid iteration and independent scaling for their services.

Microservice client extensions execute actions in response to events within the Liferay instance.

Common scenarios for microservice client extensions include:

Creating communication channels between Liferay and external systems.
Offloading tasks from Liferay to a secondary system.
Prioritizing a loosely coupled architectural design.
Empowering independent teams to maintain a cohesive overall strategy while managing their own build and release processes.

In this lesson, you'll learn how microservice client extensions work, the types Liferay provides, and the considerations for using them effectively.

Integration Using Microservice Client Extensions

Microservice client extensions integrate through REST endpoints, which empowers you to consume external services directly within Liferay without implementing additional portal logic. This provides a distinct advantage over traditional OSGi modules that tightly couple with platform components.

These are the essential components of a microservice client extension:

A descriptor client-extension.yaml file for the extension.
The elements that make up the microservice.

The Liferay Sample Workspace provides example microservice client extension projects using NodeJS and Spring Boot.

The Liferay Sample Workspace provides example microservice client extension projects using Node.js and Spring Boot, which you'll explore later in this course. Node.js and Spring Boot are starting points only; the REST-based communication of microservice client extensions empowers you to use any technology that can produce headless API requests and consume the responses, with adaptability to follow best practices for that specific technology.

Types of Microservice Client Extension

Microservice client extensions include several types that handle business logic, manage data, integrate third-party systems, and perform other data-driven actions, depending on the type. These are the primary types:

Type	YAML Definition	Example Use Case
Object Action	`type: objectAction`	Call external APIs when a custom object is created to synchronize the data with another system, such as a CRM or ERP, or trigger some internal business logic.
Object Validation	`type: objectValidationRule`	When data is entered into an object field, implement your own custom check for validation, preventing the entry to be saved in case the validation fails.
Workflow Action	`type: workflowAction`	Run external checks verifying with third party systems when a workflow reaches an approval stage.
Notification Type	`type: notificationType`	Send personalized emails or SMS notifications when users complete object forms, integrating with third party messaging platforms to handle the communication.
Captcha	`type: captcha`	If you want to integrate a different third-party CAPTCHA provider from the ones natively supported OOTB by Liferay, to verify a human user is accessing your site and not a bot or malicious code attacking it you must use a CAPTCHA client extension.

With the exception of cron jobs, microservices share the same basic execution behavior. When the extension is deployed, Liferay processes the package and registers a new client extension. These microservice extensions then hook into a Liferay process and offload tasks to the specified endpoint.

Object Action and Object Validation client extensions are the decoupled equivalent of OSGi Model Listeners. Where OSGi Model Listeners react to model-level events through internal Liferay APIs, Object Action and Object Validation client extensions achieve similar results while keeping logic external.

These are some typical use cases where microservice client extensions are ideal:

Enterprise System Integration: Integrating with CRM or ERP systems where sensitive data and strong authentication are essential.
Data Processing: Handling data-intensive tasks that require secure and controlled access.
Microservice Architectures: Managing integrations with multiple microservices that require varying levels of access.

Examples: Object Action

Consider a scenario where a system must notify users if their account is accessed from an unusual location. This can be implemented with an Object Action using the On After Login trigger. After a user signs in successfully, Liferay invokes the configured Object Action, which sends a payload to a microservice client extension. The microservice compares the request's IP address against the user's login history. If the location is unfamiliar, the microservice calls back to Liferay to generate a security notification. Because the On After Login trigger is a post-login event, it does not intercept or block authentication. The user's session is unaffected, and the microservice executes its logic in the background.

Alternatively, Object Actions can be configured as Standalone, meaning they run only when invoked manually rather than by an automatic system trigger. Standalone actions are asynchronous and always return HTTP 204 No Content, making them ideal for fire-and-forget workflows. For example, a user could click a button to trigger a background data sync; the UI instantly registers the 204 success, allowing the user to keep working while the microservice processes the payload externally.

Example: Object Validation

Consider a scenario where an application requires a valid business tax ID before an entry can be saved. This can be enforced by configuring an Object Validation rule that calls a microservice client extension to verify the submitted ID against an external registry. If the validation fails, the microservice returns an error message, and Liferay blocks the entry from being created.

Because Object Validation is synchronous, it is best suited for lightweight, fast checks like format validation or quick external lookups. For checks involving slower external services or complex approval logic, a workflow is a better choice. Workflows decouple the data submission from the validation latency and provide more control over the overall lifecycle.

Benefits of Microservice Client Extensions

Microservice client extensions offer several benefits for integrating and extending Liferay DXP with external systems:

Flexible Integration: Integrate with any system or service, regardless of underlying technology, as long as it supports REST.
Decoupled Systems: Reduce dependencies by facilitating loose coupling between Liferay and external systems.
Improved Maintainability: Lower total cost of ownership and improve maintainability by enabling independent teams to work on separate microservices, supporting parallel development and efficient resource allocation.
Software and Asset Reuse: Use existing systems and services within your current infrastructure to improve development time.

Considerations for Leveraging Microservices

Before deciding whether microservice client extensions are right for a specific use case, consider these important factors. These extensions are backend services with no frontend or visual element added to Liferay. Similarly, microservice client extensions are only registered through deployment and cannot be manually added through Liferay's administration UI. Microservice client extensions are primarily suited for offloading tasks to separate systems and are not always ideal for other integration scenarios.

Troubleshooting Microservice Client Extensions

When working with microservice client extensions, keep these specific troubleshooting suggestions in mind:

Replace hard-coded paths and only reference injected route information.
If you observe issues related to scopes, redeploy the client extension as a first troubleshooting step.
Avoid creating excessive API calls. Too many calls will exhaust the system's available threads, causing performance issues. Connection pooling and rate limiting help prevent thread exhaustion. GraphQL queries are another approach for resolving such issues.

Clarity's Microservice Client Extensions

Clarity plans to use microservices to offload distributor management account creation. They've created a workflow managing the approval process and configured an object action to trigger on application approval. When its trigger fires during runtime, the action invokes the registered extension's REST endpoint and waits for a response. The microservice queues the object action's request, processes it, and sends a response back to Liferay to create a new account.

Clarity plans to leverage microservice client extensions to offload account creation for approved distributors.

With a microservice client extension, Clarity can independently develop components of the approval process using diverse technologies suited to specific needs. These pieces are then orchestrated to achieve the overall objective, while their loose coupling ensures easy modification and scalability.

Conclusion

Microservice client extensions empower flexible, agile development through standards-based headless APIs. These extensions act as a bridge between Liferay and external microservices, handling business logic, managing data, and integrating third-party systems.

Next, you'll explore how scheduled microservices automate background tasks on a defined frequency.