Migrating from 8.1 to 8.5

Warning

Starting from version 8.5.239, GMS no longer supports the migration process and the tool has been removed from the installation package.

Describes how you can migrate your application from former 8.1 versions to 8.5 versions.

Why Migrating?

In release 8.5, services data are no longer stored in Universal Contact Server (UCS) database; they moved to Genesys Moblie Services (GMS) Cassandra database.

1. If you are upgrading from 8.1 to 8.5, you must first migrate your Context Services data using the Context Services migration tool.
2. If your application needs profiles, you can keep using data stored in UCS. You do not need to modify the 8.1.3 Context Services queries for profiles and interactions. In this scenario, you must also set up your proxy to correctly handle URLs, as shown in the architecture diagram below.

As detailed in the Context Services Developer's Guide, profiles, interactions, and additional metadata resources are no longer available in 8.5. If your application requirements include these resources, you can still use the UCS APIs to manage customer data. You must update the UCS configuration to point to the same base URL than GMS. You should therefore edit your proxy configuration; see below for detailed instructions.

Important

If your application uses both GMS and UCS queries, you should make sure that it does not use deprecated methods.

Database Migration Process

Important

Before your start the migration, you must install Context Services.

The migration tool is a command line tool installed with the Context Services. This tool exports the services stored in UCS and then imports them in the Cassandra Database of the GMS Cluster:

• All service data, including state, tasks, and extensions are migrated.
• All the start/complete events are re-created.

Migration process:

1. Launching the tool with all required parameters.
2. Extracting Context Service data from UCS DB.
3. Importing Context Service data in GMS DB.

Database Migration Results

The migration tool creates the following files after the migration:

• <Migration Tool Directory>/failure.log;
• <Migration Tool Directory>/success.log.

If no error occurs during the migration, the Context Services is then available in the Genesys Mobiles Services cluster.

Important

The Context Services data is not deleted from the UCS database.

Interruption during the Database Migration

You can abort the migration during the import stage by entering CTRL-C command at the console.. The migration process may need a few seconds to stop. Then, you will be able to restart the migration tool by specifying the last imported service ID with the -continue-from option.

Here is an interruption sequence diagram.

Migrating the Context Services from UCS to GMS Database

You must complete the following steps to perform the service data migration:

1. Checking the Business Attributes Mapping Options
2. Enabling the custom IDs
3. Running the Migration Tool

Checking the Business Attributes Mapping Options

Procedure: Checking the Business Attributes Mapping Options

Purpose: To make sure that your UCS and GMS applications have the same business attribute mapping. The mapping may be disabled during the migration process.

Steps

1. Open the Configuration Manager and edit both your GMS and UCS applications.
2. Make sure that the options defined in the business-attributes sections are identical in both applications.

Enabling the Custom IDs

Procedure: Enabling the Custom IDs

Purpose: To configure the allow-custom-ids option which allows the migration tool to replicate the UCS service IDs in the GMS Cassandra database. This option allows to keep identical IDs in the new storage location. Note that further services will be created with distinct UUID-type IDs.

Steps

1. Open the Configuration Manager and edit your GMS application.
2. Select the Options tab, and select the cview section.
3. Click Add to create Add the option allow-custom-ids and set its value to true.
4. Click OK to apply changes.

Running the Migration Tool

Procedure: Running the Migration Tool

Purpose: To migrate services from UCS database to Cassandra.

Before you run the tool, make sure that:

• You installed the Context Services.
• The Migration Tool is available in the <GMS installation directory>/tools/cs_migration_tool folder.
• You already set the cview/allow-custom-ids option to true and your business-attributes options are set correctly for both UCS and GMS.

The command line tool includes two migration modes:

• The DB mode, which migrates all the services from the UCS database to the GMS database;
• The FILE mode, which migrates a restricted list of service IDs from the UCS database to the GMS database.

Steps

1. Open a console.
2. Enter the migration command line:

$ startClient.bat [DB_OPTIONS] -tenantid <tenantID> -ucsurl <UCS_URL> -gmsurl <GMS_URL> [ADDITIONAL_OPTIONS]
or
$ startClient.bat  -file <PATH_TO_FILE> -tenantid <tenantID> -ucsurl <UCS_URL> -gmsurl <GMS_URL>  [ADDITIONAL_OPTIONS]

See the tables below for information about the parameters.

The parameters are described in the following table:

Command Line Parameters

Parameters	Scope	Mandatory	Description
-dbtype	DB only	Y	Sets the type of Database used for UCS ('oracle' or 'mssql') -dbtype mssql
-dbhost	DB only	Yes	Sets the host for the UCS Database -dbhost demo_srv
-dbport	DB only	Yes	Sets the port of the UCS Database. -dbport 1433
-dbname	DB only	Y	Sets the name of the UCS Database to migrate. In this case, all the services are migrated to the GMS database. -dbname UCS
-dbuser	DB only	Yes	Sets the user name of the UCS Database. -dbuser sa
-dbpassword	DB import only	Yes	Sets the password of the UCS Database. -dbpassword mypass
-file	FILE only	Yes	Sets the migration file which contains the list of ServiceIds to migrate. This text file (.txt) must contain one service_id per line; for example, you can create a file named listOfIds.txt containing the following list of IDs: 10001 10002 10003
-ucsurl	ALL modes	Yes	Sets the UCS URL. -ucsurl http://<host>:<port>/genesys/1/c
-gmsurl	ALL modes	Yes	Sets the GMS URL. -gmsurl http://<host>:<port>/genesys/1/cs
-tenantid	ALL modes	Yes	Sets the GMS tenant DBID. -tenantid 102
-continue_from	ALL modes	No	In case of restart, specifies from which service_id to continue the migration. -continue_from 10003

In addition, the migration tool supports a set of additional options which help you to fine-tune your migration. Each option matches the following syntax:

-D<option>="<value>"

where <value> can either be a number or a string.

Special Options

Option	Scope	Mandatory	Description
EXTRACTOR_SELECT_QUERY	DB import only	No	Sets a specific selection query to migrate data from UCS Database. The default value is: SELECT ServiceId, StartTime FROM ServiceStarted UNION SELECT ServiceId, StartTime FROM ServiceStartedAnonymous ORDER BY StartTime The query must return the service ids in the first column; for example: // selecting a range of services -DEXTRACTOR_SELECT_QUERY="SELECT ServiceId FROM ServiceStarted WHERE ServiceId >= 822184 AND ServiceId < 922184 ORDER BY StartTime ASC" or // selecting all the associated services which are not completed -DEXTRACTOR_SELECT_QUERY="SELECT ServiceId FROM ServiceStarted WHERE (ServiceId NOT IN (SELECT ServiceId FROM ServiceCompleted)) ORDER BY StartTime ASC"
THREAD_POOL_SIZE	Any	No	Sets the number of services to process in parallel. Default is 30. The default value should be fine in most cases. If you modify this value, you change the number of requests that will be in process in case of user termination on demand (Ctrl-C). -DTHREAD_POOL_SIZE=50

Additional Configuration for UCS Backward Compatibility

Now, you must also configure the new Context Services application to ensure compatibility with your UCS installation. See Configuring CS for UCS Compatibility.