Submit Feedback

Integrating Service Builder Applications with Objects

You can integrate existing Service Builder applications with the Objects framework. Once integrated, your custom entities become unmodifiable system objects, like several of the out-of-the-box Liferay entities (e.g., Users and Accounts). For these object definitions, most configurations cannot be modified from the objects UI. You can change the entry title field, field labels, and the Mandatory setting. You can also add relationships, validations, and actions.

In this example a simple CRUD application based on Service Builder is integrated with Objects. The integration is done by including a SystemObjectDefinitionManager class in its service module.

Get the K3N1 Service Builder Application Code

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip the K3N1 Service Builder project.

curl https://resources.learn.liferay.com/examples/liferay-k3n1.zip -O

unzip liferay-k3n1.zip

From the module root, build and deploy.
```
./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
```
Note

This command is the same as copying the deployed jars to /opt/liferay/osgi/modules on the Docker container.

Confirm the deployment in the Liferay Docker container console.

STARTED com.acme.k3n1.api_1.0.0 [1433]
STARTED com.acme.k3n1.service_1.0.0 [1434]
STARTED com.acme.k3n1.web_1.0.0 [1435]

Open your browser to https://localhost:8080.
Add the K3N1 Portlet to a page. You can find the example portlet under Sample Widgets.
Add an entry with the K3N1 Portlet (e.g., enter k3n1 for the name and k3n1 for the description).
Click Submit.

You can add K3N1 Entries with its portlet.

Add Validation to the K3N1 Entry Object

Add a validation rule so the description and name cannot be equal. This takes capitalization into account, but note that the configured error message does not appear in the UI.

Open the Global Menu () → Control Panel → Objects.
Find the K3N1 Entry object and click on it.
Go to Validations and click Add ().
Enter the label Name must not equal description and click Save.
Click the new validation’s label.
Activate the validation.
Open the Conditions tab and enter name != description.
Enter the error message The name and description fields cannot be the same, then click Save.
Go back to the page with the K3N1 Portlet and add an entry with the same name and description values.

The validation ensures that the entry is not added, but the configured error message isn’t displayed. This is expected, because the system object UI is not under control of the objects framework. Therefore, your portlet’s display code must be adapted to display the error message.

The error message you provided is printed to the Liferay log:
```
2025-02-03 21:49:57.261 ERROR [http-nio-8080-exec-8][PortletServlet:109] Unable to process portlet com_acme_k3n1_web_internal_portlet_K3N1Portlet: com.liferay.portal.kernel.exception.ModelListenerException: com.liferay.object.exception.ObjectValidationRuleEngineException: The name and description fields cannot be the same.
```

Considerations and Limitations

Site-scoped entities cannot be turned into site-scoped objects. The groupId is not passed to the SystemobjectDefinitionManager and its methods, and cannot be used when making service calls.

There are some limitations if your entity does not have REST APIs. Consider using REST Builder to add headless APIs for your entity, then updating the SystemObjectDefinitionManager#getJaxRsApplicationDescriptor method to create a new descriptor for the entity. This opens up additional capabilities, especially when relating your custom entity to other objects.

retun new JaxRsApplicationDescriptor(
   String applicationName, String applicationPath, String path,
   String version);

As in the JSP approach in this code sample, you must create the UI for your application. The objects and page-building features cannot be used to build an application UI for unmodifiable system objects.

Capability: