Advanced Configurator/CML Deployer

A powerful tool to migrate Salesforce Advanced Configurator aka CML code between orgs directly from within Visual Studio Code.

This extension automates the entire complex process of migrating an Advanced Configurator, including its CML script, all related data, and crucially, all its complex lookup relationships to other objects like Products and Components.

Features

• End-to-End Migration: Automates the entire migration of an Advanced Configurator setup (ExpressionSet and all its related records).

• Intelligent ID Resolution: Automatically resolves Salesforce Record IDs between source and target orgs using external IDs, ensuring data integrity across different environments.

• Complex Relationship Handling: Correctly maps complex data relationships, including ProductRelatedComponent records based on their parent product and component group.

• Automated Cleanup: Performs a clean deployment by first deleting any old constraint records from a previous version in the target org before deploying the new ones.

• Script Migration: Handles the export and import of the CML script.

• Resumable Migrations: If a migration fails mid-way (e.g., due to a network error), re-running the command will intelligently resume from the last successful step, saving significant time.

• User-Friendly Interface: A fully guided UI within VSCode using the Command Palette, with real-time, detailed progress notifications.

• Automatic Workspace Management: Creates all temporary migration files in the system's temp directory, keeping your project folder clean. After a successful migration, all temporary files are automatically deleted.

• Data Compliant: This tool enhances security by only retrieving the essential record IDs and unique identifiers needed for the deployment, completely avoiding sensitive data like product names. Furthermore, all temporary files generated during the process are permanently deleted from your local machine upon completion, ensuring your data remains secure.

Prerequisites

Before using this extension, please ensure you have the following configured:

1. Visual Studio Code (v1.80.0 or higher).
2. Salesforce CLI (sf) installed and available in your system's PATH.
3. You must be authenticated to both your source and target Salesforce orgs via the CLI. You can check your authenticated orgs by running sf org list --all in your terminal.
4. Make sure the target org has the required PCM data.

How to Use

1. Install the Extension:

   • Install the "Advanced Configurator/CML Deployer" extension from the Visual Studio Code Marketplace.

2. Run the Deployment:

   • Open your project folder in VSCode.
   • Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows).
   • Type and select RCCML: Deploy Advanced Configurator.
   • Follow the interactive prompts that appear at the top of the screen:
     1. Select your source org.
     2. Select your target org.
     3. Enter the ApiName of the Advanced Configurator to deploy.

Configuration (Optional)

By default, the extension uses a standard set of fields to match records between your source and target orgs.

If your org uses different fields as unique identifiers (e.g., ProductCode on the Product object), you can easily override these defaults by adding settings to your VS Code settings.json file. You can find this file in your project at .vscode/settings.json (if the file or folder doesn't exist, you can create them)

The example below shows how you might configure the extension to use custom fields for your specific project.

Example settings.json:

{
    //all existing code,
    "cmlDeployer.product2.externalIdField": "ProductCode",
    "cmlDeployer.productClassification.externalIdField": "Legacy_ID__c",
    "cmlDeployer.productComponentGroup.externalIdField": "Group_Code__c"
}

How It Works

The tool follows a robust 3-step process for each deployment:

1. Export: Connects to the source org and extracts the entire Advanced Configurator configuration, including all its dependent data and relationships.

2. Transform: Intelligently maps the extracted data to the target org by resolving Salesforce record IDs using the unique external identifiers specified in your settings (or the defaults).

3. Deploy: Connects to the target org and performs a clean deployment, ensuring all records are created in the correct order and the CML script is uploaded.

Limitations and Known Issues

Limitations

• Single CML Deployment: The current version of the extension supports the deployment of only one Advanced Configurator (ExpressionSet) at a time. Bulk or multi-CML deployments are not supported.

• Deployed Inactive: The current version doesn't deploy the CML code in Active status.

Known Issues

• Record Not Found / Timeout Errors: In some cases, a deployment may fail with an error like Could not find a matching record in target org.... This can happen due to transient Salesforce data replication delays.

  • Workaround: Simply re-run the RCCML: Deploy Advanced Configurator command. The tool is designed to resume from the last successful step.

  • Verification: If the issue persists, use the following steps to verify your data. The first part of the failing record's ID tells you which object to check.

    For Products (Product2, ID prefix 01t)

    1. In the Source Org, run this query to find the product's unique identifier (using your configured field, e.g., ExternalId or ProductCode):

       SELECT Id, Name, {Your-Product-Ext-ID-Field} FROM Product2 WHERE Id = '{ID FROM ERROR MESSAGE}'
       

    2. In the Target Org, use the unique value from the previous query to find the matching record:

       SELECT Id, Name, {Your-Product-Ext-ID-Field} FROM Product2 WHERE {Your-Product-Ext-ID-Field} = '{Value FROM PREVIOUS QUERY}'
       

    If a record is found, the data is correct. Try re-running the deployment.

    For Product Classifications (ProductClassification, ID prefix 11B)

    1. In the Source Org, run this query to find the classification's unique identifier:

       SELECT Id, Name, {Your-Classification-Ext-ID-Field} FROM ProductClassification WHERE Id = '{ID FROM ERROR MESSAGE}'
       

    2. In the Target Org, use the unique value from the previous query to find the matching record:

       SELECT Id, Name, {Your-Classification-Ext-ID-Field} FROM ProductClassification WHERE {Your-Classification-Ext-ID-Field} = '{Value FROM PREVIOUS QUERY}'
       

    For Product Related Components (ProductRelatedComponent, ID prefix 0dS) These records are matched using a composite key derived from their parent records. To verify, check the following:

    1. In the Source Org, identify the unique ID value (e.g., ExternalId or ProductCode) of the parent Product2, unique ID value (e.g., ExternalId or ProductCode) of the parent Product2 and the unique ID value (e.g., Code) of the parent ProductComponentGroup.

       SELECT Id, Name, ParentProduct.{Your-Product-Ext-ID-Field}, ChildProduct.{Your-Product-Ext-ID-Field}, ProductComponentGroup.Code FROM ProductRelatedComponent WHERE Id = 'ID_FROM_ERROR_OUTPUT'
       

    2. In the Target Org, confirm that records exist with those exact same unique ID values.
    3. Finally, confirm that a ProductRelatedComponent record exists in the target org that links those three records.

       SELECT Id, Name, ParentProduct.{Your-Product-Ext-ID-Field}, ChildProduct.{Your-Product-Ext-ID-Field}, ProductComponentGroup.{Your-Classification-Ext-ID-Field} FROM ProductRelatedComponent WHERE ParentProduct.{Your-Product-Ext-ID-Field} = '' AND ProductComponentGroup.{Your-Classification-Ext-ID-Field} = '' AND ChildProduct.{Your-Product-Ext-ID-Field} = ''
       

Feedback and Contributions

If you encounter any issues or have a feature request, please email at arohitu@gmail.com