Skip to main content

Indicium setup

Indicium is a .NET Core application, which means that it is capable of hosting itself with a built-in web server. However, for security and management reasons, we do not recommend exposing the built-in web server in production environments. Instead, we recommend hosting Indicium behind an IIS proxy, since IIS is rich in features and offers great management tools.

This guide explains how to integrate Indicium in an IIS proxy.

note

When you are using Automated Machine Learning in your environment, you need to install and configure an additional component. For more information, see the AutoML guide.

About Indicium​

Two types of the Thinkwise Indicium Application Tier are available:

  • Indicium Basic: for use with the Windows GUI. This basic version does not support, for example, system flows and OpenID.
  • Indicium: for use with the Universal GUI and via API's. This version uses the full range of Indicium functionality.

Quick reference guide Indicium setup​

Instead of using the Deployment Center, this document describes how to deploy Indicium manually (on premise).

To deploy Indicium in the cloud:

Follow these steps to manually deploy Indicium on premise (using IIS):
1. Check - Before you start, check if your systems meet the prerequisites.
2. Download - Download Indicium and save the files.
3. Application pool - Create an application pool in IIS.
4. Web application - Create the web application.
If necessary: Troubleshooting or Monitoring Indicium live.

For a video explanation on how to manually deploy Indicium (including troubleshooting), see: Masterclass Indicium. It is an extensive video that also covers:

  • the deployment of Universal GUI (1:13:00)
  • the deployment of Windows GUI (1:19:00)
  • API's in Indicium (1:28:00).

Prerequisites​

Make sure to meet the following prerequisites before you install Indicium on IIS:

RequiredMore information
IISCheck if IIS has been installed. See: Configuring IIS.
.NET 8Indicium is built using ASP.NET Core. The ASP.NET Core 8 runtime must be installed on the web server.
If you also need to run Indicium on IIS, you must install the ASP.NET Core Runtime 8 Hosting Bundle.
This module enables IIS to take control of starting and stopping Indicium, amongst other things. To check if the module has already been installed, open Modules on a website in the IIS Manager.
AspNetCoreModuleV2
URL Rewrite ModuleMicrosoft's URL Rewrite Module for IIS is not available in IIS by default, but necessary to facilitate the integration of Indicium. You can check whether it is already available in the IIS Manager, much like the previous module. If it has not been installed yet, use this link to install it: https://www.iis.net/downloads/microsoft/url-rewrite.
RewriteModule
WebSocket ProtocolIndicium makes use of SignalR to provide clients the option to subscribe for asynchronous updates on features such as:

To enable IIS to run SignalR the WebSocket Protocol feature must be installed on the server.
WebSocketProtocol
OptionalMore information
.NET FrameworkSome features of Indicium currently cannot be ported to run on .NET 8. Therefore, they are run as plugins in separate .NET Framework processes. The minimum .NET Framework version to run the plugin processes is 4.7.2. To check which version has been installed: https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed. If the web server has no .NET Framework or a lower version, then use the following link to install the latest version: https://www.microsoft.com/net/download/thank-you/net472.

This affects the following features:
  • Crystal Reports
  • SSRS Reporting
  • DevExpress Reporting
DB2 Core driverSee: IBM i DB2 drivers for the Universal GUI with Indicium

Note: Using DB2 with any of the reporting types mentioned in the .NET Framework section above, still require the old iSeries DB2 driver.

Download and save Indicium​

When all prerequisites mentioned above are met:

  1. Download the Indicium software in TCP - Thinkwise products and save it.

  2. If necessary, remove the security block in the zip file's Properties. (This won't be necessary if you use 7-ZIP.)

  3. Extract the files.

  4. In IIS, right-click on the site where you wish to install Indicium and select Explore. Typically, this location will be something like C:\inetpub\wwwroot\indicium.

  5. Add a folder and give it a name, eg 'indicium_universal'.

  6. Copy all the extracted files to this folder.

Create an application pool​

warning

Always create a separate pool for each Indicium. Several Indiciums in one pool will not work. Moreover, it ensures that each Indicium can operate separately from the others and can be independently stopped and restarted.

To create a separate application pool in IIS for each Indicium:

  1. Right-click Application Pools and choose Add Application Pool.

    • Name: name the application pool the same as the folder you created (eg, as in the example above: 'indicium_universal').

    • .NET CLR version: Indicium is capable of hosting itself and IIS is merely used as a proxy to expose Indicium to the network and/or the internet. As such, all the heavy lifting is performed by Indicium's own web server and the Application Pool in IIS does not even need to initialize a .NET runtime. Because of this, select No Managed Code when creating an Application Pool for Indicium, as it will positively affect the start up time.

Add Application Pool

Configuring pool users​

warning

When configuring the Database Pool User in the appsettings.json file, you can only use database accounts and no domain accounts. Domain accounts in the appsettings.json file are not supported because they can cause severe performance degradation and are considered a potentially dangerous security breach.

After creating the application pool in IIS, you can configure pool users:

  1. Open the Advanced Settings (under the Actions menu) of the application pool.

  2. Now configure an Identity (click the ...). This is the Application Pool Identity. Use, for example, a dedicated service account. The identity requires the following permissions:

    • Full access (read, write, delete, list, execute) to the Indicium folder so, for example, logs and caches can be written.
    • Read/write/modify control for all file system storage locations so files can be written, read, and deleted.

What these disk locations are depends on where the application stores its images and other files, and to which locations the application can upload files.

Advanced Settings

Indicium handles authentication and authorization internally and will perform all database traffic with a single user, the Database Pool User. By default, the Application Pool Identity (as set in IIS) is used as Database Pool User. To deviate from this, you can choose to override it by adding the PoolUserName and PoolPassword properties in the appsettings.json file.

{
  "MetaSourceConnection": {
    "PoolUserName": "[username]",
    "PoolPassword": "[password]"
  }
}
note

See also:

Make sure the Database Pool User only has the minimal required permissions:

  • It should only facilitate the communication with the database.
  • It needs full access to all the databases present in IAM, including the IAM database itself. Therefore, it should have the role 'db_owner' for the IAM database and all end application databases.
  • There is no need to add the Database Pool User as a user to IAM, since it does not need to log in to the end application.

None of the end users accessing the applications requires any physical permissions on any database, as this is regulated by the pool user.

Store pool user credentials encrypted​

Indicium Universal GUI main administrator application administrator

When using the Software Factory in Universal GUI, you can also store the pool user credentials in IAM or the Software Factory. These credentials will be safely encrypted and used instead of the credentials stored in Indicium's appsettings.json file.

To store the pool user credentials in IAM:

menu Authorization > Applications

  1. Execute the task Set pool user credentials set credentials.

  2. Enter the user name and password.

  3. Click Execute.

    pool user credentials Store pool user credentials in IAM

    In tab Form, the checkbox Custom pool user set will be selected automatically. This indicates that a pool user has been set for this application.

    You can reset the credentials and use the ones stored in Indicium's appsettings.json file instead with task Reset pool user credentials reset.

To store the pool user credentials in the Software Factory:

  • For a runtime configuration: menu Maintenance > Runtime configurations.
  • For an IAM configuration: menu Maintenance > IAM configurations.

Azure Active Directory as pool user​

It is possible to use Azure Active Directory users as the database pool user for Indicium.

note

This cannot be used to create a new database using the Creation screen in the Software Factory.

To use an Azure Active Directory user, add the following settings to the appsettings.json file:

{
  "MetaSourceConnection": {
    "UseAzureActiveDirectory": true,
    "PoolUserName": "[username]",
    "PoolPassword": "[password]"
  }
}

The PoolUserNameand PoolPassword are optional. If not set, Indicium will use the managed identity that is running the App Service in Azure as the pool user (similar to how it would use the Application Pool Identity for IIS). To enable this, add the App Service as a user to the database using the following statements:

CREATE USER {APP_SERVICE_NAME} FROM EXTERNAL PROVIDER;
ALTER ROLE db_owner ADD MEMBER {APP_SERVICE_NAME};

Idle time-out​

Check in IIS in the application pool's Advanced Settings that the Idle Time-out (minutes) is set to 0 (disabled) instead of 20. This ensures that scheduled process flows will continue running without user activity.

Start mode​

Check in IIS in the application pool's Advanced Settings that the StartMode is set to AlwaysRunning instead of OnDemand. This ensures that Indicium will be active even if no web requests have been made yet.

warning

If you change the StartMode setting to AlwaysRunning, you must enable the Application Initialization feature.

Create the web application​

Main administrator

  1. Open the appsettings.json file with a text editor to configure the connection to the IAM database.

    For more information about PoolUserName and PoolPassword and whether you should use it or not, see above.

    note

    Double quotes (") and backslashes (\) in the appsettings.json file, for instance in the server address, need to be escaped by an extra backslash. For example: server\instance should be server\\instance.

    {
      "Logging": {
        "IncludeScopes": false,
        "LogLevel": {
          "Default": "Information",
          "System": "Information",
          "Microsoft": "Warning",
          "Indicium": "Debug"
        }
      },

      "MetaSourceConnection": {
        "Server": "[server]",
        "Database": "[iam_database]",
        "PoolUserName": "[username]",
        "PoolPassword": "[password]"
      }
    }

  2. Create a new web application: right click on the folder (e.g., 'indicium_universal') and select Convert to application.

  3. Choose an Alias, the created Application Pool and the Physical path to Indicium.

    Add Application

  4. The web application will attempt to listen on port 80 by default. If this port is already in use, choose another one: right-click Default Web Site and select Edit bindings.

  5. In addition to the AlwaysRunning setting on the application pool, ensure Indicium is activated properly after the application pool has been (re)started. In the Advanced settings of the Indicium web application, enable the Preload option.

    Note that the Preload feature of IIS will not work correctly if the website only accepts traffic via https, as the preload request is fired on http. A resolution for this situation can be found here.

    Preload Application

  6. Start the web application to verify that Indicium is running and has been configured correctly. This is possible in two ways:

    • Open a browser and navigate to https://server/indicium/.
    • Or: select the application in IIS and choose Browse :80 (http) (depending on the set port).

    Check if Indicium is running

note

If you do not get a result like the image above, refer to Troubleshooting issues.

Troubleshooting startup errors​

If the root URL of Indicium (for example, https://server/indicium/) gives an error, it will most likely state "An error occurred while starting the application" and/or show error code 502.21. With version 2.0.6+ of the AspNetCoreModuleV2 for IIS, the error page should include the cause of the error. This is usually informative enough to point you in the right direction. If not, follow the steps below in their stated order.

note

When Indicium encounters a database connection failure during start-up, it retries every two minutes for up to 10 minutes. The cause of the connection failure can be a temporary issue with the database server or network that resolves itself.

1. Database connection and version mismatch​

Check Indicium's Logs folder for more information about what could be wrong:

  • Incorrect version of Indicium or IAM.
  • Incorrect database connection settings. Ensure that the information in the appsettings.json file is correct. Double-check the server address and the database. See: Create the web application.
  • Database Pool User lacks permission. Ensure that the Database Pool User has access to the configured IAM database and product databases. See: Configuring pool users.

2. Configuration and system requirements issues​

Check Indicium's Logs folder for more information about what could be wrong.

If it is empty, start Indicium.exe (from the root folder) as the Database Pool User (make sure that it is not overruled by the Application Pool User in the appsettings.json file). See if it runs successfully or displays an error. If so, take a screen shot because it disappears quickly.

  • Syntax error in appsettings.json. Ensure that the JSON in the appsettings.json file is valid. The most common mistakes are forgetting to escape backslashes either in the server address or the pool username, or forgetting a comma after a property which is not the last one.

    Invalid JSON

    If you want to be certain that the JSON is valid, you could use this website to validate it (clear any sensitive information first): https://jsonlint.com/.

  • Wrong version of the .NET Framework or .NET Core runtime installed. Double-check if your system meets the required versions as mentioned in Prerequisites.

  • Indicium's files are blocked by file security properties.

3. IIS hosting issues​

  • Wrong version of the .NET Core Windows Hosting bundle installed. Double-check that your system meets the required versions as mentioned in Prerequisites.

  • No IIS Rewrite module. Double-check if your system meets the required versions as mentioned in Prerequisites.

  • The Application Pool User has no access to Indicium's folder. See: Configuring pool users.

  • The Application Pool user has no access to the certificate store. The following error indicates insufficient access rights to the Windows certificate store for the application pool identity:

    System.Security.Cryptography.CryptographicException: The system cannot find the file specified.

    Right-click on your Application Pool, open the Advanced Settings and make sure that the correct Identity is set. Note that Load User Profile should be set to True.

  • Multiple applications on one Application Pool (Indicium). Make sure you use a separate Application Pool for each Indicium.

4. Log files​

If none of the above-mentioned solutions solves Indicium's startup problems, gather the log files and send them to your Thinkwise representative for further assistance.

See Indicium log files for more information.

Was this article helpful?