Appendix: Migration Procedures

Important

This topic contains migration information only for 8.1.4 releases. For instruction on how to migrate to earlier releases of Interaction Concentrator, see the Interaction Concentrator chapters in the Genesys Migration Guide.

Migration Preliminaries

Complete the following procedures before starting your migration of Interaction Concentrator:

1. Migrate Management Framework, as applicable for your deployment.
2. Upgrade other prerequisite Genesys components (for example, T-Server, Interaction Server, or Universal Routing Server), as applicable for your deployment.
3. Update the contact center configuration (for example, Place Groups, Agent Groups, and DNs).

Migration Procedures

Main Steps

1. Migrate your ICON Server.
2. Check whether you need to update your IDB schema.
3. If necessary, migrate your IDB schema.

In a High Availability Environment

Genesys recommends that you run both ICONs in each ICON pair simultaneously for at least one day before the migration. At the minimum, the time the ICONs run simultaneously must exceed the time set in the Genesys Info Mart max-call-duration configuration option.

The recommended upgrade plan is the following:

• Stop one member of an ICON pair, migrate that ICON instance, and then restart it. Make sure it starts successfully. If not, roll back the migration (see Rolling Back the Migration).
• If the ICON migration was successful, wait until the longest active interaction in the environment finishes (usually 24 hours is enough). Then—assuming the migrated ICON has been operating normally—stop the other member of the HA pair of ICONs and perform the same migration procedure, again ensuring that the migration is successful.

In an Environment with Genesys Info Mart

Important

Your migration should be done in a working environment with an available ICON database and the associated ICON DBServer.

If Genesys Info Mart is running in your environment, stop all Info Mart extraction jobs before you start your ICON migration. Restart Job_ExtractICON only after you have successfully completed the migration of the ICON instances from which Info Mart is extracting data.

If you have multiple ICON applications, repeat the migration procedure for each ICON instance (including each ICON in any HA pair).

Migrating the ICON Server

Follow these steps to migrate the server component of Interaction Concentrator to the latest release:

1. Find a timeframe for this migration during which ICON has minimal activity.
2. Stop ICON, either using Genesys Solution Control Interface (SCI), Genesys Administrator/Genesys Administrator Extension, or manually. This may take several minutes. Make sure not to restart ICON until after the database update is complete.
3. Back up the Interaction database (IDB).
4. If you have customized the gudCustDISP1 or gudCustDISP2 dispatcher stored procedures and saved them with the default (Genesys-provided) names, back up the procedures and restore them after the upgrade.
5. Back up the entire ICON directory in case you need to roll back the migration.
   • Back up your customer-related files, which have the following suffixes:
     • *.db
     • *.pq
     • *.xml—You can locate this file, which by default is named ccon_adata_spec.xml, in the directory where the current version of Interaction Concentrator is installed.
   • Save the scripts that drop outdated stored procedures. To do so, save the drop_<version>_<db>.sql file to be used after successful migration completion to drop the old stored procedures. Keep the old stored procedures for approximately one week. Then you can drop them, if you prefer, but there is no need to.
6. Run the setup file (install.sh or setup.exe) provided in your installation package.

   Important

   These instructions assume you are installing the new version of ICON in the same location as the old one. If you install the upgraded version into a different directory from the existing version, verify that you are launching the correct ICON version when you restart. For example, you might need to adjust the Windows Service settings. For instructions on how to configure ICON start up, see Starting and Stopping.

7. Restore the backup customer-related files saved in Step 5.
   • Replace the files installed in the folder where you deployed ICON 8.1.x during migration with your saved files.
8. For environments running any Genesys Info Mart release prior to 8.5.007.xx, run the update_idb_for_gim.sql or update_idb_for_gim_mm.sql script, as appropriate, every time you migrate to a new release of Interaction Concentrator.

Checking Your IDB Schema Version

Check if an ICON database update is necessary by comparing database schema versions.

1. The database schema version of the new installation can be identified from the name of the following file: drop_<VERSION>_<db_type>.sql
   where
   • <VERSION> stands for the new database version. The version has the format N.N.NNN.NN.
   • <db_type> stands for the short name of the database type.

   For example, the filename might be: drop_8.1.512.xx_postgre.sql.

2. The currently-installed RDBMS version can be identified by either the name of the drop_<VERSION>_<db_type>.sql file in the previous installation of ICON or using the following database query:
   SELECT VAL FROM G_DB_PARAMETERS where SECT = 'schema' and OPT = 'version'

Important

If both the current and new ICON schema versions are the same, you do not need to update your IDB. The version of the database schema does not necessarily match the release number of the component. For example, for Interaction Concentrator release 8.1.509.09, the database schema version is 8.1.508.05.

Updating IDB

The update includes an upgrade of the stored procedures and it might include a change to the database schema.

To perform the schema upgrade, apply all the upgrade scripts sequentially in the order of increasing versions starting from the lowest numbered upgrade script version above the current (old) ICON database schema version through the highest version found in the directory.

The Interaction Concentrator installation package may contains one or more upgrade schema scripts in the following format: Upgrade_N.N.NNN.NN_<db_type>.sql
where:

• N.N.NNN.NN indicates the schema version to which this script upgrades the database schema.
• <db_type> defines the type of database (ora, mssql, db2, or postgre).

Examples

Example A

If the old IDB version is 8.1.100.28 on ORACLE and the new ICON installation provides the following upgrade scripts:

• Upgrade_8.1.100.27_ora.sql
• Upgrade_8.1.100.29_ora.sql
• Upgrade_8.1.100.32_ora.sql

Then run the following scripts in the specified order:

• Upgrade_8.1.100.29_ora.sql
• Upgrade_8.1.100.32_ora.sql

Example B

If the old IDB version is 8.1.100.32 on ORACLE and the new ICON installation provides the following upgrade scripts:

• Upgrade_8.1.100.27_ora.sql
• Upgrade_8.1.100.29_ora.sql
• Upgrade_8.1.100.32_ora.sql

There is no need to apply any of the upgrade scripts.

Example C

If the old IDB version is 8.1.100.35 on ORACLE and the new ICON installation provides the following upgrade scripts:

• Upgrade_8.1.100.27_ora.sql
• Upgrade_8.1.100.29_ora.sql
• Upgrade_8.1.100.32_ora.sql

There is no need to apply any of the upgrade scripts.

Example D

If the old IDB version is 8.1.100.27 on ORACLE and the new ICON installation provides the following upgrade scripts:

• Upgrade_8.1.100.27_ora.sql
• Upgrade_8.1.100.29_ora.sql
• Upgrade_8.1.100.32_ora.sql

Then run the following scripts in the specified order:

• Upgrade_8.1.100.29_ora.sql
• Upgrade_8.1.100.32_ora.sql

Upgrading the Stored Procedures

1. To create a new set of stored procedures in IDB to support your new ICON installation, run CoreProcedures_<db_type>.sql.
2. If you are running Oracle 11 or higher and plan to purge by truncating partitions, you must create a new partitioned IDB. See Configuring a Partitioned Oracle IDB in the Interaction Concentrator Deployment Guide for deployment considerations and instructions.
   Important

   If you have an existing partitioned IDB, you cannot migrate that IDB to a non-partitioned database structure.
3. Upgrade your purge procedure. To do so, execute the appropriate one of the following scripts:
   • Purge2_<database>.sql
   • PurgePart_ora.sql—If you have a partitioned IDB.
   • Purge2_PartitionType0_ora.sql—If you have a non-partitioned Oracle IDB with the ICON partition-type configuration option set to 0. Available in release 8.1.505.05 and higher.
4. Verify the purge parameters. Verify that the GSYSPurge81 procedure has been set up appropriately for your deployment. To do this:
   1. Retrieve the transaction_size value by selecting SELECT Val
      from
      G_DB_PARAMETERS
      where
      SECT = 'GSYSPurge81'
      and
      OPT = 'rowspertransaction'
   2. Make sure Val has the required value (the default value is 200,000 records). If necessary, you can make changes manually or you can use an optional Interaction Concentrator stored procedure, svcUpdateDBParameters, provided in the Wrapper_for_<version>_<db_type>.sql script.
5. Upgrade the wrappers. The ICON scripts directory contains wrappers for the stored procedures. For each RDBMS type, there is a file that matches pattern Wrapper_for_*_<db_type>.sql. For example, for Microsoft SQL, the wrapper name is Wrapper_for_<version>_mssql.sql.
   • Execute the wrapper for your RDBMS.

Re-Starting ICON and Verifying the Migration

1. Start the upgraded ICON. Genesys recommends that you use Solution Control Interface (SCI) or Genesys Administrator/Genesys Administrator Extension to start ICON.
2. Wait while ICON completes startup operations. The startup time strictly depends on the size of your configuration environment and may take more than 30 minutes.
3. Check the log for errors to verify that ICON is running properly. The criteria for a successful migration is that ICON starts and no database problem is detected.
   ICON is started when all three of the following trace messages below have been printed in the log:
   • Trace log message 09-25004: Database queue [ID]: persistent queue transaction [number1] is processed, committed and removed. [number2] records are written.
   • Trace log message 09-25016: Persistent Queue [ID]: transaction [number1] is committed. [number2] records written into the queue.
   • Trace log message 00-04541: Message [message type] received from [socket number] ([application type] [application name]).
   If ICON is unable to write interaction data in IDB, then see Rolling Back the Migration for instruction on reversing the migration and restoring your previous version of ICON.

Follow-Up Steps to Complete Your Migration

1. If ICON started successfully, you can start the Genesys Info Mart Job_ExtractICON.
2. (Optional) After a week—to allow time to be certain that you will not need to roll back your upgrade—you can delete all old stored procedures for previous Interaction Concentrator releases. To do so, execute the drop_<previous_schema_version>_<db_type>.sql script you saved in Step 5 in "Migrating the ICON Server" (above).

Rolling Back the Migration

If the upgrade failed and ICON did not start successfully, perform the following steps:

1. Stop Interaction Concentrator.
2. Restore the IDB database from your backup.
3. Restore entire the Interaction Concentrator directory, including the icon.exe file, as well as the *.pq and *.db files.
4. Start the restored version of ICON.
5. If ICON starts successfully, you can then start the Genesys Info Mart extraction job.

Important Migration Notes

• You can migrate Interaction Concentrator from any version of release 7.5 or 7.6 directly to release 8.x.
• To migrate Interaction Concentrator 7.2 to 8.x, first, migrate to release 7.5 or 7.6 and then migrate to release 8.x.
• ICON processing must be suspended while the Interaction Concentrator migration is occurring. The content of the persistent queue file (icon_*.pq) is lost as a result of the upgrade. To minimize the loss of data, perform the upgrade when the contact center load is minimal.
• Stopping ICON does not stop the execution of any stored procedures that may be running or scheduled to run during the upgrade. In particular, if the merge or purge stored procedures are executing when you run the database scripts, these stored procedures are not successfully dropped and then re-created. You are not notified if you did not upgrade these service procedures correctly.
• You cannot migrate from a non-partitioned IDB to a partitioned IDB, or vice versa. If you want to start or stop using partitions, you must create a new IDB. (Partitioning is available on Oracle RDBMSs only.) For detailed information on this topic, see Purging by Truncating Partitions in the Interaction Concentrator User’s Guide.