Merge pull request #419 from sf-kishore-kurri/u/kkurri/W-19637353

fix: @W-19637353: Fix for the omnscript unmanaged package deployment issue

Author: snehaljha-sf

README.md

@@ -1,8 +1,10 @@
-# 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.
 
-### Before You Begin
+## 🚀 Before You Begin
+
+⚠️ 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)
 
@@ -32,7 +34,7 @@ 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/[email protected].43
+sf plugins install @salesforce/[email protected].50
 ```
 
 4. Run the Omnistudio Migration Assistant from the Salesforce CLI:

messages/assess.json

@@ -46,8 +46,8 @@
   "allVersionsInfo": "All versions: %s",
   "assessmentInitialization": "Assessment process started. Using namespace: %s",
   "apiVersionInfo": "API version: %s",
-  "unknownNamespace": "Org doesn't have Omnistudio namespace(s) configured",
-  "noOmniStudioLicenses": "OmniStudio licenses are not found in the org. OmniStudio licenses are required for migration assessment",
+  "unknownNamespace": "Omnistudio namespace is not configured in this org. Configure the namespace and try again",
+  "noOmniStudioLicenses": "We couldn’t find Omnistudio licenses in this org. Omnistudio licenses are required for migration assessment",
   "assessmentTargets": "Assessment targets: %s",
   "relatedObjectsInfo": "Related objects: %s",
   "allVersionsFlagInfo": "All versions: %s",
@@ -195,5 +195,6 @@
   "ipNameUpdateFailed": "IP reference %s can’t be updated",
   "dmNameUpdateFailed": "DM reference %s can’t be updated",
   "invalidTypeAssessErrorMessage": "We couldn't assess your Omnistudio components in the %s namespace. Select the correct namespace and try again",
-  "assessmentSuccessfulMessage": "Migration assessment for org %s is complete and reports are ready for review in the folder %s"
+  "assessmentSuccessfulMessage": "Migration assessment for org %s is complete and reports are ready for review in the folder %s",
+  "missingMandatoryField": "Missing mandatory field: %s for %s"
 }

messages/info.json

@@ -12,5 +12,6 @@
   "greetingOrgInfo": "Hello %s! This is org: %s",
   "greetingOrgInfoWithDate": "Hello %s! This is org: %s and I will be around until %s!",
   "hubOrgId": "My hub org id is: %s",
-  "allVersionsAppended": " and all versions will be migrated"
+  "allVersionsAppended": " and all versions will be migrated",
+  "errorRunningInfo": "Error occurred while running info command"
 }

messages/migrate.json

@@ -73,7 +73,7 @@
   "processingLwcsForMigration": "Processing LWCs for migration",
   "successfullyProcessedLwcsForMigration": "Successfully processed %s LWCs for migration",
   "lwcMigrationResults": "LWC migration results: %s",
-  "retrievingMetadata": "Retrieving metadata for %s in project path: %s",
+  "retrievingMetadata": "Retrieving metadata for %s for : %s",
   "creatingProject": "Creating project %s",
   "projectCreated": "Project %s created",
   "metadataRetrieved": "Metadata %s retrieved from %s",
@@ -247,5 +247,41 @@
   "migrationSuccessfulMessage": "Migration process for org %s is complete and reports are ready for review in the folder %s",
   "elementValueMapUnexpectedType": "ElementValueMap has unexpected data type '%s' for element '%s'. Expected object format.",
   "errorProcessingFormulaInElement": "Error processing formula for key '%s' in element '%s': %s",
-  "errorProcessingElementValueMap": "Error processing elementValueMap in Integration Procedure element '%s': %s"
-}
+  "errorProcessingElementValueMap": "Error processing elementValueMap in Integration Procedure element '%s': %s",
+  "startingOmniscriptPackageDeployment": "Starting deployment of omniscript customization package...",
+  "omniscriptPackageDeploymentStarted": "Omniscript package deployment started with ID: %s",
+  "omniscriptPackageIntegrated": "Omniscript customization package deployed successfully",
+  "pollingDeploymentStatus": "Polling deployment status for ID: %s (attempt %s/%s)",
+  "deploymentStatusUpdate": "Deployment %s status: %s - %s%% complete",
+  "deploymentInProgress": "Deployment in progress... Elapsed: %s, Estimated remaining: %s",
+  "deploymentCompleted": "Omniscript package deployment completed successfully in %s",
+  "deploymentFailed": "Omniscript package deployment failed: %s",
+  "deploymentCancelled": "Omniscript package deployment was cancelled",
+  "deploymentTimedOut": "Omniscript package deployment timed out after %s minutes",
+  "retryingDeployment": "Retrying deployment due to %s (attempt %s/%s)",
+  "deploymentRetryExhausted": "Maximum retry attempts (%s) exceeded for omniscript package deployment",
+  "extractingDeploymentId": "Extracting deployment ID from command output...",
+  "deploymentIdNotFound": "Could not extract deployment ID from deployment response",
+  "checkingDeploymentStatus": "Checking deployment status for ID: %s",
+  "deploymentStatusCheckFailed": "Failed to check deployment status: %s",
+  "deploymentStatusCheckExhausted": "Failed to check deployment status after %s attempts: %s",
+  "errorIntegratingOmniscriptPackage": "Error occurred while integrating omniscript customization package",
+  "omniscriptPackageDeploymentError": "Omniscript package deployment error details: %s",
+  "omniscriptPackagePathNotFound": "Omniscript customization package not found at: %s",
+  "asyncDeploymentStart": "Starting async deployment for source directory: %s",
+  "asyncDeploymentStatusCheck": "Checking async deployment status for ID: %s",
+  "deploymentProgressDetails": "Components deployed: %s/%s, Errors: %s, Warnings: %s",
+  "waitingForDeploymentCompletion": "Waiting for omniscript package deployment completion before proceeding...",
+  "deploymentSkipped": "Deployment skipped - autoDeploy is disabled or package.xml not found",
+  "deployOmniscriptPackageManually": "Omniscript customization package deployment failed. Please deploy the omniscript unmanaged package components manually before deploying your migrated metadata components. Please check the documentation <a href='%s' target='_blank'>link</a> for manual steps",
+  "deployComponentsManually": "Metadata Components deployment failed. Please deploy using generated package.xml manually using Salesforce CLI or Workbench. Check the logs for detailed error information.",
+  "omniscriptDeploymentFailedContinuing": "Omniscript package deployment failed, continuing with report generation. Manual deployment required.",
+  "deploymentFailedContinuing": "Deployment failed, continuing with report generation. Manual deployment required.",
+  "ensurePackageInstalled": "Please ensure omniscript customization package is properly installed: %s",
+  "packageDeploymentFailedWithError": "Omniscript package deployment failed after %s attempts. Error: %s. Please check deployment logs and org settings.",
+  "maxRetryAttemptsExceeded": "Maximum retry attempts (%s) exceeded for omniscript package deployment",
+  "deploymentNonRetryableError": "Deployment failed with non-retryable error: %s. Please review and fix the issue manually",
+  "deploymentTriggeredSuccessfully": "Please monitor your Deployment: %s using deployment status page in Org",
+  "omniscriptPackageDeploymentFailedReturnedFalse": "Omniscript package deployment failed - deployment returned false. This may be due to missing package, permissions, or deployment timeout.",
+  "omniscriptPackageDeploymentFailedWithMessage": "Omniscript package deployment failed: %s"
+}

src/commands/omnistudio/migration/migrate.ts

@@ -227,10 +227,12 @@ export default class Migrate extends OmniStudioBaseCommand {
     );
 
     try {
-      postMigrate.deploy();
+      await postMigrate.deploy(actionItems);
     } catch (error) {
       Logger.error(messages.getMessage('errorDeployingComponents'), error);
       Logger.logVerbose(error);
+      // Even if deployment fails completely, continue with report generation
+      // Action items are already added to the array by the deploy method
     }
 
     await ResultsBuilder.generateReport(

src/error/deploymentErrors.ts

@@ -0,0 +1,33 @@
+/**
+ * Custom error classes for deployment failures
+ */
+
+/**
+ * Error thrown when omniscript package deployment fails
+ */
+export class OmniscriptPackageDeploymentError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = 'OmniscriptPackageDeploymentError';
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, OmniscriptPackageDeploymentError);
+    }
+  }
+}
+
+/**
+ * Error thrown when general deployment fails
+ */
+export class DeploymentError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = 'DeploymentError';
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, DeploymentError);
+    }
+  }
+}

src/migration/NameMappingRegistry.ts

@@ -151,8 +151,9 @@ export class NameMappingRegistry {
   public getOmniScriptCleanedName(type: string, subType: string, language: string | 'English'): string {
     const originalName = `${type}_${subType}_${language}`;
     // Check if we have a mapping for this OmniScript first
-    if (this.omniScriptMappings.has(originalName)) {
-      return this.omniScriptMappings.get(originalName)!;
+    const mappedName = this.omniScriptMappings.get(originalName);
+    if (mappedName) {
+      return mappedName;
     }
     // Fallback to cleaning individual parts
     const cleanedType = Stringutil.cleanName(type);

src/migration/deployer.ts

@@ -3,6 +3,8 @@ import { Messages } from '@salesforce/core';
 import * as shell from 'shelljs';
 import { sfProject } from '../utils/sfcli/project/sfProject';
 import { Logger } from '../utils/logger';
+import { OmniscriptPackageManager, OmniscriptPackageConfig } from '../utils/omniscriptPackageManager';
+import { OmniscriptPackageDeploymentError } from '../error/deploymentErrors';
 
 export class Deployer {
   private readonly projectPath: string;
@@ -11,30 +13,78 @@ export class Deployer {
   private readonly omniscriptCustomizationPackageVersion = '250.0.0';
   private readonly username: string;
   private readonly messages: Messages;
+  private readonly omniscriptPackageConfig: OmniscriptPackageConfig;
+  private omniscriptPackageManager?: OmniscriptPackageManager;
 
   public constructor(projectPath: string, messages: Messages, username: string, authKey: string) {
     this.projectPath = projectPath;
     this.username = username;
     this.messages = messages;
     this.authKey = authKey;
+
+    // Configure omniscript package settings
+    this.omniscriptPackageConfig = {
+      packageName: this.omniscriptCustomizationPackage,
+      version: this.omniscriptCustomizationPackageVersion,
+    };
   }
 
-  public deploy(): void {
+  public async deploy(): Promise<void> {
     const pwd = shell.pwd();
     shell.cd(this.projectPath);
+
     try {
+      // Install dependencies including omniscript customization package
       if (this.authKey) {
         sfProject.createNPMConfigFile(this.authKey);
         Logger.logVerbose(this.messages.getMessage('installingRequiredDependencies'));
         sfProject.installDependency();
         sfProject.installDependency(
           `${this.omniscriptCustomizationPackage}@${this.omniscriptCustomizationPackageVersion}`
         );
+
+        // Deploy omniscript customization package separately first
+        await this.deployOmniscriptPackage();
       }
+
+      // Deploy the main project after omniscript package deployment succeeds
       Logger.log(path.join(pwd.toString(), 'package.xml'));
       sfProject.deployFromManifest(path.join(pwd.toString(), 'package.xml'), this.username);
     } finally {
       shell.cd(pwd);
     }
   }
+
+  private async deployOmniscriptPackage(): Promise<void> {
+    try {
+      this.omniscriptPackageManager = new OmniscriptPackageManager(
+        this.projectPath,
+        this.omniscriptPackageConfig,
+        this.username
+      );
+
+      const success = await this.omniscriptPackageManager.deployPackageAsync();
+      if (success) {
+        Logger.log(this.messages.getMessage('omniscriptPackageIntegrated'));
+      } else {
+        const errorMsg = this.messages.getMessage('omniscriptPackageDeploymentFailedReturnedFalse');
+        Logger.error(errorMsg);
+        throw new OmniscriptPackageDeploymentError(
+          this.messages.getMessage('omniscriptPackageDeploymentFailedWithMessage', [errorMsg])
+        );
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      Logger.error(this.messages.getMessage('errorIntegratingOmniscriptPackage'), error);
+
+      // Re-throw as OmniscriptPackageDeploymentError for consistent error handling upstream
+      if (error instanceof OmniscriptPackageDeploymentError) {
+        throw error;
+      } else {
+        throw new OmniscriptPackageDeploymentError(
+          this.messages.getMessage('omniscriptPackageDeploymentFailedWithMessage', [errorMessage])
+        );
+      }
+    }
+  }
 }

src/migration/postMigrate.ts

@@ -10,8 +10,10 @@ import { OmnistudioSettingsPrefManager } from '../utils/OmnistudioSettingsPrefMa
 import { OrgPreferences } from '../utils/orgPreferences';
 import { BaseMigrationTool } from './base';
 import { Deployer } from './deployer';
+import { OmniscriptPackageDeploymentError } from '../error/deploymentErrors';
 import * as fs from 'fs';
 import * as path from 'path';
+import { documentRegistry } from '../utils/constants/documentRegistry';
 
 export class PostMigrate extends BaseMigrationTool {
   private readonly org: Org;
@@ -180,21 +182,39 @@ export class PostMigrate extends BaseMigrationTool {
     }
   }
 
-  public deploy(): void {
+  public async deploy(userActionMessage: string[]): Promise<void> {
     if (!this.deploymentConfig.autoDeploy || !fs.existsSync(path.join(process.cwd(), 'package.xml'))) {
+      Logger.logVerbose(this.messages.getMessage('deploymentSkipped'));
       return;
     }
+
     try {
       const deployer = new Deployer(
         this.projectPath,
         this.messages,
         this.org.getUsername(),
         this.deploymentConfig.authKey
       );
-      deployer.deploy();
-      Logger.logVerbose('Deployment completed');
+
+      await deployer.deploy();
     } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
       Logger.error(this.messages.getMessage('errorDeployingComponents'), error);
+
+      // Handle specific omniscript package deployment failures by error type (not message)
+      if (error instanceof OmniscriptPackageDeploymentError) {
+        userActionMessage.push(
+          this.messages.getMessage('deployOmniscriptPackageManually', [documentRegistry.manualDeploymentSteps])
+        );
+        Logger.logVerbose(this.messages.getMessage('omniscriptDeploymentFailedContinuing'));
+      } else {
+        // Handle general deployment failures
+        userActionMessage.push(this.messages.getMessage('deployComponentsManually'));
+        Logger.logVerbose(this.messages.getMessage('deploymentFailedContinuing'));
+      }
+
+      // Log the specific error details for troubleshooting
+      Logger.logVerbose(`Deployment error details: ${errorMessage}`);
     }
   }
 }

src/migration/related/ExperienceSiteMigration.ts

@@ -94,7 +94,7 @@ export class ExperienceSiteMigration extends BaseRelatedObjectMigration {
       for (const file of fileArray) {
         progressBar.update(++progressCounter);
         if (file.ext !== '.json') {
-          Logger.logVerbose(this.messages.getMessage('skipNonJsonFile ', [file.name]));
+          Logger.logVerbose(this.messages.getMessage('skipNonJsonFile', [file.name]));
           continue;
         }
         try {