Adding Data Models for Clarity's Distributor Management App
In this article, you'll begin implementing Clarity’s distributor management app. This process includes adding object definitions, configuring them, adding a custom field, and publishing it. After publishing the object definitions, you can practice creating and managing the object’s entries via the Liferay UI.
Exercise: Adding an Object Definition
Object definitions are blueprints that define the structure and properties of your app's data. Creating an object definition is the first step towards implementing custom data models within Liferay DXP.
Here you’ll add your first object definition for Clarity’s distributor management app 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 Objects.
Here you’ll create your data model, starting with your project’s folder. -
Click Add (
) for Object Folders. -
For Label, enter
Distributor Management
and click Create Folder.
This creates the folder and redirects you to it. -
Click Actions (
) for the folder and select Edit Label and ERC.
-
Enter
D4B8_DISTRIBUTOR_MANAGEMENT
for the External Reference Code and click Save.Now you can begin creating your object definitions.
By default, Liferay assigns a random UUID to object folders and definitions. Using consistent, human-readable ERCs can help when migrating object definitions between environments or using its headless APIs. -
Click View in Model Builder.
-
Click Create New Object.
-
Enter these details:
Field Value Label Distributor Application
Plural Label Distributor Applications
Object Name DistributorApplication
-
Click Save.
Great! You've created a draft object definition that you can now configure.
Exercise: Configuring the Object
Object definitions include configuration options for modifying their general details, behavior, and available features. For example, you can determine how each object's data is scoped, where users can access it in the UI, and whether to maintain a history of entry events.
Here you’ll configure the Distributor Application object.
-
From the Model Builder UI, select the Distributor Application object.
This displays the object definition's details in the editing side menu. -
Click Actions (
) and select Edit ERC.
-
Enter
D4B8_DISTRIBUTOR_APPLICATION
and click Save. -
In the right side panel, configure the object’s scope:
Field Value Scope Company Panel Link Applications > Content
This configures the Distributor Application to scope object data by company, so it can include data from across multiple sites. Also, once published, the object will appear under Content in the Global Menu's Applications tab. -
Enable Allow Users to Save Entries as Draft.
This setting is necessary for Clarity to build the multi-page form they plan to use for the object.
When using the Model Builder UI, Liferay saves changes automatically, so you’re ready to move on to adding a custom field to your object definition.
Exercise: Adding Fields to the Object
When you create object definitions, they include default system fields for important metadata (e.g., createDate
, creator
, externalReferenceCode
, id
, modifiedDate
, status
). You can add various kinds of text, numeric, and date fields to ensure you’re gathering the data necessary for your app.
Here you’ll add some basic text fields to the Distributor Application object.
-
From the Model Builder UI, click Add Field or Relationship, and select Add Field.
-
Enter these values and click Save.
Field Value Label Applicant Name
Field Name applicantName
Type Text Enable Entry Translation No Mandatory Yes Accept Unique Values Only No If the type field does not display any options, please refresh the page.This adds the field to the definition and displays field configuration options in the right side panel.
-
Repeat the above steps to add these fields:
Field Value Label Applicant Email Address
Field Name applicantEmailAddress
Type Text Enable Entry Translation No Mandatory Yes Accept Unique Values Only Yes Field Value Label Business Name
Field Name businessName
Type Text Enable Entry Translation No Mandatory Yes Accept Unique Values Only No
Great! You’ve added three custom fields to the Distributor Application object. In future lessons, you’ll add more fields, but for now you can publish the object definition and practice creating entries.
Exercise: Publishing the Object and Creating Entries
When you publish custom objects, Liferay creates a database table for storing its data entries. Publishing also registers the object with the OSGi framework, integrates it with Liferay's core features (e.g., permissions, workflow, headless), and provides a basic user interface. Users can access the object’s UI according to its scope and panel link.
Here you’ll publish the Distributor Application object.
-
From the Model Builder UI, click Publish.
-
Check Distributor Application and click Publish Objects.
Once you publish an object, you cannot unpublish it, though you can deactivate, edit, or delete the object. -
Confirm the object is published successfully and click Close.
-
Open the Global Menu (
), go to the Applications tab, and confirm Distributor Application appears under Content.
-
Practice creating, updating, and deleting object entries via the Liferay UI before moving forward.
Once created, entries appear in a table that includes the object’s custom fields alongside the id, status, and author system fields by default. You’ll customize this UI in a later lesson.
You can also use the REST APIs generated for Distributor Application during publishing to create, edit, query, and remove entries. These APIs are available at the c/distributorapplications
path. For a complete list of available APIs, see Headless Framework Integration.
Later in this course, you’ll use these APIs to extend out-of-the-box capabilities and design user interfaces with Liferay Objects.
Exercise: Implementing the Application Evaluations Object
Having created and published the Distributor Applications object, you can set up the object definition for storing application evaluations.
Here you’ll create, configure, and publish the Application Evaluations object definition.
-
Go to the Distributor Management folder in the Objects application and click View in Model Builder.
-
Add an object definition with these details:
Field Value Label Application Evaluation
Plural Label Application Evaluations
Object Name ApplicationEvaluation
-
Update the object’s ERC to
D4B8_APPLICATION_EVALUATION
. -
Configure these settings:
Field Value Scope Company Panel Link Applications > Content Show Widget in Page Builder No Enable Categorization of Object Entries Yes Enable Comments in Page Builder Yes Enable Indexed Search No Enable Entry History in Audit Framework No Allow Users to Save Entries as Draft No Enable Entry Translation No -
Add this field to the object:
Field Value Label Interview Notes
Field Name interviewNotes
Type Rich Text Enable Entry Translation No Mandatory No
-
Publish the Application Evaluation object.
Once created, you’re ready to begin adding more fields to Clarity’s distributor management app. But first, Clarity also wants to extend the User system object.
Exercise: Updating the User System Object
Clarity wants to improve how they identify distributors within their user management system. To do this, they want to add a distributorID
field to the User system object.
Here you’ll add this custom field.
-
From the Model Builder UI, go to the Default folder (
) and select the User object.
-
Add this field:
Field Value Label Distributor ID
Field Name distributorID
Type Integer Mandatory No Accept Unique Values Only No
Liferay automatically saves your change, so you can immediately access the new field via headless APIs.
Conclusion
Congratulations, you’ve started implementing Clarity’s distributor management app. Next you’ll review what you’ve learned before moving on to the next module.
Capabilities
Product
Education
Contact Us