Skip to main content

Indicium configuration

Configuration template for Indicium​

Indicium

Remove the parts you do not need before using this template.

You can validate the correctness of your json configuration through this website: https://jsonlint.com/.

{
    "Logging": {
        "pathFormat": "YourOwnName-{Date}.txt",
        "IncludeScopes": false,
        "ErrorLog": {
            "LogLevel": {
                "Default": "Information",
                "System": "Information",
                "Microsoft": "Debug",
                "Indicium": "Warning"
            }
        }
    },
    "MetaSourceConnection": {
        "Server": "[server]",
        "Database": "[iam_database]",
        "PoolUserName": "[username]",
        "PoolPassword": "[password]"
    },
    "HideMetaDataDocument": true,
    "LoginOptions": {
        "AlwaysDeferLogin": false
    },    
    "SMS": {
        "Username": "[Account SID]",
        "Password": "[Authorization Token]",
        "FromPhoneNumber": "[Provider Phone Number]",
        "DefaultTwoFactorTokenTemplate": "Your validation code is {twoFactorToken}.",
        "TwoFactorTokenTemplates": {
            "NL": "Uw validatiecode is {twoFactorToken}",
            "ENG": "Your validation code is {twoFactorToken}."
        }
    },
    "Agent": {
        "Enabled": true
    },
    "Licensing": {
        "ScheduleUpdate": true
    },
    "AllowedOrigins": [
        "https://www.mydomain.com",
        "https://www.otherdomain.com"
    ],
    "ReverseProxy": {
        "Enabled": true,
        "TracingEnabled": true,
        "AllowedHeaders": [
            "XForwardedHost",
            "XForwardedProto",
            "XForwardedFor",
            "All"
        ],
        "CustomHeaders": {
            "XForwardedHost": "CUSTOM-FORWARDED-HOST",
            "XForwardedProto": "CUSTOM-FORWARDED-PROTO",
            "XForwardedFor": "CUSTOM-FORWARDED-FOR"
        },
        "AllowedHosts": [
            "www.example.com",
            "*.example.com"
        ],
        "KnownProxies": [
            "10.60.0.185"
        ],
        "KnownNetworks": [
            "10.60.0.0/16"
        ],
        "ExternalPathBase": "/"
    },
    "Applications": {
        "Preload": [
          "itst",
          "23",
          "does-not-exist"
        ],
        "RemoveUnusedModelAfterHours": 72
    },
    "FileCache": {
      "ClearLocalCacheOnStartup": true
    }
}

Configuration template for Indicium Basic (EoL)​

Indicium Basic End-of-life

In accordance with our Lifecycle policy, Indicium Basic is no longer supported. The Thinkwise Platform version 2024.2 is the last version to support Indicium Basic. Indicium for 3-tier environments is Indicium Basic's successor. It matches Indicium's 2-tier functionality and more.

Indicium Basic

Remove the parts you do not need before using this template.

You can validate the correctness of your json configuration through this website: https://jsonlint.com.

{
   "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Information",
      "System": "Information",
      "Microsoft": "Warning",
      "Indicium": "Debug"
    }
  },
    "MetaSourceConnection": {
        "Server": "[server]",
        "Database": "[iam_database]",
        "PoolUserName": "[username]",
        "PoolPassword": "[password]"
    },    
    "Email": {
        "SmtpServer": "[SMTP server address]",
        "SmtpPort": 587,
        "UseSSL": true,
        "SmtpUsername": "[SMTP account username]",
        "SmtpPassword": "[SMTP account password]",
        "PasswordResetTemplate": {
                "FromEmail": "[Sender email address]",
                "FromDisplay": "[Sender email display name]",
                "Title": "Uw wachtwoordherstelcode",
                "Body": "Uw wachtwoordherstelcode is: <b>{resetToken}</b>"
        },
        "TwoFactorTokenTemplate": {
                "FromEmail": "[Sender email address]",
                "FromDisplay": "[Sender email display name]",
                "Title": "Uw inlogcode",
                "Body": "Uw validatiecode om in te loggen is: <b>{twoFactorToken}</b>"
        }
    },
    "SMS": {
        "Username": "[Account SID]",
        "Password": "[Authorization Token]",
        "FromPhoneNumber": "[Provider Phone Number]",
        "TwoFactorTokenTemplate": "Uw validatiecode is {twoFactorToken}"
    },
    "AllowedOrigins": [
        "https://www.mydomain.com",
        "https://www.otherdomain.com"
    ],
}

Hide $metadata and OpenAPI specification​

Indicium

You can hide the /$metadata and /openapi endpoints to limit the amount of information exposed by Indicium. If these endpoints are not hidden, all available entities for your application and all available operations for every entity can be retrieved, including the (optional) parameters.

Add the following property to the appsettings.json file:

{
  "HideMetaDataDocument": true
}

Azure AD authentication (Indicium Basic)​

Indicium Basic End-of-life

In accordance with our Lifecycle policy, Indicium Basic is no longer supported. The Thinkwise Platform version 2024.2 is the last version to support Indicium Basic. Indicium for 3-tier environments is Indicium Basic's successor. It matches Indicium's 2-tier functionality and more.

Indicium Basic

Since Indicium Basic doesn't have a login page, OpenID is not available. However, there is a solution for Azure AD authentication via an Azure SQL Database.

Azure SQL Database allows you to "create contained users mapped to Azure AD identities". In turn, Indicium Basic allows users to sign in with these contained users.

In IAM, the Authentication type for the corresponding user has to be 'External' (menu Authorization > Users > tab Form > tab User). This is the same as how a user is configured for Azure AD authentication via OpenID.

Email configuration on Azure​

Sending emails from Azure requires some additional configuration. Azure blocks outbound email messages sent from any service in Azure that does not use an authenticated SMTP relay service, to protect Azure data center IP addresses from reputation abuse.

The most common SMTP relay service that is integrated with Microsoft Azure is SendGrid. The SendGrid SMTP API allows you to send emails using the Thinkwise SMTP connector, but you could also use their Web API with the Thinkwise HTTP connector.

Instructions on how to setup SendGrid in Azure and send emails using SMTP can be found here and here. Consult the SendGrid documentation for more information.

Amazon SNS support​

Indicium

Amazon Simple Notification Service (Amazon SNS) can be used to call Indicium's standard APIs (for example, tasks, tables, etc.).

In the Amazon SNS requests, the application/json Content-Type is used. This makes these requests compatible with the Indicium APIs.

Amazon SNS authentication​

Indicium

Indicium supports authentication by Amazon SNS. This service can then send notifications to Indicium.

To use Amazon SNS for sending notifications, subscribe to Amazon SNS topics on one or more HTTPS endpoints. To confirm your subscription, navigate to the SubscribeURL, either with the HTTP Connector or manually from the browser.

The endpoint can, for example, be an Indicium Process Flow API endpoint. This way, you can create custom logic to handle the message. Consult the Amazon documentation for full details on how to subscribe.

Two-factor authentication (2FA)​

Indicium supports different types of two-factor authentication:

  • TOTP
  • Email
  • SMS

The type of two-factor authentication you need can be configured for each user in the Intelligent Application Manager. See Two-factor authentication for more information.

Title for authentication pages​

Indicium

The title for Indiciums authentication pages is set in IAM: menu Settings > Global settings > field Title.

If no title property is entered in IAM, the title 'Thinkwise Identity Provider' will be used.

Login screen​

Login options​

Most of the login options can be configured in IAM. For more information, see Login page configuration.

Defer login​

Indicium Universal GUI

With the setting AlwaysDeferLogin, you can control whether the Universal GUI should always defer the login process to Indicium or not.

  • If set to true:

    • Indicium will always handle the login process.
    • Exception: if you have set loginOptionsDisabled and loginOptionsHidden set to false in the Universal GUI, then Indicium will not redirect users from the Universal GUI login screen to the new login screen on Indicium.

  • If set to false:

    • Indicium will not redirect users from the Universal GUI login screen to the new login screen on Indicium.

For more information, see Settings for the Universal GUI login screen.

note

In the future, the default value will be changed to true.

To change the default value, add the following to the appsettings.json file:

{
  "LoginOptions": {
    "AlwaysDeferLogin": true
  }
}

Push notification configuration​

Indicium Universal GUI

You must configure Indicium to use push notifications for your applications. The topics below explain how to do this for different hosting environments.

Firewall configuration​

Indicium must be able to reach out to push notification services. Ensure your firewall allows traffic from Indicium to:

  • Google - fcm.googleapis.com
  • Mozilla - updates.push.services.mozilla.com and push.services.mozilla.com
  • Apple - web.push.apple.com
  • Microsoft - https://*.notify.windows.com

On-premise​

To configure push notification in Indicium for on-premise, add the following to the appsettings.json. This setting describes where to store the VAPID keys required for push notification. Ensure the Indicium pool user has write access to the specified StorageLocation folder.

"Agent": {
  "PushNotifications": {
    "VapidKey": {
      "LocalFileSystem": {
        "StorageLocation": "C:\\VapidKeys\\"
      }
    }
  }
}
note
  • In case Indicium is scaled, make sure all instances share the same push notification (VAPID) keys or else push notification will not work correctly.
  • You can also store VAPID keys in Azure Key Vault with an on-premise deployment. See the Azure section below.

Azure​

When using Indicium on Azure, the push notification encryption keys must be stored in a Key Vault:

  1. In the Indicium Web App, select the menu Identity.
  2. Make sure that the setting System Assigned is enabled.
  3. In the Azure Portal, create a Key Vault.
  4. In the Key Vault, go to Access Control (IAM) and click on Add role assignment to allow the Indicium instance access.
  5. On the tab Role, select the role Key Vault Secrets Officer.
  6. On the tab Members, select Managed identity, and select the Indicium Web App.
  7. Save the role assignment.

To use the newly created Key Vault, you must set the KeyVaultSecretUrl setting in the Indicium Web App.

In the appsettings.json configuration file, this KeyVaultSecretUrl setting can be configured directly:

"Agent": {
  "PushNotifications": {
    "VapidKey": {
        "AzureKeyVault": {
          "KeyVaultSecretUrl": "https://<name-of-the-key-vault>.vault.azure.net/secrets/<secret-name>"
          // When using an application registration, the following is mandatory. If using a managed identity it can be left out.
          "TenantId": "<Directory (tenant) ID>",
          "ClientId": "<Application (client) ID>",
          "ClientSecret": "<Secret value>",
        }
    }
  }
}

Alternatively, you can store this setting in the App Service:

  1. In the App Service, open the menu and select Settings > Configuration.

  2. Add the following Application settings:

    • Name - Agent__PushNotifications__VapidKey__AzureKeyVault__KeyVaultSecretUrl
    • Value - https://<name-of-the-key-vault>.vault.azure.net/secrets/<secret-name>

When using an application registration, the information can be found in the overview screen of the App Registration. Secrets can be created in the Azure Portal, in App registration > Certificates & secrets for your app. Make note of the secret expiration date, because push notifications will not work anymore after that expiration date. Configure a new secret in time to avoid issues, or, preferably, use a managed identity.

note

Indicium needs to be able to create the secret. Make sure the managed identity of the Azure application or the application registration has the role assignment Key Vault Secrets Officer for the Key Vault you set up.

AWS​

When using Indicium on AWS, the push notification encryption keys must be saved in the AWS Secrets Manager.

To give the Elastic BeanStalk EC2 instance access to the Secrets Manager:

  1. In your Elastic Beanstalk EC2 instance, select the tab Security.
  2. Click Identity and Access Management (IAM).
  3. Click Add permissions.
  4. Click Create inline policy.
  5. In the tab JSON, paste the JSON code fragment below.
  6. Save the new policy. Indicium can now access the AWS Secrets Manager.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:CreateSecret"
            ],
            "Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:<secret-prefix>-*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "secretsmanager:ListSecrets",
            "Resource": "*"
        }
    ]
}

In the above JSON code fragment:

  • Replace region with your region, for example, "eu-west-1".
  • Replace account-id with your account number.
  • Replace secret-prefix with the prefix you want your encryption keys in the Secrets Manager to have.

For example, if your prefix is "indicium/push-notification-test", you should give access to "indicium/push-notification-test-*" with the wildcard character.

In the appsettings.json configuration file, add the following code:

"Agent": {
  "PushNotifications": {
    "VapidKey": {
        "AwsSecretManager": {
          "SecretPrefix": "indicium/push-notification-test"
        }
    }
  }
}

Enable Cross-Origin Resource Sharing (CORS)​

By default, a website only allows requests that come from the same origin (scheme, host/domain, and port). If you host a website yourself and you want to allow requests from another origin, you can use Cross-Origin Resource Sharing.

This concept also applies to the Indicium Application Tier. To enable cross-origin requests, add the allowed origin(s) to the appsettings.json file:

{
  "AllowedOrigins": [
    "https://www.mydomain.com",
    "https://www.otherdomain.com"
  ]
}
note

This is only available when Indicium runs in Development mode.

Global redirects for CORS requests in IAM​

If CORS is enabled, and if Indicium is running on a different domain than the Universal GUI, you need to allow the client to redirect back to the domain where the Universal GUI is located. To whitelist global return URLs in IAM, see Client redirect in the IAM manual.

Preload application models during startup​

Indicium

To reduce the response times for users who are the first to access applications after a cold start or restart, you can specify application models that Indicium must try to preload from IAM during startup.

Keep in mind that:

  • For applications containing system flows, this feature has little to no effect. The reason is that Indicium already implicitly loads applications containing system flows during startup, as it needs to know the model before it can execute the scheduled flows.
  • Due to the way that Indicium handles loading models from Software Factory sources, this feature only works for models synced to IAM.
  • If a new version of a preloaded model/application is synced to IAM, Indicium will not automatically preload the new version.

Example​

Preloading application models can be configured in the appsettings.json configuration file under the Applications:Preload configuration key. Specify either the ID or the alias of the applications that need to be preloaded. Indicium will try to load these models for the specified applications during startup.

{
  "Applications": {
    "Preload": [
      "itst",
      "23",
      "does-not-exist"
    ]
  }
}

This process is also logged to the default Indicium log:

Indicium log Example log file: preloading models and one fail

Periodic removal of idle application models from memory​

Indicium

Indicium can periodically remove idle application models from memory. An application model is considered idle when:

  • It has not received any API calls during the specified time.
  • There has been no active system flow during the specified time.
  • It has not been marked as a preloaded application model.

In the appsettings.json configuration file, the RemoveUnusedModelAfterHours configuration option specifies the period of time in hours after which the model is removed. Please note that "Applications" is the same configuration section as the "Applications" section mentioned in preloaded application model.

"Applications": {
  "RemoveUnusedModelAfterHours": 72
}

The default (and recommended) value of this setting is 72 hours. This may feel like a long time to keep idle application models in memory, but the goal is not to clear the memory as quickly and often as possible. After all, it is a cache that serves an important purpose. The performance-memory trade-off needs to be considered because once an application model is removed from memory and requested again through an API call, it needs to be loaded from the database, which will be a performance hit on that API call.

The main goal of this feature is to ensure that Indicium instances that are rarely restarted, for example, because they are in use 24/7, don't gradually use more and more memory for 'dead' application models that have not been used for weeks. We recommend to lower this value only if all of the points below are true:

  • Indicium is restarted rarely.
  • Many applications are used for a short time within a short time.
  • Indicium's memory usage is noticeably growing to several gigabytes within the 72-hours.

Log​

Change logfile name​

It is possible to edit the log file name and the path. This can be useful if you are running multiple instances of Indicium next to each other or if you do not like the current name.

To change a log file name, add the pathFormat to the Logging segment in Indicium's appsettings.json:

{ 
  "pathFormat": "YourOwnName-{Date}.txt" 
}
  • Replace the content of FileName with a name of your own choosing (YourOwnName).
  • If no {Date} is specified, Indicium will add it.
  • If file extension .txt is not specified, Indicium will add it.

Edit minimum log level​

It is possible to edit the minimal log level. The default log level is 'Error'. This can be useful if you need more information.

The log level of other logging namespaces can be overridden by adding a key and value to the Logging:ErrorLog:LogLevel section. Some keys cannot be modified and will always be set to level 'Information'.

{
  "Logging": {
    "ErrorLog": {
      "LogLevel": {
        // Log Information level messages to the error log.
        "Default": "Information",
        // Log Debug level messages if the namespace of the logger starts with 'Microsoft'.
        "Microsoft": "Debug"
      }
    }
  }
}

This process is also logged to the default Indicium log:

Indicium log *Example log file: preloading models and one fail

Disable background operations​

Indicium

It is possible to disable all background operations managed by Indicium and IAM. At the moment, the only example of such a background operation is the scheduling of system flows.

The default value for background operations is true. To disable the background operations: set 'Agent:Enabled' to 'false' in the appsettings.json:

{
  "Agent": {
    // Skip registering this Indicium instance as an agent on IAM.
    // Also disables adding all agent related services such as the scheduled system flow runner.
    "Enabled": false
  }
}

Disable scheduled license update checks​

Indicium

Indicium performs a license check on startup and obtains, if necessary, an updated license. This check recurs periodically to keep the license valid. See Automatic license renewal.

To make Indicium perform this check only on startup, set Licensing:ScheduleUpdate to false in the appsettings.json.

{
  "Licensing": {
    // Only check and update (if necessary) the current license once on startup
    // and skip scheduling further checks from being run in the background.
    "ScheduleUpdate": false
  }
}

File cache​

ClearLocalCacheOnStartup - Optional. If not set or true, the local cache is cleared on startup. Set it to false if multiple instances of Indicium share the same cache folder. For example, when running multiple app service instances. It prevents that one instance clears the cache while another one tries to access files in the cache.

  "FileCache": {
    "ClearLocalCacheOnStartup": true
  }
Was this article helpful?