Riva Insight On-Premises Setup Guide (Insight 2026.3 and later)

Curtis Massie
Curtis Massie
  • Updated

This document explains how to deploy the unified Riva Insight Services project on an on-premises Windows server. The Services project combines Insight, WebAPI (Riva Sync compatibility), and TrackStateService (TSS) into a single Kestrel-based application running as a Windows Service.

 

Prerequisites

  • Windows Server 2022 or later
  • ASP.NET Core Runtime 8
  • Redis installed and running (required for session sharing and caching)
  • A valid TLS/SSL certificate (if not using a load balancer for TLS termination)
  • Riva Sync installed and configured with a valid connection.
  • MongoDB instance (required for TrackStateService)

 

Install or Setup Prerequisites

  1. Install ASP.NET Core Runtime 8.0
  2. Install Redis 
  3. Install MongoDb
  4. Install SSL Certificate
  5. Create Microsoft Entra Id App Registration
  6. Create Salesforce External Client Application (ECA)

 

Download/Extract Riva Insight Service 

  1. Download the package from https://dl.rivacrmintegration.com/ (ensure version is 2026.3 or later)
  2. For the downloaded file, go into the properties and select "Unblock"
  3. Extract the contents to a location you would like the application hosted (i.e. C:\Riva\Riva Insight\)

Riva Insight App Configuration


The configuration settings for the Riva Insight app are configured in appsettings.OnPremises.json. The setting with the file will look something like the following once setup has been completed:

{
  "AppSettings": {
    "BasePath": "/insight",
    "Insight.Port": "5001",
    "LoggingLevel": "ERROR",
    "Sync.Compatibility.connectionFilePath": "C:\\Riva\\Riva Sync\\Configuration\\user@example.com__www.salesforce.com.connection",
    "Sync.Compatibility.applicationDirectoryInfo": "C:\\Riva\\Riva Sync\\Configuration",
    "HTTPSCertificate": {
      "UseCertificate": "true",
      "UseCertificateStore": "true"
    },
    "CertificateStore": {
      "SslCertificateFindByValue": "{value}",
      "SslCertificateFindBy": "FindByThumbprint",
      "SslCertificateStoreName": "My",
      "SslCertificateStoreLocation": "LocalMachine"
    }
  },
  "ConnectionStrings": {
    "RedisConnectionString": "{RedisHost}:6379,password={RedisPassword}",
    "Insight.Auth.Salesforce.Oauth": "Key={SfConsumerKey};Secret={SfConsumerSecret};",
    "Insight.Graph.OAuth": "ApplicationId={AppId};Tenant={Tenant};Authority=https://login.microsoftonline.com/{Tenant}/oauth2/v2.0"
  },
  "MongoDb": {
    "Client": {
      "ConnectionString": "mongodb://{user}:{pass}@{host]:27017/Default?tls=false",
      "DatabaseName": {
        "TrackStateService": "TrackStateServiceDb"
      },
      "CollectionName": {
         "TrackStateService": "TrackStateServiceCollection"
      }
    }
  }
}

 

App Settings

Base Settings

This is the primary configuration file. It is in root folder of the Insight Application

NOTE: When setting up multiple Insight services on the same machine, Insight.Port must be different for each service.

Setting Description
BasePath The URL path suffix for the application (e.g. /insight, /insight-uat). All requests must include this suffix.
Insight.Port The TCP port Kestrel listens on. Defaults to 5001 if not specified. Must be unique if running multiple Insight instances on the same server.
LoggingLevel

 Logging Level.  Options: 

  • ERROR (default)
  • WARN
  • INFO
  • TRACE
# EnvironmentLogPathSuffix   Used to differentiate logs between Insight applications.

 

CRM Connection

  1. For Sync.Compatibility.connectionFilePath setting, add the path (including filename) to the connection file.
  2. For the Sync.Compatibility.applicationDirectoryInfo setting, add the path to the location containing the sync configuration files.

Setting Description
Sync.Compatibility.connectionFilePath Full path to the Riva Sync .connection file for this user/org.
Sync.Compatibility.applicationDirectoryInfo Path to the Riva Sync configuration directory.

SSL Certificate

  1. The certificate should be in the 'LocalMachine/My' certificate store
  2. Add the thumbprint of the certificate to the SslCertificateFindByValue setting.

Setting Description
SslCertificateFindByValue The Subject Name of the certificate.

If SslCertificateFindBy is set, then the lookup would be based on the FindBy method defined.
# SslCertificateFindBy

Determines whether to look up the certificate by name or thumbprint (case-sensitive). Recommended Options: 

  • FindBySubjectName 
  • FindByThumbprint (default)
  • FindBySerialNumber
  # SslCertificateStoreName

Name of the certificate store. Default is My. Recommended Options:

  • My (Personal) -- default
  • Root (Trusted Root Certification Authorities)
  • CA (Intermediate Certification Authorities)
  # SslCertificateStoreLocation Location of the certificate store. Default is LocalMachine.

Connection Strings

Redis

Redis is used for session management and distributed caching. All servers in a multi-server setup must point to the same Redis instance.

Look for a connectionstring similar to the following: 

"RedisConnectionString": "{RedisHost}:6379,password={RedisPassword}"

Setting Description
RedisHost Redis host ip address or DNS name.
RedisPort   Redis Port. The default port of 3679 is configured by default.
RedisPassword Redis password

Salesforce External Client Application (ECA)

Look for a connectionstring similar to the following: 

"Insight.Auth.Salesforce.Oauth": "Key={SfConsumerKey};Secret={SfConsumerSecret};"

Setting Description
SfConsumerKey Salesforce External Client Application Consumer Key
SfConsumerSecret   Salesforce External Client Application Consumer Secret

 

Microsoft Entra Id App Registration

Look for a connectionstring similar to the following: 

"Insight.Graph.OAuth": "ApplicationId={AppId};Tenant={Tenant};Authority=https://login.microsoftonline.com/{Tenant}/oauth2/v2.0"

Setting Description
AppId The Application (client) ID of the Entra Id App Registration
Tenant   The Tenant ID or Domain Name.

Connection String - MongoDB

Look for a connectionstring similar to the following: 

"ConnectionString": "mongodb://{MongoUser}:{MongoPassword}@{mongohost):27017/?tls=false"

Setting Description
MongoHost Mongo host ip address or DNS name.
MongoPort   Mongo Port. The default port of 27017 is configured by default.
MongoUser MongoDB User
MongoPassword   MongoDB Password

Related Article:


Start and Verify Riva Insight

If running multiple instances of Insight, each service will needs its own unique name. 

NOTE: When setting up multiple Insight services on the same machine, each Insight Service must be given its own unique name (replace RivaInsightServices in the following steps).

Register the Service

Powershell (run as Admin)

New-Service -Name "RivaInsightServices" -BinaryPathName "C:\Riva\Insight\Omni.Riva.Insight.Services.exe" -StartupType Automatic
 
Setting Description
-Name Name give to the services (each app requires its own unique name)
-BinaryPathName   Redis Port. The default port  of 3679 is configured by default.

Next, configure the service to delay start in the event of a reboot to allow other dependent windows services to start first.

sc.exe config "RivaInsightServices" start=delayed-auto

Start the Service

The service may be started from the Windows Services control panel, or through PowerShell.

Powershell (run as Admin)

Start-Service -Name "RivaInsightServices"
 

If the service fails to start, check the logs located under:

  • %programdata%\riva\insight\

 

Service Recovery Settings

Once we have confirmed the service is able to start, we can configure the service to restart in the event it unexpectedly stops.

sc.exe failure RivaInsightServices reset= 86400 actions= restart/60000/restart/120000/restart/300000

sc.exe failureflag RivaInsightServices 1

 

Health Check Diagnostics

Load the Insight Diagnostics page to ensure all Insight Services are running. 

To access the diagnostics page, append health.check?diagnostics=true to the end of the Insight URL. 
  E.G.  https://rivainsight.company.local/insight/health.check?diagnostics=true

 
NOTE: If configuration changes are made, the server must be restarted in order for the changes to get picked up. The service may be restarted from the Windows Services control panel, or through PowerShell.

Powershell

Restart-Service -Name "RivaInsightServices";
 

Configuring Riva Sync for Riva Insight

Load Balancing Requirements