Skip to main content
Version: 3.0

Database Connections

Starting with v3.0, Cortex supports two ways to configure database connections to your source systems.

The primary method for managing database connections in Cortex v3.0 and later is through Data Sources - a configuration interface built into the Cortex web app. Data Sources let you define any number of connections to your source databases, including multiple connections to the same system type.

For example, you could connect to 15 separate Cherwell databases simultaneously, each defined as its own named Data Source, all without touching the server configuration.

This is the recommended approach for any deployment where you need more than one connection to a given system, or where you expect to add or change connections over time without rerunning the installer.

For instructions on configuring Data Sources inside the app, see: Data Sources

Installer / appsettings.json Connection Strings​

The Cortex Installer automates the setup of database connections by writing connection strings to the appsettings.json configuration file. This is the older method and may be streamlined or removed in a future release, but it remains fully supported.

info

Any connection string defined in appsettings.json will automatically generate a corresponding Data Source record in the Cortex web UI when the application starts. If you configure connections through the installer, you will see them reflected in the Data Sources interface.

For new installations on v3.0, the installer supports configuring one connection string per source system - up to one each for Cherwell, Neurons, ServiceNow, and Jira, in addition to the required Cortex connection. If you need multiple connections to the same system type, use the in-app Data Sources interface for those additional connections after installation.

Named Connection Strings​

The following named connection strings are recognized by Cortex when defined in appsettings.json:

  • Cortex - Required. Cortex's own internal data store.
  • Default or Cherwell - Connection to a Cherwell (CSM) database.
  • ServiceNow - Connection to a ServiceNow database.
  • Jira - Connection to a Jira Service Management database.
  • Neurons - Connection to an Ivanti Neurons for ITSM database.

Each of these is a single named entry. If you need multiple connections to the same system type, use the in-app Data Sources interface instead.

Cortex can connect to Microsoft SQL Server, PostgreSQL, or SQLite. SQL Server is recommended.

Constructing a Connection String​

Cortex accepts standard .NET connection strings - a series of semicolon-separated key-value pairs. A typical connection string looks like this:

server=server-hostname,1433;uid=username;password=the-password;database=Cherwell;MultipleActiveResultSets=true

Helpful references:

Required Settings​

  • server - The hostname or FQDN and port of your SQL Server instance, or the name of a named local instance.

  • Authentication - Choose one of the following:

    • SQL Authentication (recommended)
      • uid or user id - the SQL username
      • password - the SQL password
    • Windows Authentication (common in high-security environments, requires additional IIS configuration - see below)
      • Integrated Security=true

  • database or initial catalog - The name of the database.

  • MultipleActiveResultSets - Must be set to true.

Alternate Database Engines​

All connection strings are treated as SQL Server by default. Cortex also supports PostgreSQL and SQLite for both the Default/Cherwell and Cortex connections.

To use a different engine, add the engine option to the connection string:

engine=postgres;server=server-hostname,5432;uid=username;password=the-password;database=Cherwell

Valid values are postgres and sqlite.

note

MultipleActiveResultSets=true is SQL Server-specific and will cause PostgreSQL and SQLite connections to fail if included. Remove it when using those engines.

Functionality is limited when using SQLite for the Default/Cherwell connection. There is no supported migration path from SQL Server to SQLite (though there is one from SQL Server to PostgreSQL).

Windows Authentication for SQL Server​

warning

Windows Authentication for the SQL Server connection only affects how Cortex connects to the database. User authentication to Cortex itself must still be configured separately via SAML or OpenID Connect.

This option is only supported when running Cortex on Windows with IIS, connecting to Microsoft SQL Server. It is not supported with PostgreSQL or SQLite.

  1. In IIS Manager, configure the Application Pool that Cortex runs under to use a specific Windows user account. This account must have access to the SQL Server instance.
  2. Update your connection string to use Integrated Security instead of a username and password:
server=server-hostname,1433;Integrated Security=true;database=Cherwell;MultipleActiveResultSets=true

Optional Settings​

These settings may be required depending on your environment or security requirements.

  • Encrypt - Recommended to be true. Can be set to false if the database is on the same machine.
  • TrustServerCertificate - Set to true if your SQL Server uses a self-signed certificate or an untrusted chain. See Installation Troubleshooting for when this is needed.

Troubleshooting​

If you encounter connection errors, see:

Installation Troubleshooting