Jump to: navigation, search

Migrating Contact and Interaction Data

Summary

Migration from UCS 8.5.2+ to UCS 9.1 consists of:

  • Uploading in GDPS the migration .jar files for both interactions and contacts by using a command line.
  • Starting the migration process in GDPS.

Migration of contacts and interactions must be run separately. The order does not matter.

Important
To migrate extensions data you must migrate contacts first.

Recommendation

Genesys recommends that you make a backup of your 8.5.2+ database before commencing migration.

Migration Process Summary

  1. Stop the primary and backup UCS 8.5s.
  2. Optionally, make backups of the main and archive UCS databases.
  3. Install UCS 9.1 (Cassandra, ElasticSearch and UCS Nodes).
  4. Start UCS 9.1 nodes.
  5. Install GDPS for data migration.
  6. Start GDPS nodes.
  7. Run the migration jobs.
  8. Connect all UCS clients (except RMI clients) to UCS 9.1.
    • Connect to the cluster for clients supporting UCS N+1.
    • Connect to a UCS node in compatibility mode ( that is, a UCS node in a primary / backup configuration) for clients that support only warm standby UCS.
  9. Optionally, disable UCS 8.5 services that are no longer used.
  10. Optionally, remove redundant UCS data from the UCS 8.5 database.
  11. Restart UCS 8.5 applications for clients that cannot be connected to UCS 9.1 (see RMI clients in Known Limitations).

Required files

To run the migration the following files are needed:

  • analytic-package-<version number>.jar available in the deploy\package directory of an installed GDPS. This is the file that will be uploaded in GDPS.
  • ucs-job.bat or ucs-job.sh available in the deploy\package directory of an installed GDPS. This file is used to run the migration command line.

To run migration you must execute ucs-job.bat or ucs-job.sh with several parameters. You can consult the parameter list using either of the following:

  • ucs-job /help or ucs-job /h on Windows platforms.
  • ./ucs-job.sh --help or ./ucs-job.sh --h on Linux platforms.

Parameters List

The list of parameters for migration is as follows:

Parameter Meaning Notes Example
-p PATH_CURL Directory where curl is installed If path contains spaces, surround it with double quotes. -p PATH_CURL "C:\Program Files\tools"
-p GDPS_HOST IP OR HOSTNAME GDPS hostname or IP Set to localhost by default.
-p GDPS_PORT TCP PORT GDPS TCP port Set to 17009 by default. Note: When using multiple GDPS nodes, provide host and port of GDPS master. analytic-package-<version number>.jar cannot be uploaded on worker nodes.
-p PACKAGE_NAME Name of package Name of the package when uploaded onto the server. It can be any string.
-p JOB_NAME
  • MigrateUcsInteractions
  • MigrateListOfInteractions
  • MigrateUcsContacts
  • MigrateListOfContacts
  • MigrateExtensions
Names are not checked, but they must exist already in GDPS.
  • MigrateUcsInteractions—Perform migration of all interactions from the UCS 8.5 database
  • MigrateUcsContacts—Perform migration of all contacts from the UCS 8.5 database
  • MigrateListOfInteractions—Perform migration of interactions from a file (see parameter IMPORT_FILE)
  • MigrateListOfContacts—Perform migration of contacts from a file (see parameter IMPORT_FILE)
  • MigrateExtensions—Perform migration of contacts from a file (see parameter IMPORT_FILE)
-p UCS8_RETRY_CONNECTION The number of attempts to be made to reconnect where the database connection is lost. Retries occur every 1 minute until upper limit is reached. Default value = 10 if parameter is absent or invalid. Valid values: any positive integer. Value 0 disables the retry mechanism.
-p ID <JOB_NUMBER> The Job ID of the migration job Used for various job maintenance tasks.
-p UCS8_PROTOCOL sqlserver
oracle
db2
postgresql
UCS 8.5 database type
-p UCS8_DBNAME UCS8 DB Name UCS 8.5 database name
-p UCS8_HOST IP or Hostname UCS 8.5 database host name or IP address. Set to localhost by default.
-p UCS8_PORT TCP Port UCS 8.5 database port. Set to 1433 by default.
-p UCS8_DBCONFIG Any DB-specific parameters Other parameters to connect to the UCS 8.5 database if any. Use "" if there are spaces in the parameter or any special characters such as , < >.
-p UCS8_USER Username UCS 8.5 database user name.
Username is set to sa by default.
-p UCS8_PWD Password UCS 8.5 database password. Database password is set to sa by default. For an empty password, use the syntax UC8_PWD ""
-p UCS9_HOST IP or Hostname UCS 9.1 host name or IP address. Set to localhost by default. If using a cluster of UCS9s, specify all the nodes, separated by a comma. Load will be balanced on all UCS 9.1 nodes of the cluster. All UCS 9.1 nodes must be reachable. If they are not, the job will fail. Set to 10100 by default. On Windows, surround a comma-separated list with double quotes. 135.39.33.12,135,135.39.33.13,
135.39.33.14
-p UCS9_PORT Port UCS 9.1 port. Must be a comma-separated list of ports if UCS9_HOST contains a comma-separated list. The order must be the same as the list of UCS hosts. On Windows, surround a comma-separated list with double quotes.
-p SPARK_PARTITIONS Spark partitions Default value is 16. GDPS divides the total amount of records by this number to re-do partitioning on each worker.
-p IMPORT_FILE Full pathname Used when importing a file with job MigrateListOfInteractions or MigrateListOfContacts. The filename must be accessible from the GDPS server because the file is not uploaded through HTTP. The user may need to copy it to the correct location.
-p ES_HOST IP or Hostname Unless specified, Elasticsearch host is the same as the UCS 9 host by default.
-p ES_PORT TCP Port Elasticsearch TCP port. Set to 9200 by default.
-p ES_INDEX Index Name Elasticsearch index name. Set the value configured in your UCS9 (the option name in section [cassandra-keyspace])
-p JAR_FILE Full path to .JAR file Set the full path to the file to upload. This option will upload the .jar file to the server. The file is available in the GDPS installation deploy/package directory. For example, the file name can be analytic-package-<version number>.jar. Warning: Using this option will stop and unload any current activity on the server. If path contains spaces, use double quotes.

Upload a Package

The first command consists in uploading a package in the GDSP master node. This is done by using the command ucs-job add and adding the following parameters:

  • -p PACKAGE_NAME <Name_Of_Package>—Name of the package when uploaded onto the server. It can be any string
  • -p JAR_FILE <FULL_PATH_TO_JAR_FILE>—Set the full path to the file to upload. This option will upload the .jar file to the server. If path contains spaces, use double quotes.
Warning
Using this option will discard any current activity on the server.
  • -p PATH_CURL <Directory where curl is installed>—If the path contains spaces, use double quotes. For example;
      -p PATH_CURL "C:\Program Files\tools"
  • -p GDPS_HOST <IP OR HOSTNAME>—GDPS hostname or IP. Set to localhost by default.
  • -p GDPS_PORT <TCP PORT>—GDPS TCP port. Set to 17009 by default. For example:
ucs-job.bat add -p PACKAGE_NAME MigrationMSSQL_UCSmain_IXN  
-p PATH_CURL C:\GCTI\migration\curl -p GDPS_HOST hostgdps 
-p GDPS_PORT 8010 -p JAR_FILE C:\GCTI\migration\
analytic-package-8.5.000.20.jar

Perform the migration

Perform the migration using the command ucs-job submit and add the following parameters:

  • -p PACKAGE_NAME <Name_Of_Package>—The same as previously provided when uploading the package.
  • -p PATH_CURL <Directory where curl is installed>—If path contains spaces, use double quotes. For example;
      -p PATH_CURL "C:\Program Files\tools"
  • -p GDPS_HOST <IP OR HOSTNAME>—GDPS hostname or IP
  • -p GDPS_PORT <TCP PORT>—GDPS TCP port
  • -p UCS8_PROTOCOL <sqlserver|oracle|postgre|db2>—The source database type
  • -p UCS8_DBNAME <database name>—The name of the 8.5 database
  • -p UCS8_HOST <database host>—The host of the 8.5 database
  • -p UCS8_PORT <database port>—The port of the 8.5 database
  • -p UCS8_USER <database user name>—A user name of the 8.5 database
  • -p UCS8_PWD <database password>—Password for the database user
  • -p UCS9_HOST <UCS 9 host>—UCS 9.1 host name or IP address
  • -p UCS9_PORT <UCS 9 port>—UCS 9.1 port
  • -p SPARK_PARTITIONS <number>—Default value is 16. GDPS divides the total amount of records with this number before the distribution to the workers. The recommendations are:
    • Contacts—32 * total number of cores on GDPS nodes.
    • Interactions—8 * total number of cores on GDPS nodes.
     The insertion of contacts is longer than interactions due to the update of the lookup tables.
  • -p ES_HOST <Elastic search host>—Elasticsearch host or IP address
  • -p ES_PORT <Elastic search port>—Elasticsearch TCP port. Set to 9200 by default.
  • -p ES_INDEX <INDEX NAME>—Elasticsearch index name. Set the value configured in your UCS 9.1 (option name in section [cassandra-keyspace])

Example:

ucs-job.bat submit -p PACKAGE_NAME MigrationMSSQL_UCSmain_IXN 
-p PATH_CURL C:\GCTI\migration\curl -p JOB_NAME MigrateUcsInteractions 
-p UCS8_PROTOCOL sqlserver -p UCS8_DBNAME UCSmain -p UCS8_HOST hostdatabase 
-p UCS8_PORT 1433 -p UCS8_USER dbuser -p UCS8_PWD dbpwd -p UCS9_HOST hostucs9 
-p UCS9_PORT 7050 -p SPARK_PARTITIONS 16 -p GDPS_HOST hostgdps -p GDPS_PORT 8010 
-p ES_HOST hostucs9 -p ES_PORT 9200 -p ES_INDEX ks_ucs9
Important
By default, the migration job inserts the contacts and interactions into UCS 9.1 through the ESP port. It is possible to use the HTTP port. To do that, use the parameters UCS9_PROTOCOL, UCS9_BASE_URL, UCS9_USER, UCS9_PWD described here.

Progression

When the migration begins the ID of the related job in GDPS is displayed. You are advised to save this ID in a temporary file.

In the sample below the job ID is:

c0c798be-726b-4d4a-afff-52e56c7d3847

Sample Command Line

ucs-job.bat submit -p PACKAGE_NAME MigrationMSSQL_UCSmain_IXN 
-p PATH_CURL C:\GCTI\migration\curl -p JOB_NAME MigrateUcsInteractions 
-p UCS8_PROTOCOL sqlserver -p UCS8_DBNAME UCSmain -p UCS8_HOST hostdatabase 
-p UCS8_PORT 1433 -p UCS8_USER dbuser  -p UCS8_PWD dbpwd  -p UCS9_HOST hostucs9  
-p UCS9_PORT 7050 -p SPARK_PARTITIONS  16 -p GDPS_HOST hostgdps -p GDPS_PORT 8010 
-p ES_HOST hostucs9  -p ES_PORT 9200 -p ES_INDEX ks_ucs9
HTTP/1.1 100 Continue


The progression of the migration will be displayed as follows:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Tue, 21 Jun 2016 13:31:44 GMT
Accept-Ranges: bytes
Server: Restlet-Framework/2.3.0
Content-Length: 37

{"status": "Ok", "readSize": 9198523}
Job Id: c0c798be-726b-4d4a-afff-52e56c7d3847
processed:0 errors:0 exceptions:0 success:0 total:0
processed:0 errors:0 exceptions:0 success:0 total:0
processed:0 errors:0 exceptions:0 success:0 total:0
processed:0 errors:0 exceptions:0 success:0 total:0
processed:0 errors:0 exceptions:0 success:0 total:0

Removing a Package

To remove a package from GDPS use the command ucs-job remove with the following parameters:

  • -p PACKAGE_NAME <Package name>—Same name used when uploading package.
  • -p PATH_CURL <Directory where curl is installed>—If path contains spaces, use double quotes. For example:
 -p PATH_CURL "C:\Program Files\tools"
  • -p GDPS_HOST <IP OR HOSTNAME>—GDPS host name or IP. Set to localhost by default.
  • -p GDPS_PORT <TCP PORT>—GDPS TCP port. Set to 17009 by default.

Example:

ucs-job remove -p PACKAGE_NAME Migr_oracle_Ixn -p PATH_CURL C:\GCTI\migration\curl -p GDPS_HOST hostgdps -p GDPS_PORT 8010
Removing package '"Migr_oracle_Ixn"' from server. Please wait...
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Tue, 21 May 2018 14:18:40 GMT
Accept-Ranges: bytes
Server: Restlet-Framework/2.3.0
Content-Length: 16

{"status": "Ok"}
Exiting.

Error Reporting

When errors occur, a report is generated. The generated report is available in the working directory and contains the list of IDs and error reasons.

The report is generated in one of the following files:

  • interactionFailures-<job ID>.txt
  • contactFailures-<job ID>.txt (for example: interactionFailures-7a8f9257-c5c1-47e5-aed6-7ca28f760f7e.txt).

Error Report Example

#EmailIn Id
0000SaBMG7UA000S,2016-05-27T11:37:59.284Z,[job] 7a8f9257-c5c1-47e5-aed6-7ca28f760f7e
[0000SaBMG7UA000S] [OMInteractions] Error [Id] InsertInteraction [Code] 732 [Reason] 
11:37:56.980 Server: UCS9MIGR Msg: Invalid Tenant 101
0000SaBMG7UA000M,2016-05-27T11:37:59.347Z,[job] 7a8f9257-c5c1-47e5-aed6-7ca28f760f7e 
[0000SaBMG7UA000M] [OMInteractions] Error [Id] InsertInteraction [Code] 732 [Reason] 
11:37:57.058 Server: UCS9MIGR Msg: Invalid Tenant 101
#EmailOut Id
#Chat Id
#PhoneCall Id
#Callback Id
#Interaction Id

Troubleshooting

When the problem preventing the creation of contact or interaction is fixed, the migration can be run with the list of previously failed IDs only. The parameters are the same as the ones used to perform the migration, except the following:

  • -p JOB_NAME—MigrateListOfInteractions;MigrateListOfContacts
  • -p IMPORT_FILE—Path to the generated error report, relative to the GDPS master and accessible from it. Users might need to copy this file to the correct location before running the migration.


Example

ucs-job.bat submit -p PACKAGE_NAME MigrationMSSQL_UCSmain_IXN 
-p PATH_CURL C:\GCTI\migration\curl -p JOB_NAME MigrateListOfInteractions 
-p UCS8_PROTOCOL sqlserver -p UCS8_DBNAME UCSmain -p UCS8_HOST hostdatabase 
-p UCS8_PORT 1433 -p UCS8_USER dbuser -p UCS8_PWD dbpwd -p UCS9_HOST hostucs9 
-p UCS9_PORT 7050 -p SPARK_PARTITIONS 16 -p GDPS_HOST hostgdps -p GDPS_PORT 8010 
-p ES_HOST hostucs9 -p ES_PORT 9200 -p ES_INDEX ks_ucs9 
-p IMPORT_FILE interactionFailures-7a8f9257-c5c1-47e5-aed6-7ca28f760f7e.txt 

Query the Status of the Migration Job

You can get a job status (progression of the migration) from a new window or another host. Use the command ucs-job status with the following parameters:

  • -p ID <job Id>
  • -p PATH_CURL <Directory where curl is installed>; If path contains spaces, use double quotes—for example; -p PATH_CURL "C:\Program Files\tools"
  • -p ES_HOST <IP OR HOSTNAME>—Unless specified otherwise, the Elasticsearch host is the same as UCS 9 host by default
  • -p ES_PORT <TCP PORT>—Elasticsearch TCP port. Set to 9200 by default.
  • -p ES_INDEX <INDEX NAME>—Elasticsearch index name. Set the value configured in your UCS 9 (the option name in section [cassandra-keyspace])
  • -p GDPS_HOST <IP OR HOSTNAME>—GDPS hostname or IP. Set to localhost by default.
  • -p GDPS_PORT <TCP PORT>—GDPS TCP port. Set to 17009 by default.

Example:

ucs-job status -p ID c0c798be-726b-4d4a-afff-52e56c7d3847 
-p PATH_CURL C:\GCTI\migration\curl -p GDPS_HOST gdpshost -p GDPS_PORT 8010 
-p ES_HOST hostucs9 -p ES_PORT 9200 -p ES_INDEX ks_ucs9
processed:52 errors:0 exceptions:0 success:52 total:2514607
processed:275 errors:5 exceptions:0 success:270 total:2514607
processed:275 errors:5 exceptions:0 success:270 total:2514607

Rollback

To roll back your migration in the event of unresolvable error:

  1. Stop the primary and backup UCS 8.5s.
  2. Optionally, if you removed redundant data from the UCS 8.5 database, restore the main and archive UCS database backups.
  3. Connect all UCS clients to UCS 8.5 applications.
  4. Re-enable all disabled UCS 8.5 services.
  5. Start the UCS 8.5 applications.
  6. Stop the UCS 9.1 applications.

Post-migration Cleanup

If the migration of the UCS data to UCS 9.1 nodes was successful, the migrated contact and interaction data can be removed from the 8.5 UCS database.

Migrating the 8.5 Archive Database

Because there is no concept of archive versus current in Cassandra, you may need to migrate your 8.5 archive database into UCS 9.1.

To migrate the archive database, use the same command line arguments as described above, but verify that the migration job is pointing to the archive database instead of the current database. To verify that the migration job points to the archive database, adjust the following parameters accordingly:

  • UCS8_PROTOCOL
  • UCS8_DBNAME
  • UCS8_HOST
  • UCS8_PORT
  • UCS8_USER
  • UCS8_PWD


This procedure applies to interactions only, as there are no contacts stored in the 8.5 archive database.

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on November 10, 2018, at 01:54.