Skip to main content
Matrix42 Self-Service Help Center

Migrating the Entire Application to a New Environment

Overview

This walkthrough provides a step-by-step guide for migrating Digital Workspace Platform to a new server environment.

This guide assumes that the application uses the distributed deployment configuration, i.e. a Database Server, where all SQL Server components are located, and an Application Server, where Digital Workspace Platform is installed.

If you need to install a later version of Digital Workspace Platform, you should update the application before migrating it.

Set Up the New Environment

To start the migration process, you should set up the new server environment and install the same version of Digital Workspace Platform on it, for example:

  • if the Source environment has v.10.1.1 then make sure that the Target environment has also v.10.1.1
  • if the Source environment has v.11.0.0 then make sure that the Target environment has also v.11.0.0, etc.

To find out which version is installed, see How to Determine Application Version.

AppFabric is deprecated and removed from DWP since v.10.1.1 therefore if you intend to continue using AppFabric after migration and have a version 10.1.1 or later in your source environment, you have to first install 10.0.2 version to a target environment and then update it to the intended version that corresponds to your source environment. 

For more information regarding the installation or update processes, please refer to Installation and Configuration and Update.

To simplify the configuration, use the same Service Account and the same database names on new servers.

After the installation, make sure that all application services are running. To do it, start Digital Workspace Platform, and then click Administration → Home → System Diagnostics.

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.

Back Up the Application Files

By default, the application is installed under C:\Program Files (x86)\Matrix42\Matrix42 Workspace Management. In some cases, a different path is used. To find out where the application is installed, see How to Determine Installation Directory.

To back up the application files, perform the following steps:

  1. Decrypt the configuration files by executing the following commands from the command line:
%SYSTEMROOT%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis -pd "connectionStrings" -app "/M42Services"
%SYSTEMROOT%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis -pd "connectionStrings" -app "/sps"
  1. Back up the entire installation directory.
  2. Back up the database encryption key file from the following directory: 

    %ApplicationFolder%/bin/securityCryptographyConfiguration.config

Restore the Application Files

To restore the application files, make sure that the application is shut down. For more information, see Shut Down the Application.

Restore the application files on the new Application Server (replace the existing files). To restore the database encryption, see the Database Security: Encryption key section. 

After this step, the application should be fully functional, but it still references the old databases.

Restore the Databases

Restore the following databases on the new environment:

  • 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)

Change the Application Configuration

Reconfigure the Application to Use the New Database Server

To reconfigure the Database Server, perform the following steps:

  1. Run Configuration Wizard.
  2. Click Change Configuration → Change Database Server.
  3. Specify New Configuration for the Database Server.
  4. 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>

Verify the Application Configuration

To verify application configuration, run the setup wizard and follow all steps as during the update. Before you start the update process, you should downgrade the application version. For example, if the version is equal to 10.0.1.1155, set it to 10.0.1.1154.

The current version of the application is stored in PLBAProductVersionClassBase data definition and the product update history is available in PLBAProductVersionClassHistory data definition.

To run Digital Workspace Platform Setup in the update mode, run the following command from the command line:

<INSTALL DIR>/bin/Matrix42.Setup.exe –update

Click Launch the update process and follow the wizard steps.

You can skip the Database Backup step by using the Advanced Options.

When the update process is finished, you should diagnose the system. To do it, start Digital Workspace Platform, and then click Administration → Home → System Diagnostics

  • Was this article helpful?