Migrating Clarity's Data Between Environments

The first step towards promoting applications between Liferay environments is to migrate the data model and its resources, including any dependencies. Clarity’s developers successfully created their distributor management app objects in a development environment and exported these definitions. Now, they are ready to migrate the models to a pre-production environment.

In these exercises, you'll learn how to create batch payloads from exported data and leverage batch client extensions to migrate data models between environments.

Exercise: Preparing Clarity’s Distributor Management App Payload

Here, you'll package the distributor management app’s exported resources into a client extension project and create a batch payload from the object definition file.

Open a file explorer and navigate to the exercises/module-1/ folder in your course workspace.
Rename the liferay-sample-batch folder to clarity-distributor-mgmt-batch.

The liferay-sample-batch client extension was downloaded from the Liferay Sample Workspace, a collection of client extension implementation examples. Liferay recommends using these sample projects as starting points for your own client extension projects.
Within the clarity-distributor-mgmt-batch/batch/ folder, delete the existing .json files.
From the previous module-1/ folder, move these files into the clarity-distributor-mgmt-batch/batch/ folder:
- 00-list-type-definition.batch-engine-data.json
- 02-user-role.batch-engine-data.json
- 03-workflow-definition.batch-engine-data.json
- Object_Definitions.json
These files contain all the resources for Clarity’s Distributor Management app: the picklists, user roles, workflow, and the object definitions.
Navigate to the clarity-distributor-mgmt-batch/batch/ folder.
Rename the Object_Definitions.json file to 01-object-definition.batch-engine-data.json.
This puts the object definition batch file in the second deployment position.
It’s best practice to include a numeric prefix to each file name to determine the order in which they're imported upon deployment. This is useful when subsequent files require pre-populated dependencies from other files.
Open the 01-object-definition.batch-engine-data.json file with a text editor or IDE.

Add this configuration block within the first opening curly brace ({), prior to the items block:

"configuration": {
	"className": "com.liferay.object.admin.rest.dto.v1_0.ObjectDefinition",
	"parameters": {
		"containsHeaders": "true",
		"createStrategy": "UPSERT",
		"onErrorFail": "ON_ERROR_FAIL",
		"updateStrategy": "UPDATE"
	},
	"taskItemDelegateName": "DEFAULT"
},

This defines the batch payload’s configuration and specifies the object definitions as the data block.

Your file should resemble this:

{
    "configuration": {
        "className": "com.liferay.object.admin.rest.dto.v1_0.ObjectDefinition",
        "parameters": {
            "containsHeaders": "true",
            "createStrategy": "UPSERT",
            "onErrorFail": "ON_ERROR_FAIL",
            "updateStrategy": "UPDATE"
        },
        "taskItemDelegateName": "DEFAULT"
    },
    "items": [
        {
            "active": true,
			"defaultLanguageId": "en_US",
			"enableCategorization": true,
			"enableIndexSearch": true,
			"enableObjectEntryDraft": true,
			"externalReferenceCode": "D4B8_DISTRIBUTOR_APPLICATION",
[... additional fields omitted ...]
            "titleObjectFieldName": "creator"
        }
    ]
}

Ensure the object definitions are under the items block as valid JSON before proceeding.

Save the file.

Great! You’ve moved the distributor management app’s resources into a client extension project and created a batch payload from the object definition file. Next, you’ll define the client-extension.yaml file.

Exercise: Configuring the Batch Client Extension

Here, you’ll define the structure, resources, and configurations needed to deploy and manage the batch client extension.

Within the clarity-distributor-mgmt-batch/ project folder, open the client-extension.yaml with a text editor or IDE.
Delete the file’s existent content.
Add this code snippet:
```
assemble:
    - from: batch
      into: batch    
```
This adds the assemble block to specify which resources the client extension should package during the build process.
Insert a new line under the assemble block and add this code snippet:
```
clarity-distributor-mgmt-batch:
    name: Clarity Distributor Management Batch
    oAuthApplicationHeadlessServer: clarity-distributor-mgmt-batch-oauth-application-headless-server
    type: batch
```
This adds the batch client extension definition for Clarity’s distributor management app, including its name, the OAuth 2.0 server reference, and type.

Insert a new line under the client extension definition block and add this code snippet:

clarity-distributor-mgmt-batch-oauth-application-headless-server:
    .serviceAddress: localhost:8080
    .serviceScheme: http
    name: Clarity Distributor Management Batch OAuth Application Headless Server
    scopes:
        - Liferay.Headless.Admin.List.Type.everything
        - Liferay.Headless.Admin.User.everything
        - Liferay.Headless.Admin.Workflow.everything
        - Liferay.Headless.Batch.Engine.everything
        - Liferay.Object.Admin.REST.everything
    type: oAuthApplicationHeadlessServer

This adds an OAuth 2.0 headless server client extension for authorizing API calls with the necessary scopes for the batch client extension.

Save the file.
With the client extension set up, you can now move it to the appropriate workspace location.
Move the clarity-distributor-mgmt-batch/ project folder into the client-extensions/ folder of your course workspace.

Copying the project folder without removing the original will result in a deployment failure due to duplicate client extension folders. To prevent this, move the project to the client-extensions/ folder instead of making a copy.

Great! You’ve fully configured Clarity’s distributor management batch client extension. Next, you’ll deploy it into your Liferay environment.

Exercise: Deploying the Client Extension

Here, you’ll deploy the batch client extension to add the distributor management app into your Liferay instance.

Open a terminal and navigate to the client-extensions/clarity-distributor-mgmt-batch/ folder in your course workspace.
Run this command to build and deploy the client extension:
```
blade gw clean deploy
```
In your Liferay logs, you’ll find various messages related to import tasks. These import tasks correspond to the files within the batch/ folder.
Open your instance logs and search for a message similar to this:
```
INFO  [fileinstall-directory-watcher][BatchEngineImportTaskExecutorImpl:94] Started batch engine import task 904
```
This informs you that the batch engine has started an import task with the assigned ID 904.
Search for another message similar to this:
```
INFO  [fileinstall-directory-watcher][BatchEngineImportTaskExecutorImpl:175] Finished batch engine import task 904 in 48ms
```
This indicates that the import task with the ID 904 has finished.

You can leverage the import task ID (e.g., 904) with batch APIs to retrieve information useful for troubleshooting. Explore this in more detail in the Mastering Consuming Liferay’s Headless APIs course (coming soon).
Verify the client extension deploys successfully.
```
INFO  [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED claritydistributormgmtbatch_7.4.13 [1462]
```
Now that you've deployed the batch client extension, you can examine the distributor management app.
In your Liferay instance, 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.
Verify these objects were imported:
- Distributor Application
- Application Evaluation
In the Global Menu (), go to the Control Panel tab, and click Picklists.
Verify these picklists were imported:
- Annual Purchase Volumes
- Application States
- Assessment Scores
- Decisions
- Distribution Channels
- Distribution Regions
- Product Types
- Recommendations
In the Global Menu (), go to the Control Panel tab, and click Roles.
Verify these user roles were imported:
- Business Development Manager
- Business Development Specialist
In the Global Menu (), go to the Applications tab, and click Process Builder.
Verify the Distributor Manager Approval workflow was imported.

Conclusion

Congratulations! You’ve learned how to leverage batch client extensions to create batch payloads and migrate object definitions and resources between environments. Next, you’ll learn techniques for transforming data with client extensions.

Loading Knowledge

Capabilities

View All Capabilities

Product

Education

Connect