Migrating the Databases to a New Server

Last updated
Save as PDF

The process of migrating the databases to a new server is supported by the Configuration Wizard.

Shut Down the Application

Before you start the migration process, shut down the application to avoid data loss. To shut down the application, perform the following steps:

Stop the following Windows services:
- Matrix42 Host Common
- Matrix42 Host Common X86
- Matrix42 Scheduler
- Matrix42 Workers
- AppFabric Workflow Management Service (skip for environments that run on Matrix42 Worker only)
- AppFabric Event Collection Service (skip for environments that run on Matrix42 Worker only)
Stop Internet Information Services (IIS)

Back Up the Databases

Perform a full backup of the following databases:

Main Database (by default M42Production)
History Database (by default M42Archive)
Warehouse Database (by default M42Warehouse)
Reference Database <MAIN DB>_REF (by default M42Production_REF).

Skip this step for DWP v.11.0.1 and higher as for these versions Reference Database is obsolete.
Workflow Instance Store (by default M42InstanceStore)

There are more databases related to Digital Workspace Platform, such as Workflow Monitoring (M42Monitoring), SSAS Cube (M42AnalysisServices), and Staging databases that are used by Data Providers. However, these databases contain no critical data and can be recreated from scratch at any time. In case of recreating make sure that all databases have the same collation.

For more information about the databases that are used, see How to Determine Which Databases are Used by DWP Installation.

Restore the Databases

Change the Application Configuration

Reconfigure the Application to Use the New Database Server

To reconfigure the Database Server, perform the following steps:

Run Configuration Wizard.
Click Change Configuration → Change Database Server.
Specify New Configuration for the Database Server.
Click Next to apply the configuration.

You can also reconfigure the Database Server manually. In this case, you should adjust all connection strings that are defined in How to Determine Which Databases are Used.

Reconfigure the Service Host

Open the <INSTALL DIR>/bin/sps.config file in any text editor and make sure that the settings are correct:

<Matrix42.ServiceLayer
    ...
    servicesHost="localhost"
    discoveryHostName="<FQCN>"
    appFabricAdminGroup="<DOMAIN>\AS_Administrators".
    ...
/>

servicesHost: equal to "localhost"
discoveryHostName: fully qualified computer name or domain name that is used to access the Digital Workspace Platform Console. This name should match the SSL certificate of the IIS website on which DWP is installed.
appFabricAdminGroup: Domain group that is used to access the Workflow Monitoring database and the Instance Store database (this configuration is removed for environments that run on Matrix42 Worker only).

By default, the setup uses fully qualified computer name (FQCN) as discoveryHostName and generates a self-signed SSL certificate with the corresponding CN (common name). If you use custom domain name and SSL certificate, then you should migrate the certificate manually and configure it to be used as discoveryHostName.

Reconfigure E-mail Settings

No additional configuration for e-mails is required in case of the databases migration to a new server.

When you migrate the application to a new server, the sending of the e-mails will fail because the installation ID has changed in the sps.config file and it no longer matches the ID in the database. For more information, see Workspace Management does not send e-mails: "Installation ID does not match. Message will not be sent" page.

Reconfigure Matrix42 Workers

Matrix42 Workers are external processes that constantly stay in touch with Application Server. Suppose the Application has been relocated to another server. In that case, the configuration of all related Workers needs to be adjusted to reference the DNS of a new Server and Access Token need to be re-encrypted with a new machine key.

Set Server Name

Open <Worker_Install_Dir>/Core/Matrix42.Worker.Host.exe.config file in a text editor and change the "ServerName" setting to a new value:

<add key="ServerName" value="<New Server DNS>" />

Update API Token (for versions < [10.0.4])

The Matrix42 Worker uses the API Access Token for authentication with the Application Server, which is encrypted with Machine Key in the <Worker_Install_Dir>/Core/Matrix42.Worker.Host.exe.configfile. The token section needs to be removed from the Config file, the correct token will be automatically generated by the Setup wizard

 <connectionStrings configProtectionProvider="DataProtectionConfigurationProvider">
  <EncryptedData>
   <CipherData>
    <CipherValue>CIPHER_DATA</CipherValue>
   </CipherData>
  </EncryptedData>
 </connectionStrings>

Update to a new SQL server version

There are 2 main scenarios when you update your SQL Server to a new version. Either you update to a SQL version that is still supported by your installed product version or you update to a SQL version that is no longer supported by your product version. In the second case, you have to update your product immediately after you updated your SQL server.

Update to a supported SQL Server version
Perform the same steps as described above. If you directly update your SQL server without moving the databases, you don't need to change the application in any way.
Update to an unsupported SQL Server version and update the application
For example, SQL 2008R2 => SQL 2017, 8.1.7 => 9.0.2
- Migrate the Databases to a new SQL Server
  Perform the same migration steps as described above. Directly after you changed the configuration with the configuration wizard, update the application to the new version that supports the newer SQL server version.
- Update the SQL server to an unsupported SQL Server version
  Shut down the application, update the SQL server and update the application immediately after the switch to the new SQL server version. If the update asks you to start some services, to proceed simply start them.

The configuration wizard will not check the SQL server version when you switch to the new database server, but you should not use the application with an unsupported SQL server version!

It is recommended to update the compatibility level of your databases to the newest level supported by your SQL server.