CMS Migration Tool

The problems being solved

The very early CMS architecture presented a simple but limited scheme for addressing a Space; a Space could have a Primary or Secondary address and a single PIN/passcode.

It became apparent quite quickly that this was very limiting; there were requirements for multiple ways of joining a Space with different types of Participants who might or might not have a PIN/passcode with different in-call characteristics per role (e.g., video quality, lobby behaviour, video layout etc).

The solution taken by the CMS architects was to introduce the notion of 'access methods' onto the Space software model. 'Access Methods' made it possible to define URIs, Call Ids and PIN/passcodes to Spaces along with a Call Leg Profile. The URI/Call Id or PIN/Passcode identified different types of Participant and the Call Leg Profile provided the in-call properties for the Participant (video quality, lobby behaviour, video layout etc.). Pretty cool and it provided a great deal of flexibility in how different types of Participant might use a Space.

The irony of all this coolness is that the Cisco products didn't exploit it for a long time, until recently with WebApp or CMM (2021). Spaces created by CMS, CMA or TMS all use the legacy model; very simple calls.

VQ will work with the legacy Space model; you'll see less functionality but we play as nicely with as is possible. If you want to exploit the power of CMS fully, switch to 'Access Method' mode. This document explains how to use the CMSMigration utility that will do the work for you.

Please note that even if your Spaces were created using one of the new models outside of VQCM, you might still want to migrate them to VQCM for it to have the ownership of those Spaces. This will prevent them from being classified as “discovered” Spaces, which have limited functionalities.

As usual with VQ, the first version of this tool will be a command line tool; it'll evolve over several generations and then we'll move it into the user interface.

Read on....

The VQ provided CMS Migration tool enables the user to configure their system such that VQCM can take ownership of (and hence manage) existing Spaces on CMS.

In particular it:

  • Creates Space templates on VQCM based on the existing CMS equivalent, which are:

    • callProfiles and callLegProfiles defined at the global and tenant scope for the legacy templates

    • coSpaceTemplates and accessMethodTemplates, which also contain the above, and are linked to the LDAP group by the ldapUserCoSpaceTemplateSources

  • Saves the data of the existing Spaces to be migrated, for example the PIN and Secret

  • Migrates the manually created Spaces, or “non-LDAP” Spaces to VQCM, which will also recreate them in CMS

  • Restores the saved data to all the migrated Spaces that are now on VQCM

Configuration

The tool has three different modes, which can be configured and selected from the configuration file:

  1. Migrate LDAP Spaces

  2. Migrate “simple” non-LDAP Spaces. These are the legacy Spaces mentioned above

  3. Migrate “advanced” non-LDAP Spaces. These are the new generation of Spaces created from WebApp or CMM, which can also use access methods

NOTE: you can run the tool multiple times using different modes, for example to first migrate the LDAP Spaces, then the non-LDAP Spaces.

In the directory that contains the tool, you will find a file called “config.json” which should look like this:

 {
  "VQCM": {
    "Fqdn": "VQCM_FQDN",
    "Authorization": {
      "LoginFqdn": "VQCM_LOGIN_VQCM",
      "Client": {
        "ClientId": "CLIENT_NAME",
        "Secret": "CLIENT_SECRET"
      }
    }
  },
  "CallBridge": {
    "Ip": "CMS_IP",
    "Https": true,
    "Username": "CMS_USER",
    "Password": "CMS_PASSWORD"
  },
  "Settings": {
    "LdapSpaces": false,
    "CmsCoSpaceTemplateId": "CMS_TEMPLATE_GUID_IF_MIGRATED",
    "SpaceTemplateId": 0,
    "DefaultOwnerId": 0,
    "Filters": {
      "TenantId": "",
      "Filter": ""
    }
  }
}

The different available settings are described in the table below:

Parameter Description Note
Fqdn The FQDN for VQ Conference Manager The FQDNs can be found on the home page of CM-Admin
LoginFqdn The FQDN for VQCM’s Identity Server  
ClientName The Client Id configured in CM-Admin  
Secret The Secret associated to the Client configured in CM-Admin  
Ip The address of the CMS server/ This should be the main CMS node with priority 0 in VQCM

You can use a FQDN as well.

You can also add the port at the end if it differs from the default of 443. For example: IP: 192.168.1.10:445

Https Use https or not Values: true or false
Username Username of the CMS user to use. This user should have API access  
Password Password of the CMS user  
LdapSpaces Used to select if we are migrating LDAP Spaces or non-LDAP Spaces. Values: true or false
CmsCoSpaceTemplateId

Id (guid) of the CoSpaceTemplate to migrate from CMS. This will cause that template to be migrated to VQCM, and will also filter the Spaces on CMS to only migrate the non-LDAP Spaces created with that template

Optional. This setting only affects the non-LDAP Spaces migration.

If left empty, all the “simple” non-LDAP Spaces will be migrated.

Note that we will also try to migrate the “advanced” Spaces, but it is less likely to succeed if we do not know what template they are using

SpaceTemplateId

Id of the VQCM Space Template to use when creating the sSpaces on VQCM.

Will be overwritten by the migrated CoSpaceTemplate if specified

This ID can be found in the URL when editing a Space template in VQCM, for example:

https://testcm.vq.lab/#/system/space-template/edit/3

-> ID of the “Managed Meeting” Space template is 3

DefaultOwnerId ID of the VQCM user to assign as the Owner of the new Spaces if none is found

This ID can be found in the URL when searching for a user in VQCM, for example: https://testcm.vq.lab/#/tenant/2/coapps/user/28?customerId=2

-> ID of the user is 28, and it is on tenant with ID 2

TenantId ID (guid) of the CMS tenant used to filter the Spaces to migrate. Only Spaces on that tenant will be backed up and migrated

This ID can be found at the /api/v1/tenants API endpoint in CMS.

This corresponds to the “tenantFilter” parameter on the /api/v1/coSpaces API endpoint in CMS

Filter String used to filter the Spaces to migrate. This filter can match multiple fields on the Space (Name, Uri,…) This corresponds to the “filter” parameter on the /api/v1/coSpaces API endpoint in CMS

Migration process

Prerequisites

Before starting the migration process, make sure you have the following:

  • Snapshot of the VQCM VM. This will require access to VMWare

  • Backup of the database master CMS node. Make sure you move it off the CMS

NOTE: You can identify the database master node by running: database cluster status

  • Credentials for VQCM, CMS and LDAP server. Please verify you have up-to-date credentials, as you don’t want to discover you don’t halfway through the process (it's happened before!)

Migrate LDAP Spaces

Converting CMS LDAP Spaces from 'legacy' mode to 'access method' mode:

  • Step 0: Edit the “config.json” file to have the correct configuration, in particular “LdapSpaces” set to true

  • Step 1: Create VQ Space Templates for the CMS Global and Tenant profiles
  • Step 2: Save all the details for LDAP created Spaces on CMS
  • Step 3-4: Bring CMS nodes into VQ and get the LDAP and Tenant Settings from CMS into VQ
  • Step 5: Remove the LDAP created Spaces from CMS (don't worry, they were backed up at step 2)
  • Step 7-8: Recreate the Spaces from LDAP with access methods
  • Step 9: Update all of the Spaces recreated with their original PIN, Call Id and Secret values from step 2

To migrate a system the following process should be used:

  1. Use the tool to migrate the global and tenant level callProfile/callLegProfiles to template roles in VQCM

    1. CMSMigrationTool -o createTemplate

    2. Once this tool has completed your system should include a new set of Space Templates (named after the tenant and LDAP config) that can be renamed and used to create Spaces

  2. Backup the existing LDAP imported Spaces by running:

    1. CMSMigrationTool -o backup

    2. This will create a "backup" folder on the system which contains LDAP imported Space information from the call bridge that will be used to restore PINs and Secret values

    3. Once the system has been completely migrated to VQCM and there are no more issues this folder can be removed

    4. The backup process might take some time; as a general rule, allow 30 seconds per hundred Spaces

  3. Using VQCM, add the call bridges nodes from the CMS cluster and set their states to online. This will result in the LDAP and Tenant details from the CMS cluster being discovered and populated in VQ

  4. Using VQCM, update the system's LDAP configuration pages:

    1. Check (set) the 'VQ creates Spaces' check-box

    2. Save the LDAP configuration settings

  5. Using VQCM, perform a 'destructive import' to remove all of the Spaces bound to LDAP. Repeat this process for each Tenant if there are multiple Tenants:

    1. A 'destructive import' is performed by changing a value on the LDAP filter that will result in no matches on the LDAP data search which in turn results in all users (and Spaces) associated with this LDAP config being deleted from VQ and CMS

    2. A simple (and safe) way of doing this is to add an 'x' to an existing filter; this causes the filter to not match

    3. Save the LDAP config settings and run an import

  6. Using VQCM, remove the change you made to the LDAP configs (removing the 'x' if that's the approach you took). Save the LDAP config change

  7. Using VQCM, update the system's LDAP configuration settings to select the Space Template to be used when creating the Space associated with each user in the LDAP config group. Note that the CMSMigration utility at step 1) will have created VQ equivalent Space Templates for the Global and Tenant profiles from CMS. To avoid call behaviour differences caused by differences between VQ's default settings and those configured on your CMS, choose one of the Space Templates created from settings on your CMS by the CMSMigration tool at step 1. Alternatively, select one of the default single Role Space Templates shipped with VQ (for example, Huddle Room)

  8. Using VQCM, run an LDAP import for each LDAP configuration on the system. This will recreate the Spaces with Access Methods and ensures that all existing LDAP created Spaces and all future, VQ created Spaces, work in a consistent manner, are fully manageable by VQ and provide all the functionality and flexibility provided by Access Methods

  9. Restore the LDAP imported Space settings (pins and secrets) by running:

    1. CMSMigrationTool -o restore

Migrate simple non-LDAP Spaces

Converting CMS non-LDAP Spaces from 'legacy' mode to 'access method' mode:

  • Step 0: Edit the “config.json” file to have the correct configuration, in particular “LdapSpaces” set to false. You need to specify a Space Template and Default Owner ID, but no CMS CoSpaceTemplate ID.

  • Step 1: Create VQ Space Templates for the CMS Global and Tenant profiles

  • Step 2: Save all the details for non-LDAP created Spaces on CMS

  • Step 3: Bring CMS nodes into VQ

  • Step 4: Migrate the non-LDAP Spaces from CMS to VQCM, then restore the backed up data from step 2

To migrate the simple non-LDAP Spaces the following process should be used:

  1. Use the tool to migrate the global and tenant level callProfile/callLegProfiles to template roles in VQCM

    1. CMSMigrationTool -o createTemplate

    2. Once this tool has completed your system should include a new set of Space Templates (named after the tenant and LDAP config) that can be renamed and used to create Spaces

    3. You will need to edit the “config.json” file again if you want to use one of those templates

  2. Backup the existing non-LDAP Spaces by running:

    1. CMSMigrationTool -o backup

    2. This will create a "backup" folder on the system which contains non- LDAP imported Space information from the call bridge that will be used to restore PINs and Secret values

    3. Once the system has been completely migrated to VQCM and there are no more issues this folder can be removed

    4. The backup process might take some time; as a general rule, allow 30 seconds per hundred Spaces

  3. Using VQCM, add the call bridges nodes from the CMS cluster and set their states to online

  4. Delete the Spaces from CMS, re-create them on VQCM and restore the data (PIN, secret…) by running:

    1. CMSMigrationTool -o restore

Migrate advanced non-LDAP Spaces

Migrating CMS non-LDAP Spaces that are already using 'access method' to be owned and managed by VQCM:

  • Step 0: Edit the “config.json” file to have the correct configuration, in particular “LdapSpaces” set to false. You need to specify a Default Owner ID and a CmsCoSpaceTemplateId.

  • Step 1: Save all the details for non-LDAP created Spaces on CMS

  • Step 2: Bring CMS nodes into VQ

  • Step 3: Migrate the Space template to VQCM equivalent, non-LDAP Spaces from CMS to VQCM, then restore the backed up data from step 2

To migrate the advanced non-LDAP Spaces the following process should be used:

  1. Backup the existing non-LDAP Spaces by running:

    1. CMSMigrationTool -o backup

    2. This will create a "backup" folder on the system which contains non-LDAP imported Space information from the call bridge that will be used to restore PINs and Secret values

    3. Once the system has been completely migrated to VQCM and there are no more issues this folder can be removed

    4. The backup process might take some time; as a general rule, allow 30 seconds per hundred Spaces

  2. Using VQCM, add the call bridges nodes from the CMS cluster and set their states to online

  3. Migrate the CMS Space template to VQCM, delete the Spaces from CMS, re-create them on VQCM and restore the data (PIN, secret…) by running:

    1. CMSMigrationTool -o restore

Known issues

Currently there is a known issue whereby Spaces that originally contain blank PINs will not be reset to a blank PIN if the template used to generate the Space has the "Generate Pin" option selected.

Running the tool against “advanced” Spaces that are not created from a CMS “coSpaceTemplate” is tricky. The tool will do its best to check that the selected Space template can match that Space, but it is possible that it doesn’t. We recommend only migrating the Spaces created from WebApp or CMM, as that is what was tested against.

Advanced Spaces created directly from the API are “almost” impossible to migrate, as we would need a Space template that matches that Space perfectly, and it was originally created without a template.

Questions and Answers

  • Can the backup produced in step 2 be used to reverse the process? Let's say there is a problem after step 5, is there a way to reverse back to how it was previously using that backup?

    • We can’t reverse the process using just the data from the Migration tool backup as the complete process forces the call bridge to delete the original Spaces using an LDAP import (so that VQCM can recreate them using it’s structure).
    • You could rerun the LDAP import to recreate Spaces with the same URI etc but VQCM will treat these as “Discovered” Spaces which means we only allow a limited set of changes to them, and the restore will not restore everything.
    • The only real way to reverse is to restore the snap shot that was taken before the process started.

VQ Customer Support

Even after reading this document, we highly recommend you to contact our Customer Support Team who will be happy to assist you through the whole process.

Telephone: +44 1249 880140 and select option 2

Email: support@vqcomms.com