Custom Add-On Api.


The Custom SFDMU Add-On API enables the creation of unique Add-On extensions, offering the capability to enhance SFDMU with an unlimited array of custom features tailored to your business needs.

This API is founded on the principles outlined in the SFDMU Add-On API Engine.

Table of Contents



Example of a Custom SFDMU Add-On Module

For demonstration purposes, the source code of a test custom Add-On module has been shared alongside SFDMU's source code.

This module serves as a foundational code snippet for developing your own modules.

The Add-On performs a straightforward modification to the source records just before they are uploaded to the target Salesforce environment.

How to try this module.

Step 1. Install.

Install the SFDM source code .

Step 2: Compile

Compile the SFDMU source code.

# Navigate to the directory where the source code is cloned
cd C:\SFDX-Data-Move-Utility

# Compile the project
npm run build

Step 3: Create Root Directory and Copy Necessary Files

Create the root directory C:\MySfdmuAddOns for all custom Add-On modules.

Copy the following components into this directory:

  • The compiled component's source from C:\SFDX-Data-Move-Utility\lib\addons\modules\sfdmu-run\custom-addons\CustomSfdmuRunAddonTemplate.
  • The SFDMU Add-On Runtime Library package from C:\SFDX-Data-Move-Utility\lib\addons\modules\sfdmu-run\custom-addons\package.

The target directory structure should look as follows:


|-- C:\MySfdmuAddOns					<= The root directory for all Add-On modules
    |-- CustomSfdmuRunAddonTemplate		<= Directory containing our sample module
    |  	|-- index.d.ts
    |  	|-- index.js
    |  	|-- index.js.map
    |--	custom_module_1
    |--	custom_module_2
    |--	other custom modules ...
    |-- package						    <= SFDMU Add-On Runtime Library package.
    |--	|-- common.js
    |--	|-- index.js
    |--	|-- other package files ...
Notes:
  • There's no need to update the /package folder every time you create or compile your modules. Update it only when a new release of SFDMU is pushed.
  • The essential file for a custom module is index.js (and its TypeScript source, index.ts). This file serves as the main entry point of the module and is executed by the SFDMU Plugin when a migration job starts.

Step 4: Create New export.json File

Assuming the root directory for all export.json files is "*C:\SFDMU\*", create a new export.json file with the required content and place it in C:\SFDMU\CustomSfdmuRunAddonTemplate:

{
    "objects": [
        {
            "operation": "Upsert",
            "externalId": "Name",
            "deleteOldData" : true,
            "query": "SELECT Id, Name, LongText__c, TEST__c, TEST1__c  FROM Account WHERE Name = 'ACC_10000'",
            "beforeUpdateAddons" : [
                {
                        "description": "This example of the Sustom SFDMU AddOn module manipulates with the source Account records right before the target SF object going to be updated. It extracts the value from the JSON stored in the LongText__c, then puts the extracted string into the TEST1__c.",
                        "path" : "C:\\MySfdmuAddOns\\CustomSfdmuRunAddonTemplate",
                        "args" : {
                            "TEST__c": "Another small manipulation with the source data: we want to populate the TEST__c field of each record with this constant text."
                        }
                }
            ]
        }
    ]
}
Notes:
  • The array beforeUpdateAddons is for the beforeUpdate Add-On Event Declaration. It specifies the list of Add-On modules to be executed right BEFORE updating the Account object in the Target environment. This is an ideal place to modify source records, as your modifications will then be uploaded to the Target org.
  • In our scenario, we run only the module CustomSfdmuRunAddonTemplate, so the beforeUpdateAddons array contains only this module's definition object.
  • The path property indicates the directory where the index.js file of our sample module is located.
  • You can add an unlimited number of modules to execute per Add-On event.

Step 5: Create New Custom Fields

In both the Source and Target Salesforce orgs, add three new custom fields to the Account object:

  • LongText__c: Long Text Area(32768)
  • TEST__c: Text(255)
  • TEST1__c: Text(255)

Step 6: Create New Account Record

Create a new Account record in the Source Salesforce org and initialize it with the following values:

  • Name: "ACC_10000"
  • LongText__c: "{"TEST1__c": "Test Value"}"
  • Leave the fields TEST__c and TEST1__c blank as we want to populate them on the fly using our Add-On module.

Step 7: Launch the Migration Job

Launch the SFDMU with the export.json created in Step 4:

sfdx sfdmu:run --sourceusername source@name.com --targetusername target@name.com --path C:\\SFDMU\CustomSfdmuRunAddonTemplate

Step 8: Check the Results

After the job is completed, verify that the migration job was done correctly and the Add-On has worked as expected:

  • Open the Target Salesforce Org, then locate the Account record having the Name ACC_1000, newly created by the SFDMU.

  • Click the "Details" tab and you should see the fields populated as follows:

    # The original LongText__c value has been transferred unchanged, as it was explicitly included in the query of Account:
    LongText__c: "{"TEST1__c": "Test Value"}"
    
    # This field is populated with the constant value, passed to the Add-On as an input argument via the "args" property:
    TEST__c: "Another small manipulation with the source data: we want to populate the TEST__c field of each record with this constant text."
    
    # This field is populated with the value extracted from the json stored in the LongText__c field.
    TEST1__c: "Test Value"
    

Full Specification of the Add-On Event Declaration

Property Name Is Mandatory ? Data type Description
description No string The description of the module.
Passed to the Add-On instance using the module run-time context object.
path Yes string The absolute or relative path to the directory where the compiled module is located.
We recommend using absolute paths for better chance that the Plugin will locate the module properly.
args No Object The optional object passed as is to the module onExecute method using the args method parameter (see below).
Use this parameter for the customized initialization of the Add-On instance via the export.json.

List of the supported Add-On events and the execution lifecycle.

See it here: Supported Add-On Api events

How to Create and Run Your Own Custom SFDMU Add-On Module

We will create the module using the same root directory and directory structure as used for the sample Add-On module mentioned above. Ensure the SFDMU Add-On Runtime Library package has already been copied into it.
Let's create another module named TestModule, utilizing the same main directory and directory structure as described previously.

Step 1: Create Module Directory

Create a new subdirectory TestModule under C:\SFDX-Data-Move-Utility\src\addons\modules\sfdmu-run\custom-addons, and then create a new index.ts file inside it.

The content of the index.ts file is:

import { ISfdmuRunCustomAddonContext, ISfdmuRunCustomAddonModule, ISfdmuRunCustomAddonResult, ISfdmuRunCustomAddonRuntime } from "../package";

export default class SfdmuCustomAddOnModule implements ISfdmuRunCustomAddonModule {

    constructor(runtime: ISfdmuRunCustomAddonRuntime) {
        this.runtime = runtime;
    }

    runtime: ISfdmuRunCustomAddonRuntime;

    async onExecute(context: ISfdmuRunCustomAddonContext, args: any): Promise<ISfdmuRunCustomAddonResult> {

        // Just for the example... The line below will prints to the Console the following: "The running Plugin is: sfdmu".
        // TODO: Put your own code instead this line.
        this.runtime.service.log(this, 'The running Plugin is: ' +  this.runtime.service.getPluginRunInfo().pinfo.pluginName);

        // Return null to continue the migration job
        return null;
    }
}

Step 2: Compile

Compile the module.

# Navigate to the directory where the source code is cloned
cd C:\SFDX-Data-Move-Utility

# Compile the project
npm run build

Step 3: Copy Files to the Module Directory

Copy the compiled module component files from C:\SFDX-Data-Move-Utility\lib\addons\modules\sfdmu-run\custom-addons\TestModule to the root module folder C:\MySfdmuAddOns\TestModule.

Step 4: Create New export.json File

Create a new export.json file with the following content and place it in C:\SFDMU\TestModule:

{
    "objects": [
        {
            "operation": "Insert",
            "query": "SELECT Name FROM Account WHERE Name = 'ACC_10000'",
            "beforeUpdateAddons" : [
                {
                    "path" : "C:\\MySfdmuAddOns\\TestModule"
                }
            ]
        }
    ]
}

Step 5: Launch the Migration Job

Launch the SFDMU with the specified export.json file:

sfdx sfdmu:run --sourceusername source@name.com --targetusername target@name.com --path C:\SFDMU\TestModule

Step 6: Check the Results

After the job is completed, verify the results.

As a result of the job, a new Account record should be created in the Target org, and the Add-On should output the following in the Console window:

[2021-10-18  08:48:20.619] {Account} Execution of the event:beforeUpdateAddons Add-On handlers has started.

[2021-10-18  08:48:20.620] [custom:TestModule] {Account} **The running Plugin is: sfdmu**.

[2021-10-18  08:48:20.622] {Account} Execution of the event:beforeUpdateAddons Add-On handlers has finished.

How to Debug the Custom Add-On Module

Since the custom Add-On component is part of SFDMU, it can be debugged alongside the entire SFDMU Plugin.

When developing the module, simply place a breakpoint in the module code and run the Plugin in debug mode.

Last updated on 15th Mar 2024