IMPORTANT: Based on customer feedback, it is important that you have the right level of support from Gainsight to use this feature effectively.  If you are interested in leveraging Cross-Org in your implementation migration, please contact your Gainsight Project Manager or Gainsight CSM for more information.

In Administration > Migration, Gainsight offers a new tool to migrate your Custom Object's schema, Reports, Rules, Playbook assets, data spaces, power lists, and reports from a source org to a target org. For example, if you have built and tested rules in your sandbox org, you may want to migrate them to your production org. This feature saves Admins valuable time and is enabled within your org by default. To read about most frequently asked questions(FAQs) in Cross-org Migration, see Cross-org Migration FAQs

With the May 5.6 release, Gainsight offers two new options in Migration, Re-run and Changeset File. 

  • Rerun migration jobs for different orgs: Admins can now re-run a migration job with the pre-selected configuration (selection of schema, metadata, and assets) to a different org. For example, if you have run a migration job from Org A to Org B, and wish to perform migration from Org A to Org C, you can use the re-run feature to perform the migration. In large enterprise implementations of Gainsight, Customers often perform multiple migrations from same source org to different target orgs with similar items. However, it is very difficult to remember the same items of migration. Rerun is a feature that will help you to solve this problem. A Re-run job remembers the items migrated in first migration and you can repeat that migration to different target org. 
Limitations  (click here to expand)
  1. Only Insert as new records will be considered for a re-run. 
  2. During a re-run, if the migrator identifies a record as auto-mapped in the current source/target org and the record is set to Insert As new in the job, the record will be ignored.
  • Download a changeset file when a migration job is complete: The changeset file contains the information of schema, metadata, and assets selected during a migration job. Only the records which are inserted as new in the target org will be captured in the changeset file. If you want to perform migration to a different org with the same schema, metadata, and assets, you can directly upload the changeset file and perform the migration. For example, if you have run a migration job from Org A to Org B, and wish to migrate the new records from Org B to Org C, you can use the changeset file and start the migration. In Administration > Migration screen, a new option By Uploading Config is introduced for this purpose.
Use Cases (click here to expand)
  1. In large enterprise implementation/change management, Customers often do multiple practice migrations before deploying to production and different teams are responsible for these deployments.  These teams need to hand-off from one team to another, in order to make this simple a changeset file is made available to the customer which will have the pre-selected configuration for Migration.
  2. The change set file can be downloaded after the migration is completed. 
  3. The items selected previously in each step will be shown with an orange dot. 
Limitations (click here to expand)
  1. Only successfully migrated items will be added to the changeset file.  
  2. For MDA Schema and Metadata Selection steps only “Insert as new” records are added to the changeset file. 
  3. Item update scenarios are ignored in the changeset file. 

Prerequisites

  1. In order to start the migration, oAuth user of the source and target org must have Gainsight Administration (Gainsight_Admin) permission set. 
  2. Custom fields and objects created in Salesforce needs to be migrated using Salesforce change sets.  
  3. The source and target orgs need to be on the same version of Gainsight. 
  4. MDA must be enabled in source and target orgs. 

List of Supported Items

Click on the following links to view the limitations in Migration. 

List of assets that can be migrated (click here to expand)
  1. Rules (Custom and Bionic Rules)
  2. Reports
  3. Playbooks
  4. Surveys   
  5. Dataspaces
  6. Powerlists
  7. Dashboard
  8. Email Templates (2.0 and 1.0) 
List of items supported in MDA Schema step (click here to expand)
  1. Only Redshift Custom Collections are migrated. 
  2. Lookup properties are not migrated and lookup fields are ignored. 
  3. Update keys configured are not migrated. 
  4. During migration, field display names will not be changed.
  5. Only Standard and Custom columns are considered for migrations. 
  6. During the update, Index property is not copied. 
  7. During update, the primary property cannot be overridden or copied. 
  8. During update when the target collection has data already, the default value will not be changed. 
  9. During update when the target collection has data already, if target column has different maxLength property, the column will be ignored from the update. 
  10. Formula (or calculated) fields will not be updated. It will always be created as a new field.
  11.  
  12. Custom to Standard object migration - custom objects created in a source org can be migrated to a target org (standard object) using the cross-org migration tool.
    1. To enable this migration, this parameter needs to be set in the source and target org in the tenantMaster > configs property: "MIGRATOR_ALLOW_STANDARD_OBJECT_MIGRATION" : "true"
    2. If you have any schema related to the custom object (in source org), be sure to map it in the MDA Schema step to migrate it to the Target org. 
List of items supported/unsupported items in the Metadata step (click here to expand)
  1. Picklist -  For all Global, Account, and Relationship Level Configurations following are supported: 
    1. CTA Status (Alert Status) 
    2. CTA Priority (Alert Severity)
    3. CTA Snooze Reason (Relationship Activity)
    4. CTA Reason (Alert Reason)
    5. Customer Status
    6. Customer Stage 
    7. Adoption Measure
    8. Milestones
  2. GSMetaInfo - All Account & Relationship Level
    1. Objective Categories
    2. Success Plan Types 
    3. Task Type
    4. Scorecard Metric (Sc Metric)
    5. Due Date Source Type
    6. Due Date Skip Option
    7. Success Plan Status
    8. CTA Group Category
  3. CTA Types - All the Global, Account, and Relationship Type CTA Types gets migrated. 
  4. Scorecard Metric - Account level scorecard metrics are migrated. 
  5. Scoring Scheme Definition - Account level scoring scheme definitions are migrated. 
  6. Application Settings Definition - While migrating Application setting object, the following properties get migrated. 
    1. Cockpit Related Configuration Parameters 
      1. Cockpit Configuration (JBCXM__CockpitConfig__c) 
  7. GSRelationshipType - Relationship Attributes and Card View Configuration gets migrated. If you select any metadata related to a Relationship Type will also migrate the Relationship Type. For a Rel Type to get migrated you have to select at least one related metadata. 
  8. Scorecard Configuration 
    1. What We Migrate
      1. Account level scorecards (1.0) metrics and scorecard scheme definitions are migrated. 
      2. Scoring Scheme Mapping - Update the configuration related to whether Color/Number/Grading scheme is enabled. 
    2. What We Don’t Migrate
      1. Configuration option “Load Snapshot to Engagement every month” will not get updated. .
List of items supported in the Choose Assets step (click here to expand)

Rules

Custom Rules created on Data Spaces are not supported for migration. 

  1. SFDC Custom Rules
    1. SFDC rule will be migrated to target org. 
    2. All incomplete rules (with no setup/action exist) are ignored. 
    3. Rules with CTA Action: If a playbook is assigned in Setup Action step, that particular playbook will be automatically migrated.
  2. MDA Rules   
    1. Load to MDA action is supported.
    2. All the objects used must exist in the target org with the same name.
    3. All the fields used in the rule must exist in target org with the exact field name and type.
    4. Any lookup object or field used in the rule must have the same lookup object and field in target org. 
    5. Lookup up to three-levels is supported. 
  3. Bionic Rules can be migrated. Load to Feature and Set Score (1.0) action type is not supported. If a rule contains this action it will not be migrated. 
  4. Rules having Set Score 2.0 as an Action Type can now be migrated.


Reports

  1. MDA Reports
    1. Orgs must have Integration with HAPostgres. 
    2. MDA object and its fields get validated during migration. Migration happens only if MDA object is successfully validated. 
    3. Object validation include ObjectName, used Object fields(fieldName), dataType, and joins.
    4. Duplicate Reports of the same name will not be migrated (validation from Report API). 
  2. SFDC Reports    
    1. Orgs must have Integration with HAPostgres. 
    2. SFDC object and its fields get validated during migration. Migration happens only if SFDC object is successfully validated.
    3. Object validation include ObjectName, used Object fields(fieldName), dataType, and lookups
    4. Dataspace reports are supported. 
    5. Migration happens only if object validation is successful.
    6. Owner field information is removed if there are any.
    7. The "Created By ID" when the user chooses from the drop-down in source org, after migration UI throws a popup saying - ID does not exist, remove or update filter. However, migrated report opens successfully.
  3. Data Space Reports
    1. Reports of type Data Space, which are present in source and Target org can be migrated. 
    2. You can also migrate dataspace reports from source to target org directly if it is not present in target org. 
    3. Reports which can include five level join fields created in data space.
    4. If report includes a data space, it will also be migrated. 
  4. Picklist and Multi-picklist values are supported.
  5. MDA/SFDC/Data Space report, if a report with the similar name is already present in target org, it cannot be migrated. 
  6. An update in data space requires an update in the associated reports, otherwise, the migration will fail. 

Powerlist

  1. Salesforce, MDA, and Dataspace powerlist is supported.
  2. Schedule information isn’t passed along with migration.
  3. For Data space powerlist, if the dataspace is present in target org or if it is not part of the migration process then the data space will be migrated along with the Powerlist.
  4. Relationship Type Powerlist isn't supported yet for Migration.
  5. Account lookup holder cannot contain a field with join. In this case, Migration can fail. If we have an accountid mapping and having joins in recipient fields of Powerlist of minimum two-level joins migration of the PL will fail. 

Dashboard

  1. The dashboard is supported in migration.
  2. All the dependent reports are also fetched and migrated along with dashboard. 
  3. If MDA report is already present, then it will be Verified in target org. 
  4. MDA, SFDC, Dataspace Reports are supported. Gainsight also supports Widgets of SFDC type in Dashboard. 
  5. If any report fails, the associated dashboard migration fails.

Data Space

  1. Data Space on SFDC objects is supported in migration.
  2. All the dependent reports also fetched and migrated along with dashboard.
  3. Unique name constraint applied, so duplicate data space (same name) cannot be migrated.

Playbooks

  1. All type of playbooks are supported (Account + Relationship)
  2. Playbooks get migrated along with the tasks if all the dependencies are met.
  3. Playbooks containing Email type tasks can now be migrated.

Surveys

  1. Multilingual Surveys that include static resources (languages) are now migrated when you are migrating a Survey.
  2. Surveys in any stage are migrated to the draft stage in the target org. 

 

Procedure

To migrate assets from a source org to a target org: 

  1. Navigate to Administration > Migration
  2. Click + MIGRATION > New. You can either select New (new migration) or By Uploading Config (uploading a configuration file from re-run job).
  1. Under Authenticate, enter the details of the target org:
    • Username: The username of the target org.
    • Password: The password of the target org.
    • (Optional) Security Token: The security token of the target org.
    • Organization Type: Select Production or Sandbox based on your requirement.
Note: You can also authenticate the target org using a token, for more information, see Cross-org Migration
 
  1. Click AUTHENTICATE TARGET ORG. The MDA Schema screen appears. While migrating assets to a target org, you can also migrate the schema of custom objects or fields in an object. Alternatively, you can skip the schema migration step using SKIP & NEXT button.  

  1. In the MDA Schema screen, select a collection type. The list of custom object's schema appears in the left-pane. 
  2. In the Select a target object list, select an object to which you intend to migrate the schema. Once you select the target object, the list of Source Fields and Target Fields appear on the page. 
    1. Fields of the same datatype will be matched automatically. 
    2. If any field is unmapped, you can either insert the schema as a new row or replace the existing schema. Select an option from the drop-down in this case. 

Note: Formula fields have to be mapped manually if the mapping did not happen automatically. If the formula field has any dependent fields, the dependent fields also have to be mapped manually. 

  1. Click NEXT. The Meta Data Selection & Mapping screen appears. Metadata related to Reports, Playbooks, and Rules is displayed in this screen.

 

  1. In the Metadata Selection & Mapping screen, select an Entity Type. Once you select an option, the metadata associated with the assets appear. 

Note: With this release, if there is a metadata dependency or asset dependency during migration, those metadata/assets are also migrated during the process. For example, if a playbook is dependent on a CTA Type, Milestone, and Reporting Category, then while migrating the playbook, the CTA Type, Milestone, and Reporting Category will also be migrated. 

  1. To start mapping the fields, select a metadata item from the left pane. Data in the Source Value and Target Value columns appear. 
  2. After selecting an item, you can update/replace the metadata of the target org in this screen. You can perform either of the following actions:
    • If values are equal: If the metadata values of the source org and target org are equal, the values will be mapped automatically. In this case, you can also update the metadata of fields associated with the target value. 

 

  • If values are not equal(Insert new record): If the metadata values of the source org and target org are not equal, you can either insert the source value as a new record in target org or replace the existing value (using Insert as New option under the Target Value column).  
  • If values are not equal(replace existing record): If you want to replace the target value, select the target value from the drop-down. While replacing the target value you can also replace the metadata of associated fields. Select the check box under UPDATE ASSOCIATED FIELDS column. 
  1. After updating/replacing the metadata, click NEXT. The Choose Assets screen appears. 

  1. In the Choose Assets screen, select an asset from the list. You can select Playbooks, Rules, Reports, Data Spaces, Dashboards, and Power Lists.  
  1. Select the required assets and click NEXT. The Migrate screen appears.
  2. In the Migrate screen, provide a job name and review the list of MDA Schema, Configurations, and Assets to be migrated.
  1. Click MIGRATE. The migration process starts, and once it’s completed you will receive an execution report via email.
  2. Click the job name to see the execution log and job status.
 
  1. You can view the migration log in the Execution Log section. You can also Re-run the migration job or download the changeset file for further use. 

Re-run a Migration Job

Use the following procedure to re-run a migration job: 

  1. Select a migration job that is completed. 
  2. Click Re-run. The Migration screen appears.
  3. Enter the credentials of the target org to which you intend to migrate and click Authenticate Target Org. The MDA Schema screen appears. 

  1. Select the schema items and click NEXT. The items selected in the previous migration job are indicated with an orange dot. You can also select more items if required. 
  2. Select the metadata items in this screen. You can also use Entity Type drop-down list to select filter the metadata items. 
  3. Click Next. The Choose Assets screen appears. 

  1. Select the required assets in the Choose Assets screen and click Next. The Migrate screen appears. 
  2. Review the configuration displayed in the Migration screen and click Migrate. You can also go back and select more items if required. 

Run a migration job using a Changeset file

Use the following procedure to run a migration job using a changeset file: 

  1. After a migration job is complete, click Download Changeset File. A mig file gets downloaded. 
  2. Now log on to the target org that you’ve used in migration. 
  3. Navigate to Administration > Migration screen. 
  4. Click + Migration > By Uploading Config. The New Migration - Upload Configuration dialog appears.

  1. Click Browse File and select the mig file. 
  2. After successful processing of the migration file, the Authenticate Screen appears.
  3. Enter the credentials of the target org to which you intend to migrate and click Authenticate Target Org. The MDA Schema screen appears. 
  4. Select the schema items and click NEXT. The items selected in the previous migration job are indicated with an orange dot. You can also select more items if required.

  1. Select the metadata items in this screen. You can also use Entity Type drop-down list to select filter the metadata items. 
  2. Click Next. The Choose Assets screen appears. 

  1. Select the required assets in the Choose Assets screen and click Next. The Migrate screen appears. 
  2. Review the configuration displayed in the Migration screen and click Migrate. You can also go back and select more items if required. 

Authenticate target org using a token 

A new way of authenticating the target org is introduced in Cross-org Migration tool. Using Token option, you can generate a token for the target org and use it to start the migration process. This way of authorizing the target org can be used if you are unable to authenticate using the conventional way (username and password). The org Id of target org is used to generate the token.

  1. Click + TOKEN. The Authorization Token dialog appears.

  1. Type the target org Id and click Generate Token. The token will be generated.
  2. Click Copy to copy the token to clipboard. You can use this token and start the migration process.

  1. Click Migration Token in the cross-org migration tool and paste the generated token.
  2. Click Authenticate Target Org. If the authentication is successful you will be migrated to MDA Schema page directly.