/
wrangler_ WxC-DI Migration User Guide

wrangler_ WxC-DI Migration User Guide

Overview

The Wrangler WxC/UCMC migration tool supports migrations from an on premise or Domain Manager controlled UC cluster to Cisco’s WxC cloud platform. The tool supports the following migration topologies.

  • CUCM single cluster to single WxC-DI cluster and WxC-MT

  • Consolidation of Multiple CUCM clusters to single WxC-DI cluster (Map or Template Dialplan Migration options only) and or WxC-MT

  • Single CUCM+ single UCXN cluster to single WxC-DI cluster

  • Single CUCM to WxC-MT or a combination of WxC-MT and WxC-DI Cluster

  • Consolidation of Multiple CUCM clusters + single UCXN cluster to single WxC-DI cluster (Map or Template Dialplan Migration options only)

There are three Dialplan migration modes supported by the tool

  • Clone Dialplan Migration

  • Map Dialplan Migration

  • Template Dialplan Migration

Clone Dialplan Migration (Clone Source Dialplan)

The clone migration mode will perform a like for like migration of Dialplan and device objects from source clusters to the target clusters.

  • Need to create CMG/MRGL on target system that will be mapped

Map Dialplan Migration (Use Existing Target Dialplan / Do Nothing)

In a Map Dialplan migration, the Dialplan objects including Device Pools, CSS’s, Partitions* etc must be deployed to the UCMC manually prior to the migration. During the migration, the engineer performing the migration is then required to map the source Dialplan objects to the target Dialplan objects. The Wrangler tool will then transform device objects to use the target Dialplan objects and load the transformed objects into the target UCMC cloud.

  • Objects that needs to be mapped includes  PT/CSS/CMG/DP/LOC/REG/MRGL*

The MAP Dialplan migration does not migrate any Dialplan elements, it is presumed that the Dialplan is provisioned on the target cluster using BAT, Kurmi Sunrise, VOSS, Akkadian labs Site Builder or other management tool

For net new customers wrangler_ can be used to discover DN and e164 ranges https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Number-Ranges for input into the domain manager provisioning tools

Template Dialplan Migration (Push Dialplan From Templates)

In a Template Dialplan migration, Wrangler tool will deploy a standardised Domain Manager type or a Simplified Dialplan into the target UCMC cloud. Similarly to the Map Dialplan migration, the engineer performing is then required to map the source Dialplan objects to the target objects. The Wrangler tool will then transform device objects to use the target dialplan objects and load the transformed objects into the target UCMC cloud.

  • Default HCS T4 Dial plan is included but partner can also define template. 

  • Objects that needs to be mapped includes  PT/CSS/CMG/DP/LOC/REG/MRGL*

*All object types that require mapping for each migration type may be found under migrations menu item Mappings → Source Type Actions

Prior to Migration

Define Interfaces

Before starting the migration, the source and target CUCM, and if required CUC, interfaces must be defined. The rights required for these interfaces are defined here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2918973483/Yarnman+YM-PH+Interfaces#The-following-CUCM-permissions-are-required-for-wrangler_-WxC-DI-migrations

Important Note: For migration to WxC-DI, an account with User Rank 1 is required which will require a special request to Cisco as by default for DI migration an account with Rank 3 will be provided.

The process to define the interfaces can be found in https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2730393636/Yarnman+Administration#Interfaces

Important:

Target CUCM Configuration Requirements Pre Migration

Items that should be configured in target UC clusters prior to migration

CUCM target config pre migration requirements for all Dialplan options:

  • Call Manager Servers

    • These are created automatically with each CUCM node being installed

  • Call Manager Group (CMG)

    • The call manager groups need to be created to suit the target cluster layout, if the number of subscribers is changing between source and target clusters care must be taken to ensure each subscriber has the approriate number of registrations based on OVA size

  • Media Resource Group Lists (MRGL)

    • Media services, Media groups and Media Resource Group Lists need to be configured on the target cluster

  • Custom SIP Normalization Scripts

  • IP Phone Services

    • Such as Extension Mobility

  • UC Service Profiles

  • User Profiles

  • VPN Profiles and VPN Groups

  • CUCM Native Dialplans loaded other than NANP

    • Custom Dial Plan Tags

  • Any User and Network Locales other than default (ENG-US) loaded

  • Custom Roles and Access Control Groups Note required from v2.5.15

  • Mobile Smart Client Profiles

  • LDAP Directory configuration

  • CUCM Rank

Unity Connection target prerequirements

  • Unity Connection Voice Port Group

  • Unity Connection Call Handler Templates *

*Special note for Unity Connection Call Handler Templates. If any Unity Connection System Call Handlers use Message Recipient as User with Mailbox, a System Call Handler Template with this setting must be created in target for mapping of these Templates

Version 2.5.16 note

Unity Connection Default Dialplan objects, Search Space and Partition, are “Default Matched” to target Defaults and renamed as per the source objects, this is to accommodate when the system default Unity Partition and Class Of Service has been updated

Additionally if the cluster is LDAP integrated the following needs to be added

  • LDAP configuration in target cluster configured

  • LDAP Directory users to be synchronized prior to migration

Wrangler will update LDAP synchronised user configuration in the UCMC target but cannot add them

In addition to above, the following objects should be configured in UCMC target cluster pre migration when using Mapped or Template Dial Plan migration options:

  • CSS’s

  • Device Pools

  • Route Groups

  • Route Lists

  • Route Partitions

  • Transformation Profiles

  • User Groups

  • Voice Mail Pilot

  • Voice Mail Profile

  • Locations

  • Regions

UCXN

  • Connection Locations

  • Conversations

  • Fax Server

  • Mailbox Store

  • Phone System

  • Port Group Template

  • Port Group

  • Role

  • UCXN Server

  • SMPP Provider

  • Tenant

  • User Templates

The following objects are NOT migrated by Wrangler

CUCM all migration options

  • Annunciators

  • Application Servers

  • Application Users

  • Caller Filter Lists

  • Conference Bridges

  • Inter Cluster Service Profiles

  • IVR’s

  • Media Resorce Groups

  • MOH

  • MTP

  • Transcoders

  • Voice Mail Ports

  • Any None Default Network Locales

  • Any BAT Templates

Mapped and Template Dialplan migrations

  • Called Party Transformation Patterns

  • Calling Party Transformation Patterns

  • Route Patterns

  • Translation Patterns

 

Migration Process

General

During a migration, Wrangler goes through some high level steps that includes validation of the source data, during which issues may be encountered that needs resolving. These high level process steps are

  • Initial Discovery/Allocation/Validation

  • Site Allocation

  • Prepare Dial Plan (This step only when using the Template Dial Plan Migration)

  • Prepare/Clone Step

  • Load Step

Important Considerations:

●   Post Migration, Extension Mobility users are logged out from their end devices and must log in.

●   Passwords (if not using LDAP) and PIN’s are not migrated by Wrangler. The recommendation is to use BAT or such to set password and PIN in target cluster post migration.

Initiate Migration

To initiate a migration, from the Wrangler main menu, select Migrations, followed by + New Customer Migration

Select the Source and Target CUCM, and optionally UCXN, interfaces to be used for the migration, name the migration, optionally select the countries to be supported by the cluster and then select the migration mode, the schema followed by Save Migration & Start Discovery to initiate the migration process.

Interfaces to be used must be predefined in Administration App. Process to initiate these can be found in https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2730393636/Yarnman+Administration#Interfaces

Note that clusters and interfaces cannot be added after a migration has been started i.e. you cannot add a Unity publisher after the migration has been created

 

Note. The screen shot above depicts migration selections using Clone and Map Dialplan. If selecting the Template Migration option from Dialplan Configuration drop down, an additional drop down will appear to select required Dialplan that will be pushed to target by Wrangler as per below screen shot.

Initial Discovery/ Allocation/ Validation

During the initial Discovery phase, configuration is extracted from the source and target clusters, followed by an allocation and validation process where the imported data is validated against a set of predefined rules

The rules may be viewed/ modified under menu item Rules which may be found here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Rules

At completion of initial Discovery* process, a summary screen displays any issues and warnings detected during the initial Discovery process*, with the individual tabs providing detailed information on these.

*From Wrangler version 2.5.20, CUCM change notifications are supported which means that if a Rediscovery needs to take place at any time after the initial discovery has been successfully completed, Fast Re-Sync All may be selected that will detect all changes in CUCM’s since the previous full discovery was performed. (note that there is a dependency on notification queue depth in CUCM which is found in CUCM under Service Parameters)

 

Issues & Resolutions

(below description and samples apply to single cluster migrations - for multi cluster consolidation, additional info here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2789638145 )

The Issues and Resolutions tab displays items that MUST BE RESOLVED before proceeding. These items will include items such as mandatory mappings* of CUCM Call Manager, Call Manager Groups, Media Resource Lists, Duplicates etc. A complete list of validation rules and suggested resolutions of these can be found here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2757132303

The buttons on the right side of screen are to be used for required actions.

  • Blue button will bring up another screen with more detail of objects for action

  • Yellow button will perform an action directly

  • Green button (Mark Issue as Fixed) will not fix the issue but remove it from display only

  • Red button will disable the validation rule for the issue noting that the issues flagged here must be rectified before Disabling the rule as it may otherwise cause issues during the migration

 

Adjacent to the issues you may find an information button i - hover over it to view suggested resolutions

TIP - any Issues & Resolution issues flagged stating that the object/s such as Device Pools are not allocated to a site are better left unattended until after Site Suggestions/ allocation and Re Allocation performed

Object Target Mappings

If an object type is set to map in the source type mappings, as per below screenshot, these objects in the source cluster must be mapped to target, otherwise errors will occur during the migration for objects that have dependencies.

 

image-20241017-051737.png

CTI Configuration provisioned by other managers (UCCX/CUAC)

CTI Configuration that is added by other managers should be skipped such as

  • UCCX via the rmuser

  • CUAC

Note that the list above is not exhaustive as there are many 3rd party applications that perform provisioning - often for niche CTI applications

This includes

  • CTI ports

  • CTI route points

  • CTI remote destinations

As there are variable naming conventions for the systems listed for there wrangler cannot automatically identify this configuration so users should review and skip accordingly

 

If a map object with the same name exists in the target as in the source, Wrangler will automatically set the mapping

*For a Template Migration, map objects will not appear until after the Dialplan prepare step

For objects that require mapping, Selecting the Blue Button to Manually Resolve Unmapped will show the Target Mappings screen for the object/s. From here , the source object/s should be mapped to the required pre configured target cluster object.

Tip - The Mappings can, alternatively, be performed directly from the Target Mappings menu. More on Target Mappings can be found in the Administration Guide here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Map-Types

New Map Feature Wrangler Ver 2.5.20

To facilitate mappings with large number of objects such as phone button templates and for map type migrations, CSS’s, Partitions etc. mappings may now be exported, either using single object export or multi tab export for all mapping objects, to excel. This excel sheet can then be downloaded, all required mappings defined in the multi-tab spreadsheet which may then be uploaded with all defined mappings back to Wrangler

To use multi tab Excel export/ import

From Menu select Target Mappings, then from top right corner, select Export XLSX Report

The following displays

To export all mandatory mappings, select Map (mandatory mappings) button, then to download the sheet, select Download XLSX Export

Open the downloaded spreadsheet, Enable Editing if required

In the spreadsheet are multiple tabs, the first lists all objects that have not been mapped, the second then all target map objects, followed by tabs for individual objects requiring mapping.

For each of the Object types requiring mapping. In each of the tabs, complete the required map object in the Target Mapping name column corresponding to source object. When All complete save spreadsheet

To upload sheet to Wrangler, again select Target Mappings from Menu - > Export XLSX Report

 

Choose File to upload, then Submit which will upload the modified sheet and apply all the mappings in Wrangler

To use single object mapping using Excel, again under Target Mappings select the object that should be mapped, in sample below we have selected network locale

Select Download XLSX Report

Open the downloaded Excel sheet, then complete the Target Mapping Column as required, then save

From Target Mappings select the object network locale again, the Upload XLSX report, select the modified Excel sheet to upload and Submit which will upload sheet and apply mapping

 

 

Duplicates flagged may be resolved by :

  • selecting Ignore Source button which will leave the target duplicate object/s in UCMC cluster unchanged; or

  • selecting Update Target Object (default action) which will update the target UCMC cluster object/s with configuration from the source CUCM cluster object

 

Noting that the Ignore Source and Update Target Object buttons will bulk change all the objects of the same type flagged with the same action. If duplicate objects needs to be updated individually, select Review Duplicates button which will open a summary list of all the duplicate objects of that type, by selecting link from there, each object action can be selected. In below sample screenshot, the Review Duplicate adjacent to the 2 CUCM-PHONE-SECURITY-PROFILE was selected. If I now for example wanted to Ignore source for CUCM-PHONE-SECURITY-PROFILE Universal - Non-Secure, I select Edit link adjacent to this users from Source Cluster which will bring up Object details for the object

From here, Ignore As Source checkbox can be selected if this object is not to be updated in target - Save. If then all other users are to be updated in the target, select the Update Target button from the Issues & Resolutions summary screen which will set the 7 other users to be updated in the target.

Important Note : On the object screen as per below screenshot. In addition to the Ignore As Source checkbox, there is also a Skip As Source check box. The Skip as source function will skip this object for migration, but all dependent objects will need to be manually updated otherwise migration will treat this object as deleted. With the Ignore As Source function, this will still keep this object but will ‘ignore’ it, as there may be dependent objects.

Ignore As Source only works for duplicate objects. For objects that should not be migrated that are not duplicates, select Skip

The migration status of object may also be changed using menu items Bulk Changes for Skip, more on this here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Bulk-Changes and for Ignore as Source or Update Target using Reports-> Duplicate Objects here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Duplicates-Objects

When the issues under Issues & Resolutions tab have been resolved as required, proceed with issues under the !Warnings Tab

User Rank

New feature from wrangler- Version 2.5.24 is Rank validation. Rank is a feature that impacts three components in CUCM, LDAP Directory, ACG (Access Control Group) and CUCM User and is used to control user access to ACG’s .

In version 2.6.12 and later, ACG’s (Access Control Groups) default behaviour is changed to map rather than clone. Together with this we are introducing an ACG automap functionality that maps default source ACG’s to corresponding WxC-DI Partner ACG’s

This wrangler_ feature is implemented to support WxC-DI requirement that Rank value 5 should be used for enterprise users. In most CUCM deployments, Rank would be left at Default, which is 1 (the highest). Now if users have been configured with an ACG such as Standard CCM End Users with Default Rank configured, and is to be given a Rank value of 5 in WxC-Di then they will no longer be able to access the Standard CCM End Users ACG.

As part of the initial validation, wrangler_ validation rule will trigger to flag if there are users with user rank lower than 5, if LDAP directory in target is not configured with a Rank value of 5.

If these rules triggers, in target WxC-Di, configure under User Management → User Settings → User Rank a new user rank with value of 5.

 

If LDAP directory is used, configure LDAP Directory default rank with User

Rank 5, then back in wrangler_ Rediscover Migration

On completion of Rediscovery, the users with rank lower than 5 will again trigger - adjacent to this rule select the button to update Rank and map Default Rank to User Rank 5 in the target.

After update

When all validation issues have been completed , you need to Re-Validate Migration.

Rank ACG Cloning pre version 2.6.12

For WxC-DI migrations using Yarn1man with version earlier than 2.6.12, an ACG clone may be created as per below.

On completion of this next round of validations, there will be an ACG Clone Rule triggered.

Select the Clone ACGs button to clone all the currently used ACG’s with Default Rank to a new ACG with a Rank value of 5

As part of the migration all users will be transformed with a Rank Value of 5 and associated with the newly cloned ACG’s

Rank ACG behaviour Yarnman/wrangler_ version 2.6.12 and later

For version 2.6.12 and later migrating to WxC-DI only - the above ACG clone process is not performed, instead we have developed a process to Automap default source ACG’s to the WxC-DI Partner ACG’s as per below screenshot, thus now not requiring a Rank 1 account for the API interface credentials. (Note that this may still be required if custom ACG’s are required in the WxC-DI, as Cisco by default does not allow for the creation of these in the WxC-DI environment)

 

image-20241017-052513.png

 

Warnings

The Warnings tab displays items that have triggered the rules but are INFORMATION WARNINGS ONLY that may be attended to as required in source CUCM. Items that are highlighted under warnings can be missing e164 numbers, Intercom partitions and CSS's, Devices without Lines, Lines without Devices etc. To view the details of these objects, select the blue button which will take you to the item/s in question. If no action is required for the individual item/s, select Acknowledge and Continue (pre version 2.6.12 the Red Button + Disable Rule and Clear Issue) may be selected to clear the issue.

image-20250218-220659.png

Once Warnings are resolved, proceed to next Tab - Site Suggestions which is where we define the sites to be used during the migration 

Site Suggestions

Site suggestions provide a way to automate site creation based on naming conventions that exist in the source cluster

It is expected that users will need to setup the base mappings to suit source cluster configuration, the system default mapping table regexs are unlikely to suit non HCS dialplans

Most systems will have a naming convention that can be matched against with a couple of rules

•The matches can be on multiple objects types and multiple instances of an object i.e. 3 device pools, 2 regions and a location.

•Partition and CSS can be used for further matching and are required for Extension mobility only deployments

Mapping of source objects to define site

More on Mapping Tables here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Mapping-Tables.1

Site Suggestion Examples

Site Creation

To define a site, select the Green Create Site button adjacent to the site suggestion. The site suggestions are defined from the Mapping Tables. If the site suggestions does not meet requirements, the templates and regexes used to create them may be modified under menu item Mapping Tables which also provides a preview function to see outcome of templates before reallocating.

Once all sites have been created as required - select Re-Allocate Migration which will trigger allocation of objects to sites as per selection followed by a validation

On completion of this step, there will likely be another set of issues triggered for items such as objects that have not previously been allocated to a site, sites that have not a country code defined etc.

The UCMC object allocation process is responsible for allocating objects to sites. It does this in several passes as some objects depend upon the others being allocated first. The first pass is always using the mapping tables to allocate core site objects such as Device-Pools, Locations, Regions, CSS and Partitions. It does this by matching each template in the appropriate mapping table with siteId parameters against each site's source ID. Allocation will only proceed when sites have been created with correct source ID fields.

Subsequent passes utilize these first core objects and other objects in prior passes to allocate by reference. Many objects have multiple references to other site objects and may have conflicting allocation. A scoring system is utilized to tie-break based on the type of reference; the result is saved on the object for later review. After all main passes are complete several other functions may be executed, for example number-range generation, at the end of the allocation process.

Select the Issues & Resolutions Tab to resolve the remaining issues. These are mandatory to resolve and must be attended to before proceeding

 

TIP - if there are many objects with same issue such as Country Code in sample, rather than modify individually, they can be resolved using Bulk Change https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Bulk-Changes

For the Device Pool object flagged in sample above, there are a number of options how this can be solved.

Option 1 - select the blue button View Naming Convention which will trigger a preview of mapping table outcome showing the Device Pool not matching a template. To modify the templates globally, go to menu item Mapping Tables described further here https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Mapping-Tables.1 where the templates can be modified to match the DP so that it can be defined as a site.. This will modify templates for the current and all following migrations. If modification of template is required for the current migration only, the Override Table option highlighted in screenshot below may instead be used. Once modifications are completed, select Re-Allocate Migration

 

 

Option 2 - Create Site manually, then allocate the Device Pool to this site. Navigate to Sites, then select ‘Create New Site’

Populate Required Fields - then ‘Save New Site’

The created site is displayed - select Device Pools Tab

From Drop Down select Device Pool to add to the site, then ‘Save Changes’

Navigate to ‘Issues’ , the select ‘Re-Allocate Migration’

 

Option 3 - if the View link selecisted , the below screen will show, displaying which Device pool is impacted, this in turn has a link View to the Object Browser described in more detail herehttps://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Browse, that shows the detail of this Device Pool. We can here allocate this object to a site as per the screen shot below.

To Continue, Re-Validate Migration

Defining Sites to Migrate

We have now reached a stage where we need to define what sites to migrate. From the menu, select Sites. More on sites in Adminstration Guide https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Sites

Clone/ Map Migration view below screenshot

Template Migration View below screenshot

 

We can select the sites individually by selecting the O Waiting from Select column or we can Bulk Select all sites by selecting the Green Bulk Select button

Note from version 2.5.20 and as per screenshot below there is an additional row under site menu for Customer Objects where all source and target objects not allocated to site are visible

 

Now Select Ready from Main Menu

Phased migration

New feature 2.5.15

Phased migration enables the migration of sites individually or in batches. To assist in determining and understanding interdependencies prior to a phased migration, a new inter-site dependency report has been created where sites are placed in site groups and the report then determines the dependencies between the analysed site group and other site groups.

To use the interdependency report prior to a phased migration, sites need to be assigned to a site group which defines the individual sites or batches of sites migrating. This may be done by

  • Editing the site object and adding the site group

 

  • Using bulk change searching on ucmc-site and updating the sitegroup field

Note that site groups can have one or multiple sites included depending on the preferred migration strategy. For example if we are looking at migrating first a pilot site, then maybe 5 sites in next batch + remainder in the third batch, then the pilot site could be placed in Site Group 1, the next five sites in Site Group 2 and the remaining sites in Site Group 3. If we then run an Inter-Site-Dependency report for site 1 , any dependencies will be flagged to help understand issues that will need to be resolved prior to migration, which may also help in planning the migration strategy.

To verify the site group dependencies, use the inter-site dependency report https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2756444161/Wrangler+WxC+Administration+Guide#Inter-Site-Dependancies

For phased migration, it is recommended that a number of object types are moved to Before any Sites Loaded (BASL) and some objects also have their siteId set to null. This is best achieved using Bulk Changes. More on this here for version 2.6.14 or later https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/edit-v2/3362750471?draftShareId=9dc3877d-7137-4220-aeda-fb8b8d7707cd#Overview

 

If you are planning to migrate a subset of regions and location you will need to manually adjust the nested associated Locations and Regions via object browser

Site groups can also be used to select sites to migrate

 

 

Additionally, for phased migration, CUCM-EM (CUCM User Device Profiles) and CUCM-USERS that have NOT been allocated to a site post site creation and allocation steps, should be skipped if not required to be migrated or alternatively allocated to relevant site or a dummy site if they should be migrated.

To Skip CUCM-EM and CUCM-USERS for migration

  1. Select Bulk Changes from menu

  2. Select Create Bulk Change

yarnlab website