@salesforce/plugin-omnistudio-migration-tool 2.0.0-rc.6 → 2.0.0-rc.61

package/README.md

@@ -1,13 +1,23 @@
-# OmniStudio Migration Assistant
+# Omnistudio Migration Assistant
 
-The Omnistudio Migration Assistant is a command-line interface (CLI) plugin that you install via Salesforce CLI. It creates records for your omnistudio components on the Salesforce standard objects.
+The Omnistudio Migration Assistant is a Salesforce CLI plugin that automates the migration of Omnistudio components. When run on a custom data model with managed package runtime, it migrates components to the standard data model and switches them to the Omnistudio standard runtime. When run on a standard data model with managed package, it cleans record names, enables the metadata API, and switches to the Omnistudio standard runtime.
 
-### Before You Begin
+## 🚀 Before You Begin
+
+> **Note:** The `sfdx` CLI has been deprecated. Please use `sf` CLI commands instead. The deprecated `sfdx` command aliases (`-u`, `--targetusername`) are still supported.
+
+⚠️ IMPORTANT: Before installing and using the Omnistudio Migration Assistant, contact Salesforce support.
 
 - Review the migration phases in [Migration Process from Omnistudio for Managed Packages to Omnistudio](https://help.salesforce.com/s/articleView?id=xcloud.os_migrate_omnistudio_custom_objects_to_standard_objects.htm&language=en_US&type=5)
 
 - Install Salesforce CLI on your computer. See : [Install Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm).
 
+- To deploy LWC as part of auto-deployment process, environment variable 'OMA_AUTH_KEY' should be set with requested NPM repository access key from Salesforce Customer Support.
+
+- This tool requires Node Version 18+.
+
+- LWC migration auto-deployment needs minimum node version of 18.17.1
+
 ## Install and Run the Omnistudio Migration Assistant
 
 1. Install SF cli using the official documentation located [here](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm).
@@ -28,60 +38,63 @@ You can also authenticate using a consumer key (client ID) and secret key throug
 3. In a new terminal session, Install the Omnistudio Migration Assistant by running the `sf plugins install` command. For example
 
 ```
-sf plugins install @salesforce/plugin-omnistudio-migration-tool@2.0.0-beta.13
+sf plugins install @salesforce/plugin-omnistudio-migration-tool@2.0.0-dev.1
 ```
 
 4. Run the Omnistudio Migration Assistant from the Salesforce CLI:
 
 ```
 // To assess everything without migrating
-sfdx omnistudio:migration:assess -u YOUR_ORG_USERNAME@DOMAIN.COM
+sf omnistudio:migration:assess -u YOUR_ORG_USERNAME@DOMAIN.COM
 
 // To migrate everything
-sfdx omnistudio:migration:migrate -u YOUR_ORG_USERNAME@DOMAIN.COM
+sf omnistudio:migration:migrate -u YOUR_ORG_USERNAME@DOMAIN.COM
 
 
-// To migrate/assess specific components: FlexCards, DataMappers, Integration Procedures, OmniScripts, or Global Auto Numbers, add the following parameters:
---only=dr    // DataMappers (DataRaptors)
---only=ip    // Integration Procedures
---only=os    // OmniScripts
---only=fc    // FlexCards
---only=autonumber   // Global Auto Numbers
+// To migrate/assess specific components: Flexcards, Data Mappers, Integration Procedures, Omniscripts, Omni Global Auto Numbers or Custom Labels, add the following parameters:
+--only=dm           // Data Mappers
+--only=ip           // Integration Procedures
+--only=os           // Omniscripts
+--only=fc           // Flexcards
+--only=autonumber   // Omni Global Auto Numbers
+--only=cl           // Custom Labels
 
 // To migrate all versions of the components and not just the active ones:
 --allversions
 
-// To assess specific related objects:
---relatedobjects=apex    // for Apex classes only
+// To assess specific set of related objects:
+--relatedobjects=apex                             // for Apex classes only
+--relatedobjects=lwc                              // for Lightning Web Components only
+--relatedobjects=expsites                         // for Experience Sites only
+--relatedobjects=flexipage                        // for FlexiPages only
+--relatedobjects=apex,lwc,expsites,flexipage      // for all related objects
 
-// To specify the Velocity Namespace (Optional)
---namespace=VLOCITY_PACKAGE_NAMESPACE
 ```
 
 5. An HTML page will be open in your default browser with the results of your migration/assessment reports.
 
-## Global Auto Number Migration
+## Omni Global Auto Number Migration
 
-Global Auto Numbers are components that generate sequential numbers across your Omnistudio org. The migration tool supports both assessment and migration of these components.
+Omni Global Auto Numbers are components that generate sequential numbers across your Omnistudio org. The migration tool supports both assessment and migration of these components.
 
-### Prerequisites for Global Auto Number Migration
+### Prerequisites for Omni Global Auto Number Migration
 
-Before migrating Global Auto Numbers, ensure that:
+Before migrating Omni Global Auto Numbers, ensure that:
 
 1. **Org Preference is Disabled**: The `OmniGlobalAutoNumberPref` org preference must be disabled before migration
 2. **Rollback Flags are Disabled**: Both `RollbackIPChanges` and `RollbackDRChanges` flags must be disabled
 3. **Namespace is Specified**: Provide the correct namespace for your OmniStudio package
 
-### Global Auto Number Migration Process
+### Omni Global Auto Number Migration Process
 
-The migration process for Global Auto Numbers includes:
+The migration process for Omni Global Auto Numbers includes:
 
 1. **Pre-migration Checks**: Validates that org preferences and rollback flags are properly configured
-2. **Data Migration**: Transforms Global Auto Number settings from custom objects to standard Business Process Objects (BPO)
+2. **Data Migration**: Transforms Omni Global Auto Number settings from custom objects to standard Business Process Objects (BPO)
 3. **Post-migration Cleanup**: Removes source objects and enables the `OmniGlobalAutoNumberPref` org preference
 4. **Validation**: Ensures all records are successfully migrated before cleanup
 
-### Global Auto Number Assessment
+### Omni Global Auto Number Assessment
 
 Assessment provides detailed information about:
 
@@ -89,91 +102,170 @@ Assessment provides detailed information about:
 - **Migration Readiness**: Determines if components can be automatically migrated or require manual intervention
 - **Warnings**: Highlights potential issues that may affect migration success
 
-### Usage Examples for Global Auto Numbers
+### Usage Examples for Omni Global Auto Numbers
 
 ```bash
-# Assess Global Auto Numbers only
-sfdx omnistudio:migration:assess -u YOUR_ORG_USERNAME@DOMAIN.COM --only=autonumber
+# Assess Omni Global Auto Numbers only
+sf omnistudio:migration:assess -u YOUR_ORG_USERNAME@DOMAIN.COM --only=autonumber
 
-# Migrate Global Auto Numbers only
-sfdx omnistudio:migration:migrate -u YOUR_ORG_USERNAME@DOMAIN.COM --only=autonumber
+# Migrate Omni Global Auto Numbers only
+sf omnistudio:migration:migrate -u YOUR_ORG_USERNAME@DOMAIN.COM --only=autonumber
 ```
 
 5. An HTML page will be open in your default browser with the results of your migration/assessment job.
 
-### Assess Usage & parameters
+## Clean Command
+
+Deactivates and deletes Omnistudio records (Omniscripts, Integration Procedures, Flexcards, and Data Mappers) that blocks enabling the Omnistudio Metadata API. Removes records with special characters in unique name fields or missing unique names.
+
+> ⚠️ **Warning:** This action is permanent. Always run in a testing sandbox first and verify results before running in production.
+
+### Prerequisites
+
+- ✅ Org uses **standard data model** (not custom data model)
+- ✅ **Metadata API not enabled** in your org
+- ✅ All Omnistudio components **backed up** or deployed to testing sandbox
+- ✅ Run in **testing sandbox first** to verify results
+
+### Quick Start
 
+```bash
+# Step 1: Preview what would be cleaned (recommended)
+sf omnistudio:migration:clean -u orguser@domain.com --assess
+
+# Step 2: Review assessment reports in clean_assessment/ folder
+
+# Step 3: Run actual cleanup (requires confirmation)
+sf omnistudio:migration:clean -u orguser@domain.com
 ```
-USAGE
-  $ sf omnistudio:migration:assess [-n <string>] [-f] [-v <string>] [-u <string>] [--apiversion <string>] [--json] [--loglevel
-  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
 
-OPTIONS
-  -n, --namespace=namespace                                                         the namespace of the vertical package
+### Command Options
 
-  -u, --targetusername=targetusername                                               username or alias for the target
-                                                                                    org; overrides default target org
+| Option                        | Description                                             |
+| ----------------------------- | ------------------------------------------------------- |
+| `-u, --target-org=<username>` | (required) Username or alias for target org             |
+| `--assess`                    | Preview records that would be removed (no changes made) |
 
-  -v, --targetdevhubusername=targetdevhubusername                                   username or alias for the dev hub
-                                                                                    org; overrides default dev hub org
+### Usage Examples
 
-  --apiversion=apiversion                                                           override the api version used for
-                                                                                    api requests made by this command
+#### Preview Mode (Assessment)
 
-  --json                                                                            format output as json
+```bash
+# Preview without making changes
+sf omnistudio:migration:clean -u orguser@domain.com --assess
+```
 
-  --loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL)  [default: warn] logging level for
-                                                                                    this command invocation
+**Assessment Output:**
 
-  -a, --allversions                                                                 migrate all versions and not
-                                                                                    and not just the active ones.
+- Reports saved to `clean_assessment/` folder
+- JSON files for each component type (Omniscripts, Integration Procedures, Flexcards, Data Mappers)
+- Each file contains:
+  - `specialCharacterRecords`: Records with special characters in unique names
+  - `orphanRecords`: Records without deployment references (missing unique names)
+  - `totalToDelete`: Total records that would be removed
 
-  --only=only                                                                       specify components to assess:
-                                                                                    dr (DataRaptors), ip (Integration Procedures),
-                                                                                    os (OmniScripts), fc (FlexCards), autonumber (Global Auto Numbers)
+#### Cleanup Mode
 
-  --relatedobjects=relatedobjects                                                   specify related objects to assess:
-                                                                                    'apex' for Apex classes
+```bash
+# Run cleanup (requires confirmation)
+sf omnistudio:migration:clean -u orguser@domain.com
 ```
 
-### Migrate Usage & parameters
+**What Happens:**
+
+1. Validates prerequisites (standard data model, Metadata API not enabled)
+2. Shows warning and prompts for confirmation
+3. **Phase 1**: Deactivates and deletes records with special characters
+4. **Phase 2**: Deactivates and deletes records without unique names
+5. Displays completion message
+
+### Cleanup Process
+
+The clean command runs in two phases:
+
+1. **Phase 1: Special Character Cleanup**
+
+   - Removes records with special characters in unique name fields
+   - These records are incompatible with Metadata API
+
+2. **Phase 2: Missing Unique Name Cleanup**
+   - Removes records without deployment references (missing unique names)
+   - These records blocks enabling Metadata API
+
+### Full Command Reference
 
 ```
 USAGE
-  $ sf omnistudio:migration:migrate [-n <string>] [-f] [-v <string>] [-u <string>] [--apiversion <string>] [--json] [--loglevel
-  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
+  $ sf omnistudio:migration:clean -u <username> [--assess]
 
 OPTIONS
-  -n, --namespace=namespace                                                         the namespace of the vertical package
+  -u, --target-org=<username>    (required) username or alias for the target org
+  --assess                        preview which records would be removed without making changes
+```
 
-  -u, --targetusername=targetusername                                               username or alias for the target
-                                                                                    org; overrides default target org
+### Assess Usage & parameters
 
-  -v, --targetdevhubusername=targetdevhubusername                                   username or alias for the dev hub
-                                                                                    org; overrides default dev hub org
+```
+USAGE
+  $ sf omnistudio:migration:assess -u <username> [--only <component>] [--allversions]
+    [--relatedobjects <objects>] [--verbose]
 
-  --apiversion=apiversion                                                           override the api version used for
-                                                                                    api requests made by this command
+OPTIONS
+  -u, --target-org=<username>                       (required) username or alias for the target org
+                                                    (alias: --targetusername - deprecated)
 
-  --json                                                                            format output as json
+  -o, --only=<component>                            specify a single component to assess:
+                                                    dm (Data Mappers),
+                                                    ip (Integration Procedures),
+                                                    os (Omniscripts),
+                                                    fc (Flexcards),
+                                                    autonumber (Omni Global Auto Numbers),
+                                                    cl (Custom Labels)
 
-  --loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL)  [default: warn] logging level for
-                                                                                    this command invocation
+  -a, --allversions                                 assess all versions, not just the active ones
 
-  -a, --allversions                                                                 migrate all versions and not
-                                                                                    and not just the active ones.
+  -r, --relatedobjects=<objects>                    specify one or more related objects to assess (comma separated):
+                                                    apex       - Apex classes
+                                                    lwc        - Lightning Web Components
+                                                    expsites   - Experience Sites
+                                                    flexipage  - FlexiPages
 
-  --only=only                                                                       specify components to migrate:
-                                                                                    dr (DataRaptors), ip (Integration Procedures),
-                                                                                    os (OmniScripts), fc (FlexCards)
+  --verbose                                         enable verbose output
 
-  --relatedobjects=relatedobjects                                                   specify related objects to assess:
-                                                                                    'apex' for Apex classes
+  --loglevel=<level>                                (deprecated) use --verbose instead
 ```
 
-> **Note:** LWC (Lightning Web Components) assessment/migration functionality is temporarily disabled in the current version. LWC features will be re-enabled in a future releases.
+### Migrate Usage & parameters
 
-> Apex migration functionality remains fully available. The `--relatedobjects` flag only accepts values ('apex')
+```
+USAGE
+  $ sf omnistudio:migration:migrate -u <username> [--only <component>] [--allversions]
+    [--relatedobjects <objects>] [--verbose]
+
+OPTIONS
+  -u, --target-org=<username>                       (required) username or alias for the target org
+                                                    (aliases: --targetusername - deprecated)
+
+  -o, --only=<component>                            specify a single component to migrate:
+                                                    dm (Data Mappers),
+                                                    ip (Integration Procedures),
+                                                    os (Omniscripts),
+                                                    fc (Flexcards),
+                                                    autonumber (Omni Global Auto Numbers),
+                                                    cl (Custom Labels)
+
+  -a, --allversions                                 migrate all versions, not just the active ones
+
+  -r, --relatedobjects=<objects>                    specify one or more related objects to migrate (comma separated):
+                                                    apex       - Apex classes
+                                                    lwc        - Lightning Web Components
+                                                    expsites   - Experience Sites
+                                                    flexipage  - FlexiPages
+
+  --verbose                                         enable verbose output
+
+  --loglevel=<level>                                (deprecated) use --verbose instead
+```
 
 Terms:
 Notwithstanding anything stated in the terms and conditions agreed between Salesforce (‘SFDC’) and you (‘Customer’), the use of the OmniStudio Migration Assistant (‘Assistant’) is designed to facilitate the migration and it’s going to modify your custom code and by deploying and using the Assistant you hereby provide your consent to automate the migration process and enable a smooth transition. Customer shall access and use the Assistant only as permitted to the Customer and shall not compromise, break or circumvent any technical processes or security measures associated with the services provided by SFDC.

package/lib/commands/omnistudio/migration/assess.d.ts

@@ -1,23 +1,31 @@
-import { flags } from '@salesforce/command';
-import OmniStudioBaseCommand from '../../basecommand';
-export default class Assess extends OmniStudioBaseCommand {
+import { Org, Logger as CoreLogger } from '@salesforce/core';
+import { SfCommand, Ux } from '@salesforce/sf-plugins-core';
+import { AssessmentInfo } from '../../../utils/interfaces';
+interface AssessFlags {
+    'target-org'?: Org;
+    only?: string;
+    allversions?: boolean;
+    relatedobjects?: string;
+    verbose?: boolean;
+}
+export default class Assess extends SfCommand<AssessmentInfo> {
     static description: string;
     static examples: string[];
-    static args: {
-        name: string;
-    }[];
-    protected static flagsConfig: {
-        namespace: flags.Discriminated<flags.String>;
-        only: flags.Discriminated<flags.String>;
-        allversions: flags.Discriminated<flags.Boolean<boolean>>;
-        relatedobjects: flags.Discriminated<flags.String>;
-        verbose: flags.Builtin;
-    };
-    run(): Promise<any>;
-    runAssess(): Promise<any>;
+    static args: any;
+    static readonly flags: any;
+    run(): Promise<AssessmentInfo>;
+    runAssess(parsedFlags: AssessFlags, ux: Ux, logger: CoreLogger): Promise<AssessmentInfo>;
     private assessOmniStudioComponents;
     private assessDataRaptors;
     private assessFlexCards;
     private assessOmniScripts;
+    private assessSaveForLater;
     private assessGlobalAutoNumbers;
+    private assessCustomLabels;
+    /**
+     * Logs assessment completion with count and completion message if needed
+     * Skips logging when standard data model with metadata API is enabled
+     */
+    private logAssessmentCompletionIfNeeded;
 }
+export {};