Custom Add-On Api.

The Custom SFDMU Add-On Api allows you to build your own Add-On extensions allowing you to extend the SFDMU with unlimited new custom features which might be required by your business.

This Api is based on the SFDMU Add-On API Engine.

Table of Contents

• Example of Custom SFDMU Add-On module.
• How to try this module.
  • Step 1. Install.
  • Step 2. Compile.
  • Step 3. Create root directory and copy necessary files.
  • Step 4. Create new export.json file.
  • Step 5. Create new custom fields.
  • Step 6. Create new Account record.
  • Step 7. Launch the migration job.
  • Step 8. Check the results.
• Full specification of the Add-On Event declaration.
• List of the supported Add-On events.
• The Add-On Event lifecycle.
• How to create and run your own Custom SFDMU Add-On Module.
  • Step 1. Create module directory.
  • Step 2. Compile.
  • Step 3. Copy files to the module directory.
  • Step 4. Create new export.json file.
  • Step 5. Launch the migration job.
  • Step 6. Check the results.
• How to debug the Custom Add-On module.

Example of Custom SFDMU Add-On module. ⇧

For demonstration purposes, we've shared the source code of the test custom Add-On module with other SFDMU's source.

You can use this module as a basic code snipped for building your modules.

The Add-On makes a very simple modification in the source records just before they will be uploaded to the target SF environment.

How to try this module. ⇧

Step 1. Install. ⇧

Install the SFDM source code .

Step 2. Compile. ⇧

Compile the SFDMU source code.

# Make current 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 into this directory the listed below parts:

• 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 be looked like this:

|-- 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:

• You don't need to update the /package folder each time your are creating or compiling your modules. Upgrade it once we are pushing a new release of the SFDMU.
• The minimal required file for custom module is index.js (its TS source is index.ts). This file is the main entry point of the module and it's executed by the SFDMU Plugin when the migration job is started.

Step 4. Create new export.json file. ⇧

Let's say, that the root directory for all export.jsons is "C:\SFDMU\". Create a new export.json file with the following content and put it into 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 the beforeUpdate Add-On Event Declaration. It defines the lists the Add-On modules which should be launched right BEFORE the Account object is going to be updated on the Target environment. Here the good place to make a modifications in the source records, then your modifications will be uploaded to the Target org.

• In our case we run only the module CustomSfdmuRunAddonTemplate, so the beforeUpdateAddons array contains only one module definition object.

• The path property is pointing to the directory where the index.js file of our sample module is located.

• You can add unlimited number of modules to execute per Add-On event.

Step 5. Create new custom fields. ⇧

In both the Source and the 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 Sourcesalesforce 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 fly using our Add-On module.

Step 7. Launch the migration job. ⇧

Launch the SFDMU with the export.json created in the 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 have these fields populated as following:

  # 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. ⇧

List of the supported Add-On events. ⇧

See it here: Supported Add-On Api events

The Add-On Event lifecycle. ⇧

Below is the order of Add-On evenrts invocation:

Global.OnBefore

Object.OnBefore

Global.OnDataRetrieved

Object.OnTargetDataFiltering

Object.OnBeforeUpdate

Object.OnAfterUpdate

Object.OnAfter

Global.OnAfter

How to create and run your own Custom SFDMU Add-On Module. ⇧

We will create the module using the same root directory and the directory structure as we used when tried the sample Add-On module of above.

Make sure you've already copied the SFDMU Add-On Runtime Library package into it.

Let's create another module TestModule. We use the same main directory and the directory structure as above.

Step 1. Create module directory. ⇧

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

The content of the index.ts 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.

# Make current 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 our root module folder C:\MySfdmuAddOns\TestModule

Step 4. Create new export.json file. ⇧

Create a new export.json file with the following content and put it into 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 this 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 the result of the job, the new Account record should be created in the Target org and the Add-On should print in the Console window like that:

[2021-10-18 08:48:20.619] {Account} Executing of the event:onBeforeUpdate 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} Executing of the event:onBeforeUpdate Add-On handlers has finished

How to debug the Custom Add-On module. ⇧

As the custom Add-On component is a part of the SFDMU, it can be debugged together with the entire SFDMU Plugin.

When developing the module, simply put the break point in the module code and run the Plugin in debug mode.