Reference Guide - Install CM4D Results Services v25.1

This guide contains the basic steps for installing and configuring the CM4D Results services. This topic is intended for any machine that will host the Results Services and are part of a larger setup that includes a CM4D Server connecting to a centralized database.

Install Overview

This installation includes the following steps:

Run the CM4D Results Services Installer
1. Features and Installation Folder
2. Configure Database Options
3. Configure NServiceBus Transport Options
4. Configure NServiceBus Service Control
5. Configure SQL Connections for Site/Results Database
6. Configure SQL Connection for Transport/Persistence Databases
Install and Configure ServiceControl Manager

Quick Steps for Basic Install

If you simply want to install one instance of the Results services to run local to your CM4D Server, select the following options during installation:

CM4D Database Options - Use .4ds File
NServiceBus Transport Options - Site Database (Transport and Persistence)
ServiceControl Queues - Use default labels.

Installation Terminology

Some concepts you need to know to perform this installation:

Transport - The NServiceBus transport is the way the messages are sent from one node to another. The system can be a distributed deployment, such as a local CM4D Site database and a cloud-based Results database. There are multiple transport options available.
1. Site/SQL Database - The SQL transport uses database tables to implement the message queues that connect the different services. This service is simple to configure as it can use the SQL Server that is used for CM4D databases. However, it does not provide the same throughput and scalability as other transport options.
2. RabbitMQ - RabbitMQ is a high-performance open-source message broker with wide industry usage. RabbitMQ can be installed on-premises on a server, as a container or used as a service at service providers like CloudAQMP. The free plan is sufficient to test this transport. A RabbitMQ connection string requires a host, username, password and a virtual host.
3. Azure Storage Queue - Azure storage queues are a transport option for cloud-based or hybrid deployments. This option requires an Azure Storage Account. The connection string can be copied from the Azure storage account access key page.
Persistence - Information about messages might need to be stored to ensure transactional consistency of long-running transactions. The persistency configuration defines where the data is stored. It is recommended to store it in the CM4D Site database, but another database can be configured if necessary. Additional persistency options will be available in future releases.
Transport Queues - The Transport Queues are database tables created by ServiceControl where the Results services store monitoring information for ServiceControl. In ServiceControl Manager, these tables are specified as the Subscription Table in the transport connection string of each instance.

Prepare for Installation

Contact your ATS sales representative or ATS Support if you have questions or need assistance.

Gathering the following downloads and information is helpful before running the installer.

Download installers/files referenced in this guide.
		ATS CM4D Results Services installer.
		ServiceControl Manager software from Particular Software: ServiceControl - Collects data from endpoints. ServicePulse - A web-based application to inspect failed messages and resubmit them and to monitor the availability and performance of endpoints. ServiceInsight - Supports auditing of message details but has a major performance impact. At a minimum, it is strongly recommended to use ServiceControl and ServicePulse. You need to configure at least one instance of ServiceControl and Auditing and one Monitoring instance for the transport method chosen during the installation of the Results service.
Optional information that is useful to have on hand during the installation and setup process.
		CM4D Database Information - CM4D Site and Results database connection strings, including the server name and SQL authentication user/password.
		NServiceBus Transport Information (optional) - If using a Transport/Persistence option that is not the CM4D Site database, you must provide the alternative connection information (SQL, RabbitMQ or Azure Storage Queue.

Install CM4D Results Services

Run the CM4D Results Services install executable (as Administrator).
Accept the terms of the Licensing Agreement.
Select the Features (i.e., pick which Results services to install). Only ONE instance of each of the three Results Services is supported per server.
Set the Installation Folder.
Choose a Database Connection. Select the method by which the services connect to the CM4D databases.
1. Use .4ds File - If CM4D is installed on this machine, the services obtain database connection information from the DbConnect database connection file (CM4D.4ds) registered on the local system. The 4ds file provides both the Site Connection and the Results database connection strings to the Results Services.
2. Specifiy Database Credentials - If CM4D is not installed on this machine, manually enter the database connection information during the installation. Later steps in this installation prompt manual entry of the database connection information for both the Site and the Results databases.
Configure NServicebus Transport Options. Configure the same database transport and persistence for the ServiceControl configuration you are using.
Configure NServiceBus Service Control. Enter the name of the database queue tables for ServiceControl monitoring. These Queue labels must match what is defined as the Subscription Table in the connection string entered when configuring ServiceControl instances.
Configure SQL Connections for Site/Results Database. The configuration steps for entering the Site and Results database connection information is only required if you selected the Database Connection option 'Specify Database Credentials'. And depending on the services you selected in the first part of the installer, you may see only the Site database connection screen or both the Site and Results database screens. If you are installing only the Results Sender service, the Results database connection is not required.
Configure SQL Connection for Transport/Persistence Databases. The configuration steps for entering the Transport and/or Persistence database connection information is only required if you selected 'Other SQL Database' for the NServiceBus transport options.
Finish the install.

Install and Configure ServiceControl Manager

Configure ServiceControl Manager. ServiceControl is a third-party application that supports the Results Sender and Loader services communicating messages between the CM4D and Results databases. The following installation instructions are only an example of a generic installation. Your system configuration may require other settings and transport options.
1. Install ServiceControl Manager Software. Download and install the following applications from Particular Software:
  1. ServiceControl - Collects data from endpoints.
  2. ServicePulse - A web-based application to inspect failed messages and resubmit them and to monitor the availability and performance of endpoints.
  3. ServiceInsight - Supports auditing of message details but has a major performance impact.
2. Configure ServiceControl Monitoring. Once the installations are complete, run ServiceControl Management.
  1. Add a License.
    1. Click License.
    2. Click Import License.
    3. Browse to the CM4D installation folder and locate the file 'License.xml' in the StreamCacheSmith subfolder.
    4. Click Open.
  2. Create a New Monitoring Instance.
    1. Click New.
    2. Click Add Monitoring Instance.
    3. Enter a Name for the Windows service (e.g. 'Particular.Monitoring').
    4. Enter a Description.
    5. Select User Account and enter the same user credentials as used for the CM4D Services (e.g., cm4dservice).
    6. Leave the Host set to 'localhost' unless a change is required.
    7. Enter the port number.
    8. Open the Transport menu and select SQL Server.
    9. In the Connection string, enter the full string for connecting to your CM4D Site database, according to the type of Authentication that grants access to CM4D databases.
      1. Windows Authentication [Data Source=cm4dserver25;Initial Catalog=25SITE;Integrated Security=True;Queue Schema=dbo;Subscriptions Table=Particular.Monitoring]
      2. SQL Authentication [Data Source=cm4dserver25;Initial Catalog=25SITE;User id=sqluser;Password=pass1234;Queue Schema=dbo;Subscriptions Table=Particular.Monitoring]
    10. Click Add.
  3. Add New ServiceControl Instance.
    1. Click New.
    2. Click Add ServiceControl and Audit Instances.
      1. Enter a Name for the Windows service (e.g. 'Particular.ServiceControl').
      2. Open the Transport menu and select SQL Server.
      3. In the Connection string, enter the full string for connecting to your CM4D Site database, according to the type of Authentication that grants access to CM4D databases.In the Connection string field, or paste the connection string from the ServiceControl instance.
    3. Expand ServiceControl and go to the General section.
      1. Select User.
      2. Enter the same user credentials as used for the CM4D Services (e.g., cm4dservice).
      3. Leave the default settings for the remaining options.
    4. Expand ServiceControl Audit and go to the General section.
      1. Select User.
      2. Enter the same user credentials as used for the CM4D Services (e.g., cm4dservice).
      3. Leave the default settings for the remaining options.
    5. Click Add.
3. Confirm Configuration. Once the monitoring and service control instances are set up, confirm the following:
  1. Windows Services - Check that the Particular services are running.
  2. Check Site Database Tables - Check that the five tables corresponding to the two new instances (1 for Monitoring, 4 for ServiceControl) appear in the CM4D Site database.
4. Run ServicePulse. The ServicePulse application is accessed via a shortcut provided in the Windows Start menu or manually enter the web server and the port (default: localhost:9090) used during the ServicePulse installation.\
5. Run ServiceInsight. Open the ServiceInsight application and connect or configure as needed.