Skip to main content
Matrix42 Self-Service Help Center

Installation: Step by Step

Overview

You can either install Matrix42 Enterprise Service Management on one server (all-in-one installation) or distribute it on two servers (distributed installation on the Web server and the database server). This topic describes the all-in-one installation in detail and includes comments and installation tips.

Preparation

Antivirus and various Monitoring Software (e.g. PRTG) can impact the installation process and lead to errors. Please consider pausing them for the time of the installation.

Save the Matrix42.Setup.exe file on your server and run it. The Matrix42 Setup Wizard will be launched:

install_welcome.png

For Windows Server 2008 and greater, right-click the .exe file, and then click Run as Administrator.

Installation process

Click Launch the installation process.

If you are installing test, demo or training environment, you can run the Advanced Options to skip some of the configuration steps.

Choose the Advanced Options in case specific setup steps or system requirements should be ignored:

install2_2023.png

Read the License Agreement. Click Accept to accept the license agreement.

System prerequisites

Then the installation wizard will check the system prerequisites.

If your system does not meet all system prerequisites, those missing will be displayed under Required Components. Click the respective component to get more details.

System prerequisites and their configuration examples can be found on this page.

install2_1_2023.png

Freely available system components can be downloaded together with the installation file (the REDISTB.zip file) or are supplied on the CD. To continue the installation, you should install all missing components.

Application Server and Service Account

  • The installation wizard will select the default installation path (C:\Program Files (x86)\Matrix42\Matrix42 Workspace Management\) for the installation files. You can change this installation path by using the Browse button.
  • Under Service Account, enter the Login and the Password. Click Next.

This account is used to communicate with IIS [application pool] and receive client requests.

install3_2023.png

The service account is specified as the owner of the databases on the database server.

License Certificates

  • Now you should license the installation. If you use the online activation option, enter your license key in the License Key field, and then click Activate License (active Internet connection is required for this purpose).

If you use a certificate as a license key, click Browse Certificates. Save your certificate(s) to the suggested Certificates Directory and close it. The certificate(s) will appear in the list under Manual Activation

  • When necessary certificates are added, click Next.

install4_1_2023.png

Administrative user

  • Create an administrative user for interactive login to Matrix42 Enterprise Service Management and click Next.

Enter your installation user or the user that will open the application for the first time and will add other users.

install5_2023.png

E-Mail and Default Language 

  • Specify your E-Mail Settings: SMTP Server, Default Sender, Authentication details, and Password. This information will be used in notifications and other types of emails. E-mail settings can be later changed in the Global System Settings in the Administration application.
  • Select the Default Language of your environment. These settings can be changed in the Regional Settings of the Administration application.
    install6_1_2023.png
  • You should also specify whether you want to Send test mail to check SMTP server configuration.

You may skip this step by clearing the Send test mail to check SMTP server configuration checkbox. If you leave it selected and then click Next, an error message (in red) will appear at the top of the window. Click the respective error message:

SVS_INST_010.png

Now you can click Skip to skip the configuration process.

Database Server, Authentication and Databases

  • Enter your SQL Server Name, possibly including the instance name, and apply all other default settings.
  • Connect via defines the credentials for the database connection, in particular,  for the Production-DB, History DB, Data Warehouse DB, as well as Analysis Services DB, that is configured in the next step:
    • Windows Authentication is pre-selected by default and the current Windows account credentials are used for authentication and database connection.
    • SQL Server Authentication option requires Login and Password to be specified for connection.

      You can change the connect via option later on by running the Configuration Wizard → Change Service Account section.

  • Enter the Database names. We recommend that you apply the automatically inserted values for the Production-DB, History DB and Data Warehouse DB.

Enter the local SQL server name if you want to perform an all-in-one installation and the remote SQL server name for a distributed installation.

The pre-configured SQL server should operate in the mixed mode [SQL Server and Windows authentication mode] and is configured with "Latin1_General_CI_AS" or "SQL_Latin1_General_CP1_CI_AS" collation.

Database settings can be previewed in the General section of the Global System Settings in the Administration application. To change the database settings for the installed Matrix42 system, refer to the corresponding section of the Configuration wizard.  

install7_2023.png

Click Next to proceed.

Analysis and Reporting Services

  • Enter the Analysis Services Server and the Analysis Services DB. In most cases, you can apply the suggested entries. 
  • Enter the Reporting Services URL. The default name of this website is http://<Servername>/ReportServer. It will be specified during the configuration of MS SQL Reporting Services. In most cases, you can apply the suggested URL to the installation server.
  • Specify Reports Root Folder.

Report Root Folder does not support subfolders

To avoid time-outs during the first creation of the report, open  browser and enter the Reporting Services URL. Do not close the browser

install8_2023.png

Click Next to proceed.

Service Layer Configuration: Workflow Databases 

  • Specify the Service Layer Configuration parameters for your Matrix42 Enterprise Service Management environment. First, enter the names of the Workflow Persistence and Monitoring databases.

You can apply the automatically specified values for all-in-one installation:

09_install2023.png

Click Next.

Service Layer Configuration: Security Configuration

The configuration differs depending on the installed system version.

  • DWP v.10.1.1: AppFabric settings are no longer available and the setup wizard shows a warning message about the AppFabric discontinuing in the next version. 
  • DWP v.11.0: This step is no longer available for the new DWP v.11.0 installation, as the AppFabric technology usage is discontinued in the system.
  • Specify the Security Configuration parameters for Service Layer. Please make sure that the specified Security Group for AppFabric configuration exists (was created manually) on the distributed server/in the domain. Members of this group should be assigned write rights on the Workflow Persistence and Monitoring databases. Matrix42 Service Account should also be a member of this group.
  • Finally, select the Run AppFabric with Matrix42 Service Account checkbox for distributed installation. To protect the Service Layer connections, the service and client certificates will be generated and installed on the local computer.

SVS_INST_014_1.png

Click Next.

Security Configuration: SSL

Configure the security options of Matrix42 to protect the data that you process with Matrix42 Enterprise Service Management.

  • Use the HTTPS protocol if you want to encrypt your data when connecting to the Matrix42 Enterprise Service Management Console and Matrix42 Self Service Portal. To use the HTTPS protocol, you should specify the settings for Secure Socket Layer (SSL). The Domain name that you use for Matrix42 Enterprise Service Management is filled in automatically – the system reads it from the default IIS website – but you can change it.
  • Then you should choose whether to Use your own SSL Certificate or Use Self Signed Certificate.
    • If you use your own SSL certificate, then all necessary settings are defined automatically based on the provided domain name.
    • If you use a self-signed certificate, then you should provide a password to create this certificate.
  • Since 10.0.1 release, Force SSL option is the only possible. It means that when someone opens the console or the portal with the HTTP URL, they will be redirected to the HTTPS URL.

You can change the configuration settings later either in the Configuration Wizard or in the Global System Settings of Matrix42 Enterprise Service Management.

install9_2023.png

Click Next.

Replacing the SSL certificate at a later point can be done by installing the new certificate and update the binding of the site hosting the application; usually the default website.

Security Configuration: Captcha, Lock Accounts, Encrypt Viewstate

Continue with Security Configuration:

  • Select the Activate captcha checkbox to prevent automatic logins to the Matrix42 Self Service Portal or Matrix42 Enterprise Service Management Console from external sources. The captcha will be displayed after the first unsuccessful login attempt.
  • Use the Lock Accounts option for more advanced protection from automatic logins. Enter a number of unsuccessful login attempts after which the account will be locked, and a time period (in minutes) after which the account will be unlocked. Please note that the minimum number of attempts should be 3, and the minimum time period should be 10 minutes. Information about all (un)successful login attempts and account (un)locking events including the IP addresses is stored in the Matrix42.Security.log file under %programfiles%\Matrix42\Matrix42 Workspace Management\Logs. In addition, information about failed login attempts and locked accounts is stored in Windows Event Log (Applications) under the M42_SEC event name.
  • For earlier versions of DWP that still support Classic UI, select Encrypt VIEWSTATE checkbox to encrypt information that is passed to the server every time someone changes data in Matrix42 Enterprise Service Management. This setting provides additional client side security, but be aware that it may decrease client performance when opening dialogs.

You can change these settings later either in the Configuration Wizard or in Global System Settings of Matrix42 Enterprise Service Management.

install10_2023.png

Click Next.

Security Configuration: STS (Secure Token Service)

  • To use the Secure Token Service, specify the Host name and click Next. The metadata and authentication settings of the application relying on STS will use the tokens received from the token provider for validating the user credentials. The token includes multiple elements regarding the identity and group membership of the client, as well as information regarding the lifetime of the token and the issuer of the token. The token is protected from manipulation with strong encryption.

install11_2023.png

  • Advanced settings: select the checkbox to configure Load Balancer:

install12_2023.png

Cache Configuration: In-Memory or Redis cache provider

This step is available for the DWP v.11.0 and greater.

Please define whether the application should utilize a built-in In-Memory cache or Redis distributed caching provider. It is important to identify if the current installation of Matrix42 Software is going to be used as a node in a multi-clustered infrastructure. In such a case, to effectively interact with other nodes in a cluster the application must be connected to Redis to share its own cache and utilize the cache from the rest of the servers. This will allow the system to manage the cache properly and keep it in sync among the nodes.

Single server setup will not require such synchronization, so the built-in In-Memory cache is the option that will guarantee the application stable work.

In-Memory cache is strongly recommended for a single instance installation. 

  • In-Memory cache will not require any additional configurations:
    install13_2023.png 
  • Redis cache will require Redis server installed and available for new connections. The connection properties should be provided on the screen below: 

    • Host: Redis Server host or IP address (i.e., 127.0.0.1, localhost, domain.com, etc.) 
    • Port: Port number to accept connections. The default Redis port is 6379. 
    • User: Redis server login username (available for Redis server starting from version 6.0). Otherwise, the parameter gets ignored while establishing Redis connection. 
    • Password: Redis server login password (available for Redis server starting from version 6.0). Otherwise, the parameter gets ignored while establishing Redis connection. 
    • Database: The database index the Redis server should consider as a default database. All the cache traffic will be sent to this database.  
    • Encryption: Define whether the connection should be encrypted using SSL. 

The wizard will validate socket connectivity using provided host and port when clicking on the Next button. Redis cache provider configuration goes to SPS.config after successful installation (see Matrix42.Distributed.Redis.Cache section). 

install13_1_2023.png 

Redis Cache configuration example

Click Next to proceed. 

Summary

An overview of the collected information will be displayed:

install14_1_2023.png

Click Next to run the installation.

Installation

The setup wizard will now install and configure Matrix42 Enterprise Service Management. This process will take from 30 to 60 minutes, please wait:

install15_2023.png

For the installation process details, click the "View Log" button.

Additionally, the wizard suggests the following links:

  • Release notes include a list of all releases and a detailed description of the features and changes included in the corresponding product version;
  • Visit our website link for more information on Matrix42 company and products.

If the installation is manually aborted and is canceled during the rollback process the consecutive run of the Matrix42 setup wizard can result in an error. Open the command prompt as an Administrator and run the following command from the folder with the Matrix42 setup file to initialize the setup wizard:

matrix42.setup.exe --install

Publishing Workflows

While Publishing workflows it is possible that some workflows are not able to be published due to different reasons. The setup itself will automatically retry (3 times) publishing workflows that failed to be published. That may fix some failures that occurred due to locked files or directories.

Publish failure reasons are listed in a setup log, displayed above the progress bar.

If after 3 retries some workflows remain unpublished, the Setup wizard will alert the user about the actions that may be performed.

popup_21_2023.png

You may either decide to skip publishing failed workflows (and optionally publish them later) by clicking "Yes" button, or fix the issue and retry publishing them. In that case, you should click "No" in a pop-up dialog and click "Retry" button when the issue is resolved.

retry1_2023.png

Completed Installation

  • The setup wizard will inform you that the installation is completed successfully:

install16_2023.png

  • Click the Installation Summary Report to view more details about the changes that have been made on the installation server during the installation/configuration.
  • Select the Launch Matrix42 Software Asset  & Service Management checkbox if you want to open the UUX version and login in the browser.
  • For earlier versions with Classic UI, select the Launch Matrix42 Software Asset  & Service Management Console checkbox if you want to open the console directly after the installation.
  • Click on the suggested links to see more details about Enterprise Service Management and Digital Workspace Platform key features.
  • Click Finish.