Migrating RM Unify Provisioning

Transition to a new Active Directory

Introduction

RM Unify can currently provision users from three different sources:

  • An Active Directory (AD) in a school (standard or CC4)
  • CSV files
  • MIS

This document details the process of linking existing RM Unify accounts to users in a new Active Directory.

Overview

Please take the following steps in order to link users in their new Active Directory to their existing RM Unify accounts.

  1. Download a CSV of users from RM Unify
  2. Add AD account name and (optionally) email address to the CSV
  3. Uninstall RM Unify AD Sync Service (v1 or v2) if this is currently installed
  4. Run the migration script (which will add details required for migration to your AD)
  5. Install and configure RM Unify AD Sync Service v2

1.Download a CSV of users from RM Unify

  1. Logon to RM Unify as a user with admin rights.
  2. Click Management Console>Sync users from CSV
  3. Click on “Generate a CSV of all my RM Unify users”

2.Add AD username and (optionally) email address to the CSV

In order to link existing RM Unify users to the new AD, the RM Unify AD Sync Service needs to know which existing RM Unify user each AD user corresponds to.

This is achieved by writing an extra user attribute to your AD, containing the RM Unify PersonID for the user (first column in the spreadsheet you just downloaded). We provide a PowerShell migration script to help with this (see step 4).

To prepare for running the PowerShell script, you will need to add the AD account name for each user to the CSV file you downloaded in step1:

  1. In column K of the CSV, write “ADAccountName”in row 1.
  2. For each subsequent row, write the AD account name (ie. Name attribute) corresponding to the RM Unify user.

When you start provisioning from AD Sync, the RM Unify usernames for all users will be updated to match the user’s SamAccountName in your AD. By default, their email addresses will also be updatedbased on the AD account name, provided the email address has not previously been assigned to a different Unify user.

For example, if you link existing Unify username JSmith123 with email address to user JSmith in your new AD, then the Unify username will be updated to JSmith@school with email address

Note: When connecting RM Unify to Office 365, if the brownfield user matching process was followed, any email addresses explicitly chosen at this point will be maintained for the user and not overwritten by the new email address.

  1. If you do not want email addresses to be updated as part of the migration, you will also need to specify email addresses in the CSV file by adding another new column:
  1. In column L of the CSV, write “Email”in row 1.
  2. In each subsequent row, write the email address you would like the user to have. If you wish to preserve their existing email addresses, you can quickly do this in a spreadsheet using a formula – for example, in Excel type “=CONCATENATE(B2,"@myschool.la.sch.uk")” in cell L2 (substituting @myschool.la.sch.uk with your school’s email domain) and copy this down to all the subsequent cells in column L.

Note: Column I of the CSV exported from RM Unify may contain the home email address for a user if they have set it to be used for password resets. This is a personal email address and not the address to be used for Office 365. Column I should be ignored when following this document.

  1. Carefully review the CSV file to ensure you have matched AD and Unify users correctly.
  2. Save the CSV file, ensuring you continue to save it in the CSV.

3.Uninstall RM Unify AD Sync if currently installed

  1. On your AD Sync server, uninstall RM Unify AD Sync from Add/Remove Programs (or Uninstall a Program). You do not need to uninstall RM Password Filter.
  2. Rename the residual folder(s) from:
    C:\Program Files\RM\RM Unify AD Sync or C:\Program Files\RM\RM Unify AD Sync Service
    to:
    RM Unify AD SyncOLD.

If the AD Sync server is using a 64-bit operating system you will find the residual folder in the location: C:\Program Files (x86)\RM

  1. It is important to rename the residual folder to ensure the new installation of RM Unify AD Sync in Step 5 creates a new database.

4.Run our migration script

Our migration script will add the RM Unify PersonID and, optionally, email address to your AD.

By default the migration script places the PersonID in an AD attribute called “rmCom2000-UsrMgr-uPN”. This exists in CC4 networks, but not in other networks. For other networks, you will need to choose an alternative unused attribute eg. “otherPager”. You can use ADSI Edit to find a free attribute – view properties on a user to see all attributes.

If the “Email” column exists in the spreadsheet, the script will also populate the AD “mail” attribute with the values from the “Email” column.

To run the script, you will need to logged in as a domain administration to either a domain controller with Windows Server 2008 r2 or better, or a domain-joined workstation with the Remote Server Administration Tools installed (these require Windows 7 or better).

  1. Save the script and your CSV file to a directory on the computer.
  2. Open a command prompt and type “powershell get-executionpolicy”.
  3. Make a note of the policy in place eg. RemoteSigned
  4. Temporarily change the policy by typing “powershell -ExecutionPolicy unrestricted”.
  5. Change to the directory containing the script (e.g. type “cd C:\Temp\” if the script is in C:\Temp\).
  6. Run the script using –WhatIf. This gives you a preview of what the command will do, rather than make any changes:

CC4: .\Set-RMUnifyPersonID.ps1 EstablishmentUsers.csv -WhatIf

Others: .\Set-RMUnifyPersonID.ps1 EstablishmentUsers.csv -ADAttribute otherPager –WhatIf*

* This assumes you would like to use otherPager as the attribute to store RM Unify PersonID on non-CC4 networks – change the command above to use a different attribute if desired.

The script will output some basic diagnostic information and save a more detailed log to log.txt in the current directory. Carefully review all output.

  1. If you are happy with the preview output, run the script again without the -WhatIf option.

By default, the script will not overwrite any existing values in the attributes it modifies. If you would like it to, add the -Force attribute to the command-line.

  1. Change the Powershell execution policy back to its original setting by typing “powershell -ExecutionPolicy xxxxx”, where xxxx is the policy you recorded in Step 3.

5.Install and configure RM Unify AD Sync Service

You will need RM Unify AD Sync Service v2 or better.

  1. Follow the instructions in the RM Unify AD Sync Release Note to install the software and run the configuration tool for the first time.
  2. If you are using CC4, proceed to Step 4.
  3. If you are not using CC4 (so have added PersonID to an attribute other than rmCom2000-UsrMgr-uPN), you will need to do the following after first running the configuration tool but before clicking on “new AD filter”:
  1. Close the configuration tool
  2. Open: C:\Program Files (x86)\RM\RM Unify AD Sync Service\RM.Networks.IdentityManagement.config
  3. Find the line that reads <add key="IdentityGuidSource" value="rmCom2000-UsrMgr-uPN" /> and modify rmCom2000-UsrMgr-uPN to the attribute you wish to use
  4. Save the file
  5. Reopen the configuration tool
  1. Create AD filters and role mappings as required
  2. If you have also specified email addresses for users, be sure to set the email attribute to “mail” when adding a new AD filter.

On first run the RM Unify AD Sync Service will find all users matching an AD filter and:

  • Any user in your AD that has an RM Unify PersonID in the specified attribute will be linked to their existing Unify account. Their existing Unify username will be updated to match their AD SamAccountName. If you did not specify an email address in the CSV and did not explicitly set an email address during O365 brownfield user matching, their email address will also be updated based on AD account names.
  • Any user in your AD that does not have an RM Unify PersonID in the specified attribute will be created as a new user in RM Unify.
  • Any user in RM Unify that is not associated with an AD user will continue to exist, but will not be updated in future. RM Support can assist you with instructions on how to delete these users at a later date if required.