Merge branch 'release260' into metadataEnablementEnhancements

Author: shaurabh-tiwari-git

README.md

@@ -1,8 +1,10 @@
-# OmniStudio Migration Assistant
+# Omnistudio Migration Assistant
 
 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
+
+⚠️ 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]rc.43
+sf plugins install @salesforce/[email protected]dev.1
 ```
 
 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",
@@ -199,4 +199,5 @@
   "assessmentSuccessfulMessage": "Migration assessment for org %s is complete and reports are ready for review in the folder %s",
   "errorCheckingOmniStudioMetadata": "Error while checking the Omnistudio settings metadata status: %s.",
   "omniStudioSettingsMetadataAlreadyEnabled": "The Omnistudio Metadata setting is already enabled with standard data model. No need for migration."
+  "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",
@@ -200,7 +200,7 @@
   "skippingAsAngularDependencies": "(%s skipped due to Angular dependencies)",
   "noMetadataToDeploy": "No metadata to deploy",
   "missingMandatoryField": "Missing mandatory field: %s for %s",
-  "dataMapperMigrationFailed": "DataMapper migration failed for: %s",
+  "dataMapperMigrationFailed": "DataMapper migration failed for: %s ",
   "dataMapperNameStartsWithNumber": "DataMapper name '%s' starts with a number which causes migration issues. Proposed new name: %s",
   "integrationProcedureTypeEmptyAfterCleaning": "Integration Procedure Type '%s' becomes empty after name cleaning. Please provide a valid Type value.",
   "integrationProcedureSubtypeEmptyAfterCleaning": "Integration Procedure SubType '%s' becomes empty after name cleaning. Please provide a valid SubType value.",
@@ -247,6 +247,45 @@
   "generatedCustomLabelAssessmentReportPage": "Generated custom label assessment report page %s of %s with %s labels",
   "varDeclarationUpdated": "Variable initialization has been updated for target name",
   "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",
+  "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",
   "metadataTablesAlreadyClean": "OmniStudio metadata tables are empty",
   "startingMetadataCleanup": "Initiated cleanup process for Omnistudio metadata tables.",
   "failedToCleanTables": "Table cleanup failed: %s, Please contact Salesforce Support.",

src/commands/omnistudio/migration/migrate.ts

@@ -241,10 +241,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/dataraptor.ts

@@ -179,8 +179,6 @@ export class DataRaptorMigrationTool extends BaseMigrationTool implements Migrat
         continue;
       }
 
-      duplicatedNames.add(transformedDataRaptor['Name']);
-
       // Create a map of the original records
       originalDrRecords.set(recordId, dr);
 
@@ -210,9 +208,12 @@ export class DataRaptorMigrationTool extends BaseMigrationTool implements Migrat
 
       // Always add the response to track success/failure
       if (drUploadResponse && drUploadResponse.success === true) {
-        const items = await this.getItemsForDataRaptor(dataRaptorItemsData, name, drUploadResponse.id);
+        // Append the processed DM name into duplicateNames Map
+        const dataMapperName = transformedDataRaptor[DRBundleMappings.Name];
+        duplicatedNames.add(dataMapperName);
 
-        drUploadResponse.newName = transformedDataRaptor[DRBundleMappings.Name];
+        const items = await this.getItemsForDataRaptor(dataRaptorItemsData, name, drUploadResponse.id);
+        drUploadResponse.newName = dataMapperName;
 
         // Move the items
         if (!this.IS_STANDARD_DATA_MODEL) {
@@ -234,13 +235,17 @@ export class DataRaptorMigrationTool extends BaseMigrationTool implements Migrat
         }
       } else {
         // Handle failed migration - add error information
-        if (!drUploadResponse) {
+        if (!drUploadResponse?.success) {
+          Logger.logVerbose(
+            `\n${this.messages.getMessage('dataMapperMigrationFailed', [name]) + drUploadResponse.errors}`
+          );
+
           drUploadResponse = {
             referenceId: recordId,
             id: '',
             success: false,
             hasErrors: true,
-            errors: [this.messages.getMessage('dataMapperMigrationFailed', [name])],
+            errors: [this.messages.getMessage('dataMapperMigrationFailed', [name]) + drUploadResponse.errors],
             warnings: [],
             newName: '',
           };

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])
+        );
+      }
+    }
+  }
 }