Migrating to a Domain Separated Instance

These notes are intended to provide a step-by-step guide on how to use Precision Bridge to migrate  data to a ServiceNow domain-separated instance.

INTRODUCTION

Service Now includes the concept of Domain Separation. All tables can be made domain-aware by adding the sys_domain field to the table. From Jakarta onwards, the OOB tables of Service Now already include this field for all tables that are required to be domain separated; therefore there should be no need to add this field to any OOB table. If any custom tables are to be included in the migration, you may need to ensure the sys_domain field is added to these tables.

The domain for a given record (where the table supports domain separation) is set when the record is inserted, and cannot be subsequently changed. The domain set on the record will be the same as the domain of the user creating the entry. 

PRE-REQUISITES

These notes assume that the target instance is domain separated using the default settings and that the domain separation table has not been changed.  If this is not the case, the migration can still be run but some modification to the steps outlined below may be required.

All Precision Bridge Projects used for migration to a domain-separated environment should include a restriction on the set of source records being migrated.  In particular they should be restricted by reference to the specified domain.  Each Form mapping must either:

1. Explicitly contain a Source Filter condition that restricts the source record set to the specified domain;
2. Have an Inclusion Filter defined, where the set of included parent records is itself restricted to records for a given domain.

IMPLEMENTATION NOTES

Data should be migrated one domain at a time. For each domain, the following needs to be created on the target instance:

1. A Domain record;
2. An Administrator User for this domain.

Step 1: Creating the Domain Entry:

1. Connect to the target Service Now instance as System Administrator
2. Navigate to Domain Admin -> Domains
3. Click ‘New’
4. Enter the following field values:
   1. Name:  Name of the company whose data you are migrating
   2. Type: MSP
   3. Parent: TOP
   4. Description: (optional) Users can access global records and those for <company name>
5. Click ‘Submit’

Step 2: Creating the Domain Administrator User:

1. Connect to Service Now instance as System Administrator
2. Navigate to System Security -> Users and Groups ->Users
3. Click ‘New’
4. Enter the following field values:
   • User ID: <Company Name>.admin
   • First Name: <Company Name>
   • Last Name: Admin
   • Managed Domain: checked
   • Password: define as appropriate
   • Domain: Select the domain created for this company
5. Click ‘Submit’
6. In the list of users, select the user just created
7. Click on the ‘Roles’ tab at the bottom of the page
8. Click ‘Edit’
9. Select the ‘admin’ role
10. Click ‘Save’
11.  

Step 3: Migrate Data for selected domain using Precision Bridge

WARNING: Once records have been migrated, their domain cannot be changed without deleting the records (a manual task) and running the migration again. 

Any mistakes in setting up the target domain and user may result in the data being migrated to the wrong domain, and potentially allow users operating in other company specific domains access to these records. 

Therefore it is very important that prior to migrating ANY records, you make sure that the correct domain is specified in the Query Filters and/or Execution Variables for the Precision Bridge project and that the user specified for connecting to the target instance belongs to the target domain.  Never use the global ‘admin’ user to migrate records – this will place the records in the ‘global’ domain, visible to all users.

To run the migration for a specific domain perform the following actions:

• Open Precision Bridge;
• Create a new project from a template or open your prepared migration project;

• Enter connection details for the Admin account for the source instance;

NOTE: If the source instance is also domain separated and you only want to extract records from the source domain, connect using an admin account that belongs to the source domain.

Enter details for the target instance using the user created in Step 2 above.

 

• Check the Query filters for each form mapping are set to restrict data selection by the domain you require.
• Execute the migration and enter the name of the domain if configured as a project variable.

Step 4: Post Execution Checks

Check the summary migration report, for any errors. The project can be re-run if necessary. 

Confirm that migrated records are only visible to users in the same domain.

To migrate data for a different domain, repeat steps 1 - 4