Staging Guide for Cisco Unified ICM/Contact Center Enterprise & Hosted, Release 10.0(1)
User Migration Tool
Downloads: This chapterpdf (PDF - 1.32MB) The complete bookPDF (PDF - 4.21MB) | The complete bookePub (ePub - 1.21MB) | Feedback

User Migration Tool

User Migration Tool

The User Migration Tool (UMT):

  • Is a stand-alone Windows command-line application that performs migration in the granularity of a Unified ICM instance. It migrates only Unified ICM AD user accounts (config/setup and supervisors) and can be used during Technology Refresh (TR) upgrade to a new domain, or if the Unified ICM machines are moved to a new domain.
  • Finds the users in the Logger database and in all the security groups (Root, Facility, and Instance) each user belongs to; finds any additional users (not in the database) that are members of the Instance security groups; then generates a flat file (containing all users found) on the Logger system of the source domain. When the generated file is used on the Logger system in the target domain, the users are created in the new domain and added as members of the appropriate security groups. In addition, the database is updated with the migrated user information.
  • Must be executed on a Logger system. The Logger database must reside on Logger system in the source domain, as well as in the target domain.

    Note


    Microsoft .NET Framework 4 must be installed on the Logger system in both the source domain and the target domain. The main ICM installer installs Microsoft .NET Framework 4.
  • Performs migration of Unified ICM users from:
    • One domain to another.
    • One Unified ICM facility to another in the same domain.
    • One Unified ICM facility in one domain to another facility in another domain.
  • Serves the following purposes:
    • All users retrieved from the Logger database are migrated from the source to the target AD domain.
    • All AD user accounts that are directly a member of Unified ICM instance security groups are migrated from the source to the target domain.
    • The user information table in the Logger database in the target server is updated to point to the user accounts created in the target AD domain.
    • In the target domain, Unified ICM security group membership is updated for the users belonging to an external domain.

User Migration Tool Prerequisites

You must meet the following prerequisites before you run the User Migration Tool:

  • In the target domain, the Unified ICM OU hierarchy must be laid out and the Unified ICM security groups created for each Unified ICM instance before you run the User Migration Tool. This must be done by running the Domain Manager.
  • The exported Unified ICM registry from the source Logger system must be imported to the target Logger system.
  • The Logger database must be backed up from the source Logger system and be restored on the target Logger system before you run the User Migration Tool in the target domain
  • If there are users from an external domain that are a member of the Unified ICM security groups at the source domain, then the trust relationship needs to be established between the target domain and the external domain corresponding to the trust relationship that existed between the source domain and the external domain. This can be done using "Active Directory Domains and Trusts" tool.
  • If the Unified ICM server is moved to a new domain, it is the user's responsibility to make sure that the SQL Server is migrated to the new domain before you run the User Migration Tool.
  • In the source domain, the user who runs the User Migration Tool must be a domain user and a member of the local system administrator group.
  • In the target domain, the user who runs the User Migration Tool must have the following privileges:
    • The user must be a member of the local system administrator group.
    • The user must be a domain user.
    • The user must have at least one of the following privileges set:
      • a domain administrator
      • a member of the Cisco_ICM_Setup (Root) security group
  • For migration of the membership of Unified ICM users who belong to an external domain, credentials of an external domain user account with read privileges is required to access the external domain.

User Migration Tool Features

The User Migration Tool provides the following features:

  • Migrates AD user accounts from an old (source) domain to a new (target) domain to the same, or a different, Unified ICM facility.
  • Adds the user account in the corresponding Unified ICM security groups in the target domain.
  • Updates the Logger database with the Globally Unique Identifier (GUID) of the user account from the target domain.
  • Migrates the Unified ICM security group membership of Foreign Security Principals to the new domain.
  • Migrates the Unified ICM security group membership of user accounts to another facility in the current domain.

Migration Scenarios

Use the User Migration Tool in the following migration scenarios:

  • Technology Refresh upgrades on machines in a target domain.
  • Technology Refresh upgrades on machines in a different Unified ICM Facility OU in a target domain.
  • Moving machines with pre-installed Unified ICM components to a target domain.
  • Moving machines with pre-installed Unified ICM components to a different Unified ICM Facility OU in the target domain.
  • Moving machines with pre-installed Unified ICM components to a target domain and performing a Common Ground (CG) upgrade.
  • Moving machines with pre-installed Unified ICM components to a different Unified ICM Facility OU in the target domain and performing a Common Ground upgrade.
  • Migration of user accounts to a different Unified ICM Facility OU in the same domain.

Internationalization (I18n) and Localization (L10n) Considerations

In the localized version of Unified ICM, you can store the usernames in non-Western European characters (but not in Unicode) in the Unified ICM database, but the domain names are always in Western European character set. The User Migration Tool is able to perform user migration for localized systems.

Performance Considerations

The larger the number of users being exported or imported, the longer the operation takes.

During migration, there is an average memory growth of 10 MB for 1000 users due to Microsoft API memory leaks.

Security Considerations

The User Migration Tool connects to the Logger Database using Windows Authentication.

In the source domain, the user running the User Migration Tool must be a domain user and a member of the local system administrator group.

In the target domain, the user running the User Migration Tool must have the following privileges:

  • The user must be a member of the local system administrator group.
  • The user must be a domain user.
  • In addition, at least one of the following privileges must be set. The user must be:
    • a domain administrator,
    • a member of the Cisco_ICM_Setup (Root) security group,

For migration of the membership of system users who belong to an external domain with one-way trust, credentials of an external domain user account with read privileges (such as a domain user account) are required to access the external domain.

User Migration Steps

The User Migration Tool first runs in the source domain in Export mode. In this mode, it reads the users from the Logger database and the nine (9) security groups, then exports the user information (such as Username and UserGroupID) and the security group membership from the source AD folder. The UMT looks at the Logger database for each user found and looks at all nine (9) security groups to find the user's group memberships (the Setup and Config security groups in the Root, Facility, and Instance OUs). The user information found is added to the flat file.

For users belonging to the external domain, the User Migration Tool needs credentials to connect to the external domain. It looks for the users in the external domain and, if they are found, determines the security group membership for the user in the source domain and exports the information.

The UMT also looks at the Instance security groups (Setup and Config) to find any user accounts. If it finds any, that user information is added to the flat file as well.

The User Migration Tool then runs in the target domain in an Import mode. In this mode, it reads the file that was generated during Export mode and does the migration for all the users that belong to the source domain. During this mode, it looks for the users in the target domain and, if they are not found, creates the user accounts in the Instance OU. It fixes the group membership for the user and updates the database (if necessary) with the target domain name and the user's GUID from the target domain. In order to perform migration of the users belonging to an external domain, the User Migration Tool needs credentials to connect to the external domain. It looks for the users in the external domain and, if they are found, it fixes the security group membership for the user in the target domain.

The following are the steps involved when using the User Migration Tool.

Export Users from the Source Domain

Procedure
    Step 1   Back up the Logger database for each Unified ICM/CCE & Hosted instance using Microsoft SQL Server tools.
    Step 2   On the Logger system, for each installed Logger instance, execute the User Migration Tool in Export mode.

    An output file (umt_<Facility name>_<logger database name>.bin) is generated in the directory from which the tool is executed.

    Step 3   In a Technology Refresh upgrade scenario:
    1. Copy the output file to the Logger system in the target domain (to the folder from which the User Migration Tool will be run on the target system).
    2. Back up and export the registry on the source system.
    3. Check the log file for any errors.

    Import Users into the Target Domain

    Procedure
      Step 1   Shut down the Unified ICM/CCE & Hosted services if they are running.
      Step 2   If the domain name must be changed in a Common Ground upgrade scenario, see Change Domain Name and proceed to Step 4.
      Step 3   In a Technology Refresh upgrade scenario:
      1. Make sure the exported file exists in the Logger system.
      2. Restore the Logger database that was copied from the source Logger system using Microsoft SQL Server tools.
      3. Import the Unified ICM/CCE & Hosted registry exported from the source domain.
      Step 4   Run the User Migration Tool in Import mode for each Logger instance to migrate users.
      Step 5   (Optional) Run the User Migration Tool in verify mode to validate the migration.
      Step 6   For duplex Logger systems, run the ICMDBA tool to synchronize sides A and B.
      Step 7   Restart the Unified ICM/CCE & Hosted services if they were previously running.

      Change Domain Name

      To change the domain for a system, you must have the necessary permissions. To change the domain for all instances on the machine, complete the following steps:

      Procedure
        Step 1   Open the Web Setup tool.
        Step 2   Click the Instance Management tab.
        Step 3   Delete any instances and facilities that you do not want to use in the new domain.
        Step 4   Open the Domain Manager tool and ensure that the instances and facilities that are defined match what is actually on the machine. Failure to do this causes the Web Setup Change Domain operation to fail.
        Step 5   Select the instance to be modified, and then click Change Domain.

        The Change Domain page opens, displaying the currently configured domain and the new domain name of the machine.

        Step 6   Click Save. A query is sent to confirm that you want to change the domain.
        Step 7   Click Yes. If successful, you return to the Instance List page.

        If the instance does not exist, you must create it using the Domain Manager. Create the instance under the selected Facility in the new domain.


        User Migration Tool Modes

        The User Migration Tool functions in the following modes:

        • Export
          • Runs on the Logger system in the source domain.
          • Exports user account details from the Logger database and Instance security groups to a file generated in the same directory in which the tool was run. Names the exported file by combining the tool name (umt), the ICM Facility name, and the Logger database name (umt_<Facility name>_<Logger database name>.bin). The exported file contains the source domain name. It also contains Unified ICM instance specific parameters such as the Unified ICM Facility name, Unified ICM instance name, and Logger database name. This eliminates the need to specify these parameters during the Import mode.
        • Import
          • Imports user account details from the exported file.
          • Updates AD and the Logger database (if necessary).

            Note


            Due to the need to replicate new user accounts and AD security group memberships, you must wait 15 minutes after an Import is completed before running the User Migration Tool in Verify mode.
        • Verify
          • Runs on the Logger system in the target domain after an Import has been performed.
          • Validates the import.

        Note


        Help is available by entering usermigration.exe with either no arguments or the /help argument. This displays the command line syntax, and all modes and parameters are displayed.

        The User Migration Tool also generates a report file in the same directory that the tool is run. The name of the report file consists of the name of the exported file suffixed with ".rpt" (umt_<Facility name>_<Logger database name>.rpt).

        The report file contains the following information:

        • In the Export mode:
          • the name of the user account that is exported
          • all the Unified ICM security groups that the user account is a member of
        • In the Import mode:
          • the name of the user account that is created in AD
          • all the security groups added to the user account.

        In addition, every time the User Migration Tool is run, it generates a log file in C:\temp. The name of the log file contains the current time-stamp and is prefixed with "UMT" (for example: UMT2008619141550.log).

        The log file contains the User Migration Tool execution results in three categories:

        • Info
        • Warning
        • Error

        Runtime messages are also displayed in the command window while running the User Migration Tool.

        Related References

        Mode Considerations

        The username created can not log on for Internet Script Editor pages, without first logging into the new domain and then changing the password.

        Use your Windows logon to login using the AD account. A prompt appears asking to change the password. Provide a new password, then use the Internet Script Editor interface to login.

        Export Mode

        The Export mode exports the user information from the source domain and external domain into a file.

        When you run the User Migration Tool in Export mode, it exports the following information to the file:

        • Unified ICM Facility and Instance name
        • Logger database name
        • AD user account name and the domain name
        • Unified ICM security group that the user is a member of
        • UserGroupID from the Logger database

        The following table provides the command and parameter information for the User Migration Tool operating in Export mode.

        Table 1 Export Mode Syntax

        Command

        Mode Parameter

        Content Parameters

        UserMigration.exe

        /Export

        [/DBname <Logger Database name>]

        [/Facility <ICM Facility name>]

        [/Instance <ICM Instance name>]

        The Export mode command syntax is: usermigration.exe /Export /DBname <Logger Database name> /Facility <ICM Facility name> /Instance <ICM Instance name>.


        Note


        • For each external domain, the UMT command-line interface solicits the credential details to connect to that domain. If it fails to connect to the domain, it does not export the users belonging to that domain.
        • The parameter names are not case sensitive. The first parameter must always be the Mode Parameter. The order of the content parameters does not matter, as long as you include all of them in the command.

        Related References

        Import Mode

        The Import mode migrates users from the source domain, and external domain, to the target domain; and then updates the Unified ICM database.

        In the Import mode, the User Migration Tool gets the username from the input file, and searches for a user account in the AD, and creates one if not found. The user account is created in the Instance OU using the password supplied in the command-line interface. The password is set to expire to force the user to change the password during the next login.

        The User Migration Tool adds the user account to the Unified ICM security group based on the information from the exported file. The Logger database is then updated with the user account's AD Globally Unique Identifier (GUID) and the target domain name.

        The following information is imported from the exported file:

        • Logger database name
        • Unified ICM facility
        • Instance name

        In the Import mode, you can run the User Migration Tool with an optional /Facility parameter to import the user accounts to a different facility name. If the new facility migration is in the same domain:

        • The user accounts do not need to be created and the Logger database does not need to be updated.
        • Only the Unified ICM security group membership of the user account is updated.

        The following table provides the command and parameter information for the User Migration Tool operating in Import mode.

        Table 2 Import Mode Syntax

        Command

        Mode Parameter

        Content Parameters

        UserMigration.exe

        /Import

        [/FileName <Exported file name>]

        [/SetPassword <Default password for newly created AD user accounts>]

        [/Facility <Different ICM Facility name>]

        (Optional.)

        The Import mode command syntax is: usermigration.exe /Import /FileName <Exported file name> /Setpassword <Default password for newly created AD user accounts> /Facility <Different ICM Facility name>.

        In the Import mode, the User Migration Tool searches for a user account in the AD, and creates a user account if it doesn't find one. The user account is created in the Instance OU using the password supplied in the command-line interface. The password is set to expire to force the user to change the password during the next logon.


        Note


        The parameter names are not case sensitive. The first parameter must always be the Mode Parameter. The order of the content parameters does not matter, as long as you include them all in the command.
        Related References

        Verify Mode

        The Verify mode validates the import in the target domain by validating the AD and Unified ICM database migration done in the Import mode.

        The User Migration Tool performs the following verification with the data from the exported file:

        • Verifies the existence of the user account in AD.
        • Verifies the membership of the user in the Unified ICM security groups.
        • Validates the user's AD Globally Unique Identifier (GUID) and the domain name with the information in the Logger database (Unified ICM only).

        The command and parameter information for the User Migration Tool operating in Verify mode are provided in the following table.

        Table 3 Verify Mode Syntax

        Command

        Mode Parameter

        Content Parameters

        UserMigration.exe

        /Verify

        [/FileName <Exported file name>]

        [/Facility <Different ICM Facility name>]

        (Optional.)

        The Verify mode command syntax is: usermigration.exe/Verify/FileName <Exported file name>/Facility <Different ICM Facility name>.


        Note


        The parameter names are not case sensitive. The first parameter must always be the Mode Parameter. The order of the content parameters does not matter, as long as they are all included in the command.
        Related References

        Content Parameter Descriptions

        The following table provides descriptions of the parameters used by the User Migration Tool.

        Table 4 User Migration Tool Parameters

        Parameter

        Description

        /DBName

        The Logger database name.

        /Facility

        The Unified ICM instance facility name. When it is optionally specified during the import or verify mode, the User Migration Tool migrates users to a different Unified ICM facility.

        /Instance

        The Unified ICM instance name.

        /FileName

        The filename that has the user information exported from the source domain.

        /SetPassword

        The default password used for the user account created in the target domain. The User Migration Tool sets it to "Change password at next logon" so that the user is forced to change the password when they log in for the first time.

        Users from Trusted Domains

        It is possible that there are user accounts from trusted AD domains with authorization in the current domain. This is because the users are members of Unified ICM security group. The User Migration Tool performs migration of Unified ICM security group membership of such user accounts.

        For one-way trusted domains, the User Migration Tool needs Domain User credentials from the external domain in order to:

        • Connect to the external domain and find a user account.
        • Determine the Unified ICM security group membership in the current domain.

        The command-line interface to solicit credentials is as follows:

        1. Enter username on domain <DomainName>.
        2. Enter <password>.

        For users of a trusted domain, the Unified ICM security group membership is migrated if, and only if, the user is a direct member of the Unified ICM security group.

        For example:

        • ExtUser1 is a user account belonging to the trusted domain ExtDomainA.
        • ExtUser1 is a direct member of the Cisco_ICM_Setup and Cisco_ICM_Config security groups.
        • ExtUser1 is a member of the security group FOO.

        Note


        This restriction does not exist for users belonging to the current (source) domain.

        As a result, when the Unified ICM security group membership of ExtUser1 is migrated, only the Cisco_ICM_Setup and the Cisco_ICM_Config security groups are selected.

        In order to migrate Unified ICM security group membership of users belonging to a one-way trusted domain, there must be at least one user from that domain in the Logger database. Otherwise, the UMT skips migration for the one-way trusted domain.

        The UMT knows that it needs to connect to a one-way trusted domain only if it is referenced in the Logger database. Unless it connects/authenticates to the one-way trusted domain, it cannot determine whether or not there are any users from that domain that are a member of the Unified ICM security groups.

        User Migration Tool Troubleshooting

        This section provides troubleshooting information for the User Migration Tool.

        User Migration Tool Error Messages

        The following table provides solutions for User Migration Tool error messages.

        Table 5 User Migration Tool Error Messages

        Error Message

        Solution

        Cannot connect or authenticate to the Logger database.

        Verify that the Logger database exists and can be authenticated using Windows authentication.

        Cannot connect or authenticate to the Current domain.

        Verify that the Domain controller is up and running and the logged-in user is a member of the Domain Users group.

        Cannot add the user account to a Unified ICM security group.

        Verify that the logged-in user has the required permissions to run in Import mode. The logged-in user must be a Local Administrator and a member of the Setup security group in the domain. The specified password in the /Setpassword parameter must satisfy the domain's password policy requirements.

        Cannot create user account in the target domain.

        Verify that the logged-in user has the required permissions to run in Import mode. The logged-in user must be a local administrator and a member of the Setup security group in the domain.

        The exported binary file is corrupted.

        Run the User Migration Tool again on the source system to generate a new export file.

        The exported binary file could not be found in the directory where the User Migration Tool is running.

        Ensure that the exported file is available in the directory from where the tool is run.

        Failure while reading from the Logger database.

        Verify that the Logger database is not corrupted.

        Failure while updating the Logger database.

        Verify that the logged-in user has writable permissions for the database. The logged-in user must be a local administrator and a member of the Setup security group in the domain.

        Failure while reading from the exported binary file.

        The exported binary file is corrupted. Run the User Migration Tool in Export mode again on the source system to generate a new export file.

        Failure while writing to the binary file during export.

        Ensure that the logged-in user has write permissions in the current directory.

        One or more of the Unified ICM OU is missing in the current domain.

        Run Domain Manager tool and create Setup security groups, and re-run the User Migration Tool.

        One or more of the Unified ICM security groups do(es) not exist in the current domain.

        Run the Domain Manager tool and create the Setup security groups, then re-run the User Migration Tool.

        The logged-in user has insufficient credentials.

        The logged-in user must be a Local Administrator. The logged-in user must be a member of the Domain Users group in the current domain. For import, the logged-in user must be a member of Cisco_ICM_Setup security group.

        The Logger database is corrupted.

        Fix the Logger database and re-run the User Migration Tool.

        The system is either running stand-alone, or in a workgroup.

        The User Migration Tool must be run on a system that is in a domain.

        Mismatch of version between the User Migration Tool and the exported file.

        Same version of the User Migration Tool must be used for both modes of the migration.

        The User Migration Tool could not disable configuration changes.

        Disable the configuration changes manually, then run the tool.

        Incorrect usage of the User Migration Tool.

        The User Migration Tool cannot be run in Import mode under the same Unified ICM facility and domain that it was exported from. It must be run under a different Unified ICM facility in the same domain, or on a different domain.

        The Router system is not reachable for remote registry access.

        Ensure the hostname or IP address of the router is correct.