Guidance Notes for Implementing Instance Migrator

Scope

The Instance Migrator application can be used to migrate data between any two ServiceNow instances.   These guidance notes relate to the migration of Foundation data only (recommended prior to the migration of other applications such as Incident, Problem, Change, Knowledge or Service Requests)

There are two versions of Instance Migrator:

 the Store version which is certified by ServiceNow and utilises the ITSM Bridge Instance Migrator application which is available on the ServiceNow store.

The Full (uncertified) version, includes migration of additional tables and allows new table mappings to be added as well as custom fields.  This version requires administrator level access to your ServiceNow instance.

The store version migrates all data (including attachments and images) to/from the following tables:

Companies, Locations, Departments, Schedules, Cost Centers, Buildings, Users, Groups, User Roles, User Group Members, Model Categories, Product Models, Stockrooms, all CMDB Base Items and related Asset records, and CI Relationships

The full (uncertified) version  includes the above plus the option to migrate any of the following using selected migration templates:

Organization Data, Workflow Definitions, Service and Product Catalogs, CMDB (multiple templates),  Incident & Problem, HR Service Delivery;

 

Best Practice Guidelines:

1. We recommend that you use this migration tool on a non-production instance for first use.  If using with a production instance we recommend that you take a full back-up of all foundation data prior to migration. In the unlikely event that you need to restore to a pre-migration state, you should have a reliable data backup to restore from;

2. No more than 50,000 case records should be migrated in a single execution run.  You can use the Source Count button on the Source Filtering tab on each mapping to check the record selection total then modify the Filter By Query if necessary to reduce the record count.  Refer to the Product User Guide for more information (Help->User Guide menu in ITSM Bridge client);

3. Before each subsequent execution, use the ServiceNow 'Clean Import Sets' function to remove previous import set data before running the application again;

4. For customers migrating to a domain separated instance, the full version also includes a mapping to create domains based on company records.  If you want to use this mapping, first setup your target server for domain separation by Company.  If not required you can simply remove this mapping from the migration project.

implementation Notes

Step 1: Activate the 'Insert Multiple Web Service' Plugin on your instance if not already active.  This will improve the performance of the data migrations for large data sets.

 
 

 

Step 2. If using the certified version, download the ITSM Bridge Instance Migrator application from the ServiceNow store and install on both source and target instances otherwise skip to step 3

Step 2a. Create a non-Admin ServiceNow user account for running migrations on both source and target instances.

Step 2b. Add the role x_semai_imig.user to this user account.

Step 2c. If you want to migrate groups and user/group membership data then you must edit the role x_semai_imig.user in Service Now and add the contained role user_admin

Step 2d. If you are installing on Jakarta or earlier platform, connect as System Administrator and open the list of records in the sys_security_acl table, then disable the ACL called sys_db_object.* (read).   Alternatively you can edit the role x_semai_imig.user and add the contained role itil.  This is required to read the source table field definitions.

Step 3: Check that you have the latest version of Java installed on your local machine; you can download the latest version from here: https://www.java.com

Step 4: Install, launch and license ITSM Bridge v3.8.x or later on your local machine; Download from here

Step 5: From ITSM Bridge select File->New Project from Template->ServiceNow->ServiceNow then select one of the following templates:

Instance Migrator (Store):  Certified version which requires non-Admin user access with the ITSM Bridge imig role (x_semai_imig.user)

Instance Migrator (Full): Uncertified version which requires Admin user access and gives full access to create new data mappings or custom fields.

Organization: Companies, locations, cost centers, departments, users, groups, etc.

Workflow Definitions: All workflow tables that make up a complete workflow definition;

Service & Product Catalog: All tables that comprise the service and product catalogs;

Incident and Problem: All Incident, problem, tasks, slas and related tables;

HR Service Delivery: All HR scoped application tables;

Step 6: Complete the fields on the new project connection window:

Project Name:  {Enter a name for your new project}

Location: {Browse for your preferred location or use default}

Source Server Type: Service Now

Target Server Type: Service Now

Source Connection URL: Enter the URL for your source ServiceNow source instance;

UserName/Password: Enter the username and password (user created in step 2 for certified version or admin user for Full version) 

Target Connection Server URL: Enter the URL for your Service Now target instance;

Username/Password: Enter the username and password (user created in step 2 for certified version or admin user for Full version)

 
Screen Shot 2018-04-23 at 10.38.47.png
 

Step 7: Use the test buttons to test connectivity, then click on the Save Authentication check-boxes to save the login-details; click on Create to create the project.

Note: You must have network access to your Service Now instance from your client machine over web-services. If necessary adjust your firewall settings to allow web-services to send/receive messages.  By default web-services uses network port 443 to connect. 

Step 8: Once the project is opened, select View Mappings List from the Project Menu;  This displays the full list of pre-defined table mappings for this project like this:

 
Screen Shot 2018-04-23 at 10.49.40.png
 

Step 9: Review the table mappings to ensure they meet your requirements.

Consult the Product User Guide (under the Help Menu) or visit the customer support portal at https://itsmbridge.zendesk.com if you need help making changes to the default table mappings;

Step 10: Select Execute from the Project Menu then enter values for the following where applicable:

Single Company: TRUE/FALSE; Set TRUE if you only want to migrate data relating to a specific company;

Company: The name of the company if Single Company is TRUE, otherwise set to ALL;

 

 
Screen Shot 2018-04-23 at 10.55.52.png
 

Note that the total number records migrated in a single execution should not exceed 50,000.  You can use the Source Count button on the Source Filtering tab on each mapping to check the record selection total then modify the query if necessary to reduce the record count.

Step 11: On the Migration Options Tab, set the Migration Method to Import Set or Import Set no Business Rules, (running with no business rules is generally faster than without but use with caution as some business rules may need to run to ensure data integrity);

 
Screen Shot 2018-04-23 at 10.56.56.png
 

Step 12: On the Advanced Tab,  if you are using the certified (Store) version, set the Import Set Application to 'Instance Migrator' and leave the 'Allow Import Set Web Service Synchronisation unchecked.

 
Screen Shot 2018-04-23 at 10.58.48.png
 

 

If you are using the Full version, set the Import Set Application to 'global' and select 'Allow Import Set Web Service Synchronisation'

 
Screen Shot 2018-04-23 at 11.21.26.png
 

Step 13: Click Execute and confirm execution when prompted.

Post Migration Activities

1. The progress of the migration is displayed in a separate window at the bottom of the screen.  After migration is complete, open the migration report from the Report menu to view details of which records were migrated for each table mapping.

2. For security reasons passwords cannot be migrated between instances.  User passwords must be reset on the target instance after the migration is completed.

3. The Instance Migrator application includes menus that provide access to the Import sets and Transform Maps used during the migration process. If you want the user with the custom role x_semai_imig.user to have access to these, then you must add the roles import_transformer and import_set_loader to the x_semai_imig.user role.

Supplementary Notes

Due to restrictions on access to Group and Group Role records in Service Now, these tables are populated using a direct update method which is not currently certified by Service Now.  There is no import set or transform map for these tables. 

For more information or assistance visit our customer support portal at  https://itsmbridge.zendesk.com

If you do not yet have a login to the customer support portal, visit itsmbridge.com/support to request a login.