Channels 9.2 Upgrade Process with DB Migration

over 7 years ago | Article no. 6116

1 rating

THIS ARTICLE APPLIES TO:

This article applies to scenarios of upgrading Moxie™ Channels from Versions 8.3.2 to 9.4. It includes the following details:

Prerequisites for the upgrade and migration.
Typical deployment scenarios.
Steps to complete the upgrade and migration processes per scenario.

PROCESS:

Prerequisites:

Prior to the upgrade and migration ensure that the following are available:

The Channels 9.4 Hardware and Software Requirements Guide.
Login to “Moxie™ Software Support Knowledgebase” to get this document. The minimum hardware and software requirements as described in this guide must be present for this process to be successfully completed. Make sure that the infrastructure matches with the documented requirements.
Reliable Multicast Protocol enabled in the machines where Channels and/or CommCore are installed.
Microsoft .NET Framework 4.5.
IIS - configured as described in the Channels 9.4 Installation Guide.
The Moxie™ Channels 9.4 Installation Guide and the related Release Notes, for reference while completing the high level steps described in this article.

Typical Deployment scenarios:

The following scenarios are typical to the upgrade and database migration of Channels. Users can follow the steps for the scenario that matches their deployment or requirement.

Direct or “In place” upgrade from Channels 9.1 to Channels 9.2 and from Channels 9.2 to Channels 9.4.
See Section 1, for the actions to be taken for upgrading up from prior versions to Channels 9.4 before migrating Channels database.
Upgrade with Database Migration. See Section 2, for upgrading and migrating the database.
Database Migration only. See Section 3, for migrating the database.

1. Direct (“in place”) Upgrade

Direct or “In place” upgrade from Channels 9.1 to Channels 9.2 and from Channels 9.2 to Channels 9.4, is adirect procedure with minimal manual steps because:

The Channels installer executable takes care of the CommCore Services and Cache database configuration.
Channels databases are upgraded in line with the Channels software upgrade.

Upgrade Channels 9.1 to Channels 9.2Actions - on a Server where Channels 9.1+ is installed

1.	Install the new version of Channels Service.
a.	Run “MoxieChannelsServer920(x64).exe”, and complete the step by step instructions in the setup wizard.
b.	Provide a Company Name in the related dialog.
c.	Set up the Cache database by providing the details of the newly created database in the related dialog.
d.	Complete the Channels Server installation.
2.	Install the new CommCore Services.
a.	Run “MoxieCommCoreServices920(x64).exe” and follow the setup wizard.
b.	Provide details of the Channels database (Main).
c.	Provide Company Name and details for each CommCore Service.
d.	Complete the installation.
Post upgrade, Channels Service requires CommCore Services to start up completely for the first instance. After the first instance of starting the Channels Service the Channels (Main) database is upgraded and the Channels Cache database is initialized.
3.	Migrate the Email workflows of the prior versions to the schema defined in Channels 9.2.
a.	Stop Channels and all CommCore Services.
b.	Run the Email Workflow Migration tool. This upgrades the Email Workflows of Channels 9.1 and prior versions to the newCommCore Workflows and *database table schema* defined in Channels 9.2. Important: Take care to run any workflow migration tool only once. Repeating this action could result in duplicate workflows.
c.	Check for errors found as a result of the migration and correct them.
4.	Start Channels Service and CommCore Services.
a.	RunMoxieChannelsServer940(x64).exe to upgrade Channels Server.
b.	RunMoxieCommCoreServices940(x64).exe to upgrade CommCore Services.
c.	RunMoxieChannelsServer940HF1(x64).exe to install the latest Hotfix.
d.	Install the latest Patch:Channels 9.4 Hotfix 1 Patch 04 is the latest released Hotfix and Patch in the Channels 9.4 release train.

At this point Channels Service is upgraded to 9.4.

2. Upgrade with Database Migration

Upgrading to ahigher version with Database Migration involves manual steps. In this case:

An upgraded non-production (or test) Channels installation is re-targeted to a production database.
CommCore Services and Cache Database must be reconfigured after database migration.

The following assumptions apply to the steps described in this scenario:

A non-production (test) instance has Channels 9.2 Hotfix 1 Patch 08.
The production database server and the non-production (test) database server are not on the same system.
The production instance (non-upgraded) has Channels 9.1Hotfix 2.
The non-production (test) instance is re-targeted to the production database in order to upgrade the production database.

Note: It is assumed that users will upgrade along the path Channels 9.1 > Channels 9.2 > Channels 9.4.

Upgrade with database migration high level steps.

1.	*Steps to be performed on the production* instance where Channels 9.1 Hotfix 2 is deployed.**
a.	Ensure that MailSendQueue table is empty.
b.	Stop Channels Service and Survey Service.
c.	Stop IIS.
d.	Take full backup of Channels and Survey databases
e.	Delete the entries from CimServers table in Channels database (Main).
f.	Update the MailSource to 0 in the Mailbox table for POP and IMAP Mailboxes
g.	Create a new database to be used as Cache database
h.	Make sure that the broker service is enabled in the Survey database
2.	*Steps to be performed on the non-production (test)* instance where Channels 9.2 Hot Fix1 Patch 08is deployed.**
a.	Stop Channels Service, Survey Service and all CommCore Services.
b.	Stop IIS.
c.	Login to the non-production (test)SQL server.
d.	Disable the SQL Agent Job created to synchronize the Cache database. Note: This action is part of Channels 9.2 Hot Fix1 P02. Skip this step if you are continuing to upgrade to Channels 9.4 Hot Fix 1.
e.	Take a back-up of the data in the following tables of the Channels database (Main). – DatabaseConnection – PGMMulticast – CimServers – Services
f.	Make note of all the entries of CommCore Services in the “Services” table in the Channels database (Main) for each service. This information is required to manually generate the setup.ini files.
g.	In the Windows Registry of the Channels Server, navigate to : HKEY_LOCAL_MACHINE\ SOFTWARE\ Wow6432Node\ MoxieSoft\ NetAgentServer\\ CurrentVersion\
h.	Set the value of INIT_CACHE to 1.
3.	*Manually create and replace.ini files for Channels Service and the CommCore Services.**
a.	Create a new setup.ini file and replace the existing *setup.ini* file located at *\NetAgent Server\conf*.
b.	Use the data available in the DatabaseConnection table backup to create the new setup.ini file.
c.	Delete the “setup.ini” file within “bin” directory under each CommCore services install path.
d.	Generate the setup.ini files manually for each CommCore Services (Attachment, Monitor, PostOffice, Workflow and Router) using the configuration details available from ‘Services’ table backup
e.	Place the newly created setup.ini file for each CommCore Service in the respective bin folders.
f.	Generate setuppgm.ini file for Monitor Service using the configuration details from “PGMMulticast” table and replace the existing setuppgm.ini file within “bin” directory under Monitor Service. (Note: this step can be skipped if PGM IP and port details are not changing)
4.	*Update each CommCore service executable’s configuration file with the production* database’s details.**
a.	Modify the connection string for Channels database in Service.exe.config file of each CommCore service to reflect the *production* database and database server details. Example: <connectionStrings> <clear/> <add name="PrimaryDatabase" connectionString= "Data Source= ProductionDBServer;Initial Catalog=ProductionDBName; User Id=sa;Password=Password1;" providerName="System.Data.SqlClient"/> </connectionStrings>
b.	Modify connection string in the following files: – AttachmentService.exe.config – MonitorService.config – AttachmentService.config – PostOfficeService.config – RouterService.config
c.	In the Workflow Service bin folder, modify connection string in the following files: – WorkflowService.exe.config – WorkflowShell.exe.config
d.	For MultiChannel Web Service, update the web.config file in the MultiChannelWebService folder under CommCore install path. Note: The database server credentials in the Service config files will be encrypted upon restarting the Services.
e.	In the Survey Installation bin folder, modify the Survey database information in the file SurveyService.exe.config.
5.	*Modify the DSN with server details to connect to the production* database.**
a.	Change the ODBC connection [DSN] of the non-production (test)instance to point to the production database server.
b.	Start IIS.
c.	Start all services.
d.	Check for errors in the DBtool*.log file.
e.	Wait until the Channels Database is upgraded successfully and Cache database is initialized, tables and contents are successfully created in the Cache database.
f.	Start all the CommCore Services at least once so that entry will be made in the Services table.
g.	Start Survey Service.
6.	Run Email workflow Migration tool to migrate from Channels 9.1 to Channels 9.2.
a.	Stop Channels and all CommCore Services.
b.	Run Email Workflow Migration tool.
c.	Check for and correct any errors found.
d.	Start Channels and CommCore Services.
	Note: If the MailSource of Mailbox was set to0 at the beginning of the upgrade process, update the MailSource to1 in the Mailbox table for POP and IMAP Mailboxes. If continuing upgrading to 9.4HF1 this step can be performed after upgrading to 9.4HF1.
7.	Continue the upgrade to Channels 9.4:
a.	Run “CIM940ChannelServer (x64).exe” to upgrade Channels Server.
b.	Run “CommCore Services (x64).exe” to upgrade CommCore Services.
c.	If you are upgrading from Channels 9.2HF1 P08 apply the “Channels 9.4.0.0 Upgrade Installer Fix”to prevent database upgrade issues.
d.	Install the latest Hotfix and Patch: 9.4 Hotfix 2 Patch 4 is the latest released Hotfix and Patch in the Channels 9.4 release train.

At this point the databases are migrated and Channels Service is upgraded to 9.4.

3. Database Migration only – No Upgrade

The “Database Migration only” scenario involves manual steps. In this case:

An upgradednon-production (test)Channels installationis re-targeted toan upgradedproductiondatabase.
The Channels Database (Main) is migrated. This would not involve a database upgrade.
A new database is created to function as the Channels Cache database.

TheChannels database (Main) contains critical information about theChannels Cachedatabase configuration.
Copying the Channels database (Main) of Channels 9.2 or later, in anon-production (test) instance used for QA, user acceptance testing or for other purposes to aproduction environment, impacts thecachedatabase. In order to get working system, the databases must be migrated as described in this section.

The following assumptions apply to the steps described in this scenario:

The non-production (test) instance and production instance application servers run the same version of
Channels – that is Channels9.2 Hot fix 1 Patch 08, thus requiring only migration of the Channels Database(Main).
The non-production (test) instance database and production instance database are in different SQL Servers.
The Companyname entry for the non-production (test) instance and production instance is the same.
Channels Server and CommCore Services are installed in the same server.
The production instance’s database names will not be changed while restoring the non-production (test) instance database into the production instance.

Database migration high level steps

1.	*Steps to be performed on the non-production(test)Instance.*
a.	Ensure that there are no emails waiting for approval in the MailSendQueue table.
b.	Stop the Channels Service, Survey Service and all CommCore Services.
c.	Stop IIS.
d.	Make note of all configuration tables.
e.	Login to the SQL Server oftest instance.
f.	Disable the SQL Agent Job created to synchronize the cache database of the test instance. Note: This functionality was introduced in Channels 9.2-HF1 P02.
2.	*Steps to be performed on the production* instance: Backup the databases.**
a.	Validate that no emails are waiting in MailSendQueue table.
b.	Stop Channels Service, Survey Service and all CommCore Services.
c.	Stop IIS.
d.	Login to the SQL Server of production instance.
e.	Disable the SQL Agent Job created to synchronize the cache database of production instance.Note: This functionality was introduced in Channels 9.2-HF1 P02.
f.	Make note of the Main, Cache, and Survey database names.
g.	Take a backup of the data in the following tables of the main database: – DatabaseConnection – PGMMulticast – CimServers – Services
3.	*Make note of all Config* tables in the production instance and generate “.ini” files for Channels Service and the CommCore Services.*
a.	Run the following query in the Channels database (Main) and make note of all the entries of CommCore Services in the Services table. Select * from Services. Note: This information is required to manually generate the setup.ini files.
b.	Remove the Main,Cache and Survey databases in the production instance.
c.	Restore the Channels database (Main)and Survey database from the *non-production (test)* instance to the *production’s SQL server with the database names as in the production* instance.
d.	In the Mail Message table of Channels database (Main)of the *non-production (test)* instance, update Mail Source to 0. Note: This setting is to ensure that new emails are not pulled to the *non-production (test*) instance.
4.	Create the Cache Database.
a.	Create a new cache database in the *production* instance SQL server.
b.	Ensure that the new Cache database name is same as the Cache database that existed in the *production* server.
5.	*Enable the brokerservice* in the Survey database.**
6.	Perform a cleanup of the following tables in the restored Channels database (Main) of the production instance, by deleting all entries in them: – Services table – CimServers table – ServicePartition table – PGMMulticast table – DatabaseConnection table
7.	Set INIT_CACHE value.
a.	In the Windows Registry of the Channels Server, navigate to : HKEY_LOCAL_MACHINE\ SOFTWARE\Wow6432Node\ MoxieSoft\NetAgentServer\ 10.10.137.171 \CurrentVersion \INIT_CACHE
b.	Set the value of INIT_CACHE to 1. Caution: Ensure that the value ofINIT_DBis set to0.
8.	Perform one of the following: – Option 1 - Generate the setup.ini files manually for CommCore Services. – Option 2 - Copy the data backed-up in into respective tables.
9.1	Option 1: Generate the setup.ini files manually for CommCore Services.
a.	Delete the setup.ini files from the bin folders of the services: – Attachment, Post Office, Workflow, Router.
b.	Create a *setup.ini* file for each CommCore Service and place it in the respective bin folders. See “Sample .ini file templates” for help during this step.
c.	Use the information captured in Step 3a and create a setup.ini file for each CommCore Service. – Attachment, Monitor, PostOffice, Workflow, Router.
d.	Start IIS.
e.	Start Channels Service.
f.	Start all CommCore Services at least once so that the entry is made in the respective Services table: – Monitor Service – Attachment Service – Workflow Service – PostOffice Service – Router Service If any CommCore Service failed to start in the first attempt, restart the service after entries of all the other services are made in the Services table.
g.	Start the Survey Service.
h.	Validate the data in the following tables after starting all the services: – Services – PGMMulticast – CimServers – DatabaseConnection
i.	Enable the SQL Agent Job created to synchronize the cache database in the production instance. Note: This functionality was introduced in Channels 9.2-HF1 P02
9.2	*Option – 2: Copy the data saved in Step 2g into respective tables.*
a.	Start the IIS.
b.	Start the Channels Service.
c.	Start all the CommCore Services at least once so that entry will be made in the Services table. If the CommCore Service is failed to start in the first attempt, then restart the service after entries of all the other services are made in the Services table. – Monitor Service, Attachment Service,Workflow Service, PostOffice Service,Router Service
d.	Start the Survey Service.
e.	Validate the data in the following tables after starting all the services: – Services – PGMMulticast – CimServers – DatabaseConnection
f.	Enable the SQL Agent Job created to synchronize the Cache database in the *production* instance. Note: This functionality was introduced in Channels 9.2-HF1 P02.

At this point the database migration is complete.

Sample .ini file templates

This section includes sample content for the following .ini setup files.

Attachment Service
Monitor Service
Workflow Service
PostOffice Service
Router Service
PGM

Attachment Service Setup.ini

[ServiceInfo]
AuthenticationKey= [password]
CompanyId=1
Description=Attachment Service <- can be anything
HostName=[FQDN of server for the service]
Port=[Unused Port number]
Protocol=[1 =TCP, 2= HTTP]
Secured=0
ServiceName=AttachmentService [Whatever service name you typed in the installer] 
Must match what is in the servicename.exe.config file
ServiceType=6 [PostOffice =1, Monitor =2, Channels =3, Router =4, Workflow =5, Attachment =6]
Path=/channels/ [postoffice, monitor, router, workflow, attachment]
ServiceGroupID=1
Monitor Service setup.ini 
[ServiceInfo]
AuthenticationKey=test123
CompanyId=1
Description=Monitor Service
HostName=cimserver1@moxiesoft.corp
Port=102
Protocol=2
Secured=0
ServiceName=MonitorService
ServiceType=2
Path=/channels/monitor
ServiceGroupID=1
Workflow Service setup.ini 
[ServiceInfo]
AuthenticationKey=YourKey
CompanyId=1
Description= Workflow Service
HostName=ServerName.domain.com
Port=103
Protocol=1
Secured=0
ServiceName=WorkflowService
ServiceType=5
Path=/channels/workflow 
ServiceGroupID=1

PostOffice Service setup.ini

[ServiceInfo]
AuthenticationKey=YourKey
CompanyId=1
Description= PostOffice Service
HostName=ServerName.domain.com
Port=104
Protocol=2
Secured=0
ServiceName=PostOfficeService
ServiceType=1
Path=/channels/workflow 
ServiceGroupID=1

Router Service setup.ini

[ServiceInfo]
AuthenticationKey=YourKey
CompanyId=1
Description= Router Service
HostName=ServerName.domain.com
Port=105
Protocol=2
Secured=0
ServiceName=RouterService
ServiceType=4
Path=/channels/router 
ServiceGroupID=1

PGM setup.ini

[PGMInfo]
CompanyId=1
ChannelsPGMIP=[The value from MulticastIP column of PGMMulticast table with record having column PGMType as
0in the production PGMMulticast table]
ChannelsPGMPort=[The value from MulticastPort column of PGMMulticast table with record having column 
PGMType as 0in the production PGMMulticast table]
CommCorePGMIP=[The value from MulticastIP column of PGMMulticast table with record having column 
PGMType as 1in the production PGMMulticast table]
CommCorePGMPort=[The value from MulticastPort column of PGMMulticast table with record having column 
PGMType as 1in the backed up production PGMMulticast table]

Note: The .ini file created for PGM configuration as above, should be named setuppgm.ini and be placed in the following folder:

<NetAgentServerInstallPath>\CommCore Services\CompanyName\Monitor\bin\