Transforming Clarity's Legacy Distributor Data

Now that Clarity has prepared their distributor management batch client extension, they want to import legacy applications from their previous system into Liferay. While they possess a JSON file containing historical application data, the field names are inconsistent with their current Liferay object definitions. In these exercises, you'll learn how to transform external data into the appropriate structure and import it into Liferay using batch client extensions.

Exercise: Preparing Clarity’s Distributor Data Payload

Here, you’ll transform raw distributor data from Clarity’s legacy system into a batch payload. To do so, you’ll need to map the data’s fields to the distributor management app’s structure using the fieldNameMappingMap property.

In your course workspace, navigate to the exercises/module-1/ folder.
Rename the external_system_data.json file to 04-object-entry.batch-engine-data.json.
Open the file with a text editor or IDE.
Add this code snippet to the beginning of the file:
```
{
  "items": [
```
At the end of the file, insert a new line and add the following:
```
  ]
}
```
This items array designates raw JSON information as data for the batch client extension.
Add this configuration block within the first opening curly brace ({), prior to the items block:
```
  "configuration": {
      "callbackURL": null,
      "className": "com.liferay.object.rest.dto.v1_0.ObjectEntry",
      "taskItemDelegateName": "C_DistributorApplication",
      "parameters": {
          "containsHeaders": "true",
          "createStrategy": "UPSERT",
          "onErrorFail": "false",
          "updateStrategy": "UPDATE"
    }
  },
```
To import object entries, use the object definition as the value for the taskItemDelegateName property. The value’s format should be C_ObjectName, where C_ is a prefix followed by the object’s name (case-sensitive).

Now that you’ve converted the distributor data into a batch payload, you’ll map the fields to conform to the distributor management app’s object structure.
Within the configuration block, add this code snippet below the taskItemDelegateName property:
```
"fieldNameMappingMap": {
          "businessName": "businessName",
          "contactPhone": "businessPhoneNumber",
          "email": "applicantEmailAddress",
          "name": "applicantName",
          "state": "applicationState",
          "taxId": "businessTaxIDNumber",
          "website": "businessWebsiteURL"
      },
```
The fieldNameMappingMap property is optional when the item’s fields align with the object’s structure. However, if included, it must contain all of an object’s required fields. Though Clarity’s legacy distributor data already contains a businessName field, it is still necessary to map it under the fieldNameMappingMap property.

Verify that your file resembles this final result:

{
  "configuration": {
    "callbackURL": null,
    "className": "com.liferay.object.rest.dto.v1_0.ObjectEntry",
    "taskItemDelegateName": "C_DistributorApplication",
    "fieldNameMappingMap": {
      "businessName": "businessName",
      "contactPhone": "businessPhoneNumber",
      "email": "applicantEmailAddress",
      "name": "applicantName",
      "state": "applicationState",
      "taxId": "businessTaxIDNumber",
      "website": "businessWebsiteURL"
    },
    "parameters": {
      "containsHeaders": "true",
      "createStrategy": "UPSERT",
      "onErrorFail": "false",
      "updateStrategy": "UPDATE"
    }
  },
  "items": [
    {
      "businessName": "Oculus Distributors Inc.",
      "contactPhone": "555-123-4567",
      "email": "jordan.reeves@oculusdistributors.com",
      "name": "Jordan Reeves",
      "state": "open",
      "taxId": "1011121314",
      "website": "https://oculusdistributors.com"
    }
  ]
}

Save the file.

Great! With your distributor data payload ready, you can add it to the batch client extension to import it into Liferay.

Exercise: Importing Clarity’s Legacy Distributor Data

Now that you’ve prepared Clarity’s legacy data as an appropriately configured payload, you can import it. Here, you’ll add this distributor data to the clarity-distributor-mgmt-batch client extension and redeploy it.

In your course workspace, move the 04-object-entry.batch-engine-data.json file from the module-1/ folder into the client-extensions/clarity-distributor-mgmt-batch/batch/ folder.
>From the clarity-distributor-mgmt-batch/ project folder, open the client-extension.yaml file with a text editor or IDE.
Within the clarity-distributor-mgmt-batch-oauth-application-headless-server block, add this line inside the scopes block:
```
- c_distributorapplication.everything
```
This adds the Distributor Application object’s scope to the OAuth 2.0 application.

Verify that your file resembles this final result:

assemble:
    - from: batch
      into: batch
clarity-distributor-mgmt-batch:
    name: Clarity Distributor Management Batch
    oAuthApplicationHeadlessServer: clarity-distributor-mgmt-batch-oauth-application-headless-server
    type: batch
clarity-distributor-mgmt-batch-oauth-application-headless-server:
    .serviceAddress: localhost:8080
    .serviceScheme: http
    name: Clarity Distributor Management Batch OAuth Application Headless Server
    scopes:
        - c_distributorapplication.everything
        - 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

Save the file.
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
```
Verify it deploys successfully.
```
INFO  [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED claritydistributormgmtbatch_7.4.13 [1462]
```
As the client extension attempts to import resources already included in the instance, an import task error in the Liferay logs is expected. You can safely ignore this error.
In your Liferay instance, open the Global Menu (), go to the Applications tab, and click Distributor Applications.
Verify that a new entry for Jordan Reeves is present.

Leveraging these steps, Clarity can import distributor data from their legacy system into Liferay, empowering them to centralize data and streamline decision-making.

Conclusion

Great! You’ve learned how to leverage batch client extensions to import remapped JSON data from external sources. Next, you’ll learn about managing configurations as deployable assets.

Loading Knowledge

Capabilities

View All Capabilities

Product

Education

Connect