Mastering Data Modeling with Liferay Objects

Course Overview

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.

Implementing Clarity’s distributor solution includes adding object definitions, configuring them, adding a custom field, and publishing it.

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.

  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 Objects.
    Here you’ll create your data model, starting with your project’s folder.

  3. Click Add (Global Menu) for Object Folders.

  4. For Label, enter Distributor Management and click Create Folder.
    This creates the folder and redirects you to it.

  5. Click Actions (Actions menu) for the folder and select Edit Label and ERC.

    Click Actions for the folder and select Edit Label and ERC.

  6. 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.
  7. Click View in Model Builder.

  8. Click Create New Object.

  9. Enter these details:

    Field Value
    Label Distributor Application
    Plural Label Distributor Applications
    Object Name DistributorApplication


    Create a new custom object.

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

  1. From the Model Builder UI, select the Distributor Application object.
    This displays the object definition's details in the editing side menu.

  2. Click Actions (Actions menu) and select Edit ERC.

    Click Actions, select Edit ERC, enter D4B8_DISTRIBUTOR_APPLICATION, and click Save.

  3. Enter D4B8_DISTRIBUTOR_APPLICATION and click Save.

  4. In the right side panel, configure the object’s scope:

    Field Value
    Scope Company
    Panel Link Applications > Content


    Set the Object's Scope and Panel Link.

    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.

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

    Enable the Allow Users to Save Entries as Draft option.

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.

  1. From the Model Builder UI, click Add Field or Relationship, and select Add Field.

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

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

    Create the Applicant Email Address and Business Name fields.
     

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.

  1. From the Model Builder UI, click Publish.

  2. Check Distributor Application and click Publish Objects.

    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.
  3. Confirm the object is published successfully and click Close.

    Confirm the object is published successfully.

  4. Open the Global Menu (Global Menu), go to the Applications tab, and confirm Distributor Application appears under Content.

    Open the Global Menu, go to the Applications tab, and confirm Distributor Application appears under Content.

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

You can use the REST APIs generated for the Distributor Application object.
 

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.

  1. Go to the Distributor Management folder in the Objects application and click View in Model Builder.

  2. Add an object definition with these details:

    Field Value
    Label Application Evaluation
    Plural Label Application Evaluations
    Object Name ApplicationEvaluation


    Create the Application Evaluation object definition.

  3. Update the object’s ERC to D4B8_APPLICATION_EVALUATION.

  4. 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
  5. Add this field to the object:

    Field Value
    Label Interview Notes
    Field Name interviewNotes
    Type Rich Text
    Enable Entry Translation No
    Mandatory No

    Add the Interview Notes field.
     
  6. 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.

  1. From the Model Builder UI, go to the Default folder (Go to Folder) and select the User object.

    From the Model Builder UI, go to the Default folder and select the User object.

  2. Add this field:

    Field Value
    Label Distributor ID
    Field Name distributorID
    Type Integer
    Mandatory No
    Accept Unique Values Only No

    Select the User object and add the Distributor ID field.

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.

  • Exercise: Adding an Object Definition

  • Exercise: Configuring the Object

  • Exercise: Adding Fields to the Object

  • Exercise: Publishing the Object and Creating Entries

  • Exercise: Implementing the Application Evaluations Object

  • Exercise: Updating the User System Object

  • Conclusion

Loading Knowledge

Capabilities

Product

Education

Contact Us

Connect

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