Insight 2025.2 On-premises - Track State Service (TSS) Setup

Curtis Massie
Curtis Massie
  • Updated

Requirements

  1. Riva Insight On-Premises 2025.2 or later
  2. Riva Sync On-Premises 2025.2 or later
  3. Firewall Access to the Riva Insight Server for Riva Sync
  4. ASP.NET Core Runtime Hosting Bundle
  5. MongoDB
  6. MongoDB Shell
  7. Track State Service Package
  8. Private and Public Asymmetric JWT keys (from Riva)

 

Deployment Models

The deployment model you choose is dependent on your current setup for Riva Sync.

  1. Separate Track State Services for each Insight environment
    • Recommended if using multiple sync services/pods
    • Requires a sync service/pod corresponding to each Insight environment
    • Each Insight/Sync environment will point to their own TSS Service
    • More isolation (each can have its own TSS version managed independently)
    • Add Service in Insight app folder parent I.e. C:\Riva\Riva Insight\Prod\runtime\TSS
  2. Shared Track State Services for all Insight environments
    • Recommended if using a single sync service/pod
    • Each Insight/Sync environment will point to the same TSS Service
    • No isolation  (all environments use the same TSS)

 

Install Prerequisites

Riva Insight On-Premises 2025.2

Riva Insight 2025.2 is required for using the Track State Service

  • Ensure Riva Insight is updated before proceeding with the Track State Service

Riva Sync On-Premises 2025.3+

Riva Sync 2025.2 or later is required for using the Track State Service

  • Ensure Riva Sync is updated before proceeding with the Track State Service
  • Riva Sync will need access to the Riva Insight server (same FQDN/Port used for end-user access)

ASP.NET Core Hosting Bundle

The Track State Service is built on ASP.NET Core 8.  The ASP.NET Core Runtime Hosting Bundle is required for the Track State Service to run under the Riva Insight.

  1. Download the ASP.NET Core Runtime Hosting Bundle


     
    • Ensure the download is unblocked.
       
  2. Install the ASP.NET Core Runtime Hosting Bundle
  3. Confirm that this is installed by navigating to the IIS folder located at C:\Program Files (x86)\IIS\ or C:\Program Files\IIS\

 

MongoDB Setup and Configuration

MongoDB Installation

MongoDB is used to store the Track State Data.

NOTE: The steps below are using MongoDB community version, however the decision on which MongoDB version or MongoDB compatible database to use is up to your organization.  MongoDB compatible databases must support MongoDB APIs. TSS has been confirmed for MongoDB and Amazon DocumentDB.

  1. Download MongoDB Community Version
    • Ensure the download is unblocked.
  2. Install MongoDB
    1. During installation leave all defaults
    2. Make sure that MongoDB Compass is also selected
    3. The setup wizard can take 10 minutes or more to complete
    4. ‘Finish” the setup wizard and the MongoDB Compass will automatically open. Leave the MongoDB Compass open as it will be used in later steps below

MongoDB Shell Installation

The MongoDB Shell will be used to create the root user.

  1. Download Mongo DBShell
    • Ensure the download is unblocked.
  2. Extract the files in a new folder (Eg C:\Program Files\Mongo DB Shell)

MongoDB Root User

  1. Run MongoDB Shell as an Administrator:
    1. Within the MongoDB folder, navigate to the bin folder.
    2. From 'bin' folder, right-click on 'mongosh.exe' and select 'run as Administrator'
  2. Enter 'mongodb://localhost' as the database name (if prompted)
  3. Type 'use admin' to switch to the admin database
    • The prompt should show as admin>
  4. Create a root user using the following command:

    REPLACE user (pwd) with the user name of your choice, and pwd (mongo) with a secure password.
    • db.createUser({
    user: "root",
    pwd: "mongo",
    roles: [{
        role: "root", // Assign the root role
        db: "admin" // Assign to the admin database
    }]
})
  5. Exit the shell by typing 'exit'.

MongoDB Connection

  1. Open MongoDB Compass
  2. Click on '+ Add new connection'
  3. For the connection name, enter mongodb://root:mongo@localhost:27017/?tls=false
    1. Replace user (root) and password (mongo) with the user name and password you created above
  4. Select 'Save & Connect'
  5. The database can now be connected to as localhost:27017

 

Private and Public Asymmetric JWT keys

There are a few places in this document that require adding public and/or private asymmetric keys for JWT. Please read below.

  • Keys can be requested from Riva
  • Insight and Sync require both private and public keys
  • TSS only requires the public key

 

Track State Service Package

  1. Download the Track State Service Package
    • Look for the most recent package (package name starts with TrackStateService.)
    • Ensure the download is unblocked.
  2. Extract the contents of the package.
  3. Follow the steps below as per your preferred Deployment Model

 

A: Separate Track State Service for each Insight environment

  1. Create a new folder under your existing Insight application called TrackStateService

    • default location: {drive}\Riva\Riva Insight\{AppName}\runtime\

  2. Copy the contents of the extracted package into the TrackStateService folder

 

B: Shared Track State Service for all Insight environments

  1. Create a new folder alongside your existing Insight application called TrackStateService
    • default location: {drive}\Riva\Riva Insight\

  2. Move the contents of the extracted package into the TrackStateService folder

     

Setup Track State Service under IIS 

Application Pools

  1. In IIS, under the current server, right-click on Application Pools and select Add Application Pool
  2. Create an Application Pool
    1. For Name, set the App Name and append -TrackStateService to the end.
    2. Change .NET CLR version to No Managed Code

    3. Click on OK when done.

 

Track State Service Subapp:

  1. In IIS, right-click on your Insight application and select Add Application
  2. Create the TrackStateService sub-application:
    1. For Alias, enter TrackStateService
    2. For Application Pool, select the application pool you created in the previous section.
    3. For Physical Path, select the location you placed the TrackStateService under in a previous section.

  3. Make note of the virtual path as it will be needed for the next section.
    1. In IIS, select the newly created TrackStateService application.
    2. In the Actions pane on the far right, select Advanced Settings.
    3. Make note of the Virtual Path

 

Configure Track State Service

 

Track State Service Base Url

  1. NOTE: The TrackStateURL is the FQDN or Server name of the Riva Insight Server, plus the tss virtual path.
    I.E.  https://{fqdn}/{tssVirtualPath}  ||  https://my.riva.com/insight/trackstateservice
  2. Make note of the TrackStateURL for future steps.

 

Track State Service App

NOTE: If using the Shared Track State, configure this to point to the primary Insight application that will be used by Riva Sync.

  1. In the TrackStateService folder, look for a file called appsettings.json.
  2. Configure Virtual Subpath
    1. Add a new entry for VirtualSubPath, replacing the value with the virtual path from the previous section.
      • "VirtualSubPath": "/insight/trackstateservice" 
  3. Config MongoDB connection
    1. Search for a section called MongoDb and look for ConnectionString
      • "MongoDb": {
    "Client": {
        "ConnectionString": "mongodb://root:mongo@localhost:27017/?tls=false",
        "DatabaseName": {
            "TrackStateService": "TrackStateServiceDb"
        },
        "CollectionName": {
            "TrackStateService": "TrackStateServiceCollection"
        }
    }
},
    2. Replace the user name (root) and password (mongo) with the user name had password you created previously
  4. Configure Logging
    1. Search for a section called Serilog and look for the path
      • "Serilog": {
    "Using": [
      "Serilog.Sinks.File"
    ],
    "MinimumLevel": "Information",
    "Enrich": [ "WithCorrelationId" ],
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "C:\\Riva\\Riva Insight\\Insight\runtime\\Logs\\log.txt",
          "outputTemplate": "{Timestamp:HH:mm:ss} {Level:u3} [{CorrelationId}] {Message:lj}{NewLine}{Exception}",
          "rollingInterval": "Day",
          "fileSizeLimitBytes": "10485760"
        }
      }
    ],
    "Properties": {
         "Application": "Riva Track State Service"
    }
  },
    2. You may leave the logs in the default location, or update to keep the logs with the other Riva Insight logs.
      1. For each folder in the path, add double-slashes.  
        For example: "path": "C:\\Riva\\Riva Insight\\Insight\runtime\\Logs\\tss.log"
  5. Configure JWT Key
    1. Add the following section (can be added after the “Serilog” section).
    2. Ensure the comma is added before the new section
      • ,
"Jwt": {
    "Asymmetric": {
        "PublicKey": "***"
    }
}
    3. Update the value of the PublicKey with your Riva provided JWT Public Key

 

Riva Insight App

  1. Open the webConnectionStrings.xml file
  2. Add the following connectionStrings to the config:
    • <add name="Vigo.TrackStateService" connectionString="Uri={TssUrl}"/>
<add name="Vigo.JWT" connectionString="PrivateKey={PrivateKey};PublicKey={PublicKey}"/>
  3. For the Vigo.TrackStateService connection string, replace {TssUrl} with your TrackStateUrl
  4. For the Vigo.JWT connection string, replace {PrivateKey} and {PublicKey} with the provided Private and Public keys.

 

Riva Sync App

NOTE: The TrackStateURL is the FQDN or Server name of the Riva Insight Server, plus the tss virtual path.
I.E.  https://{fqdn}/{tssVirtualPath}  ||  https://my.riva.com/insight/trackstateservice

  1. Open the Riva Sync configuration file
    1. This file can be found in the RivaSync/Application/Runtime folder
    2. Depending on your version of Sync, you will have to edit the config file for either the 64-bit or 32-bit version   i.e. Omni.Riva.CrmAgentEx.exe.config  or Omni.Riva.CrmAgentEx64.exe.config
  2. Add the following connectionString to the config:
    • <add 
  name="Insight.TrackStateService" 
  connectionString="Uri={TssUrl};PrivateKey={PrivateKey};PublicKey={PublicKey}" 
  />
  3. Update the connection string with the following values:
    1. Replace {TssUrl} with your TrackStateUrl
    2. Replace {PrivateKey} and {PublicKey} with the provided Private and Public keys.

 

Confirm (Health Endpoints)

Confirm that health check endpoints are accessible
  • You can confirm that the application is working by navigating to 
    • {TrackStateUrl}/api/trackstateservice/trackstate/health
    • I.E.  https://my.riva.com/Insight/trackstateservice/api/trackstateservice/trackstate/health
  • You can then also confirm that the database is accessible by navigating to
    • {TrackStateUrl}/api/trackstateservice/trackstate/health/database
    • I.E. https://my.riva.com/Insight/trackstateservice/api/trackstateservice/trackstate/health/database

 

Enable Enhanced Track in CRM (Track State Service)

For Enhanced Track in CRM, the Track State Service must be enabled by both Insight and Sync.


Riva Insight

  1. In the AppSettings.xml file or OnPremise.xml file, add the following key:
    • <add key="Feature.Track.TrackStateService.IsEnabled" value="true" />
  2. Restart Riva Insight Server after making the change.
  3. Reload Settings or Flush Redis.

Riva Sync

  1. In the Riva Sync Policy Advanced Options, 
    1. Ensure the DefaultUrl is present and points to a valid insight Url. I.E> https://my.riva.com/insight/
      • Sync.Crm.SyncConfiguration.Insight.DefaultUrl = {InsightEndpoint)
    2. Enable the Track State Service
      • Sync.Crm.TrackStateService.Enabled = true

  2. Restart Riva Sync Service after making the change.

     

Verification

  1. After making the changes in Riva Sync 
    1. Ensure the mailbox(es) goes though at least one sync cycle
    2. Verify logs to confirm no Track State Service errors
  2. Close and re-open Outlook (to force download of Sync Configuration)
  3. Log out and back into Riva Insight (to ensure latest are picked up)
  4. Go to the Insight About page to verify TSS has been enabled: