Global Settings - stored in a Configuration File

Settings which are relevant for each individual environment (e.g. Production vs Test environment) are stored in a configuration file.

Name and Location

• File Name: config.properties
• Location: typically, the file will be located
  • on the same drive as the Tomcat Server for the Web Application
  • in the directory: <Drive:>\SAI360\config\

Database Settings

All database related settings are prefixed with dbConfig. For example:

# DB Server configuration
dbConfig.id=MS-SQL
dbConfig.serverName=your_server
dbConfig.portNumber=1433
dbConfig.databaseName=database_name
dbConfig.userName=bms
dbConfig.password=GYK7G5FDS4F43DWSAT54
dbConfig.connectionParameters=ssl=require;param2=value2

General Settings

All general settings are prefixed with mainConfig.

• Content: this file is used for various purposes. The content which is relevant in this context is listed below '# Global Settings (install based)'.
  • EmailServerAddress: enter the UNC, or the IP Address of the email server which is used in this installation
  • EmailDefaultFromAddress: used as sender, for example for the emails sent when the system cannot reach the Virus Scanner (see below).
  • WebRoot: address of the Web Application for the current installation
  • DebugSetting: depending on the selected value, the system will create an output of ignored exceptions into the file EpsilonStdErr.log file. This will help when it is necessary to debug conditions. The possible values are:
    • none: ignored exceptions will not be logged (this is the default setting)
    • debug: will output the error message only
    • openid: to provide a detailed logging of all the steps of the OpenId authentication.
    • restcallouts: provides detailed loggings for Rest Callouts
    • trace: will create output of the error message, stack trace and thread state
      (Warning: this setting can create a very large volume of entries in the log file)
  • EnableRestCallouts: Rest Callouts will only fire if this flag is set to TRUE. If the setting is absent, or set to FALSE, Rest Callouts will not be triggered.
  • SustainabilityOutstandingDataLimit: by default, the limit for Outstanding Sustainability Data is 1,000 records. It can be altered with this variable. This setting will only apply to the Outstanding Sustainability Data Entry Portal.

BI-Specific Settings

These setting can be generated with the BI Setup tool and then pasted into this config.properties file:

# Pentaho settings (sample values)
mainConfig.PentahoNamePrefix=e360
mainConfig.PentahoReportingFeatureFlag=true
mainConfig.PentahoServerAddress=http://SERVER_NAME:8081/pentaho/
mainConfig.PentahoETLDirectoryPath=//SERVER_NAME/ETL_Output/
mainConfig.PentahoDataIntegrationUser=admin
mainConfig.PentahoDataIntegrationPassword=password
#Maximum time application waits for login into BI Server before rendering Home Screen (in milliseconds, e.g. 15000ms = 15 seconds)
mainConfig.PentahoLoginMaxWait=15000
# If you are using an MS-SQL database with Pentaho reporting and your views have been created with the schema other than the default of dbo
# Then please specify the non-default schema name here
mainConfig.PentahoDataWarehouseSchema=

By default, the ETL initiates up to 10 parallel processes to improve performance. However, in some instances it may be necessary to reduce the number of parallel running processes, or even to run them in series.

There are no generic recommendations for specific settings - these need to be decided on a case-by-case basis after some in depth analysis.

The available variables (you can apply all or only some of them) are:

mainConfig.PentahoETLParallel_load_staging_area=<x>
mainConfig.PentahoETLParallel_load_history_area=<x>
mainConfig.PentahoETLParallel_load_hubs=<x>
mainConfig.PentahoETLParallel_load_satellites=<x>
mainConfig.PentahoETLParallel_load_links=<x>
mainConfig.PentahoETLParallel_load_link_satellites=<x>
mainConfig.PentahoETLParallel_load_hierarchy_dimensions=<x>
mainConfig.PentahoETLParallel_load_facts=<x>
mainConfig.PentahoETLParallel_component_verification=<x>
mainConfig.PentahoETLParallel_system_table_verification=<x>

<x> can be a value between 1 (Serial) to 10.

System Notifications

The following settings are required for those clients who want to utilize System Notifications on Roam devices.

You need to add the following settings to the config.properties file:

mainConfig.SystemNotificationsHubUrl=<your details>
mainConfig.SystemNotificationsHubName=<your details>

The details for both these settings can only be provided by Customer Support once the Web Application has been installed, as they are specific to each environment.

To use System Notifications just for the web application, these settings can remain empty.

Multi-server Environments

If multiple Tomcat servers are used, e.g. for load balancing, some events should only be run on ONE of these servers.

To suppress System Events on a particular server, add the following setting:

• For System Events:
  mainConfig.SuppressSystemEvents=true
• For Scheduled Analytics Rules:
  mainConfig.SuppressScheduledAnalyticsRules=true

Scheduled Analytics Rules in Multi-server Environments

If multiple Tomcat servers are used, e.g. for load balancing, any System Events should only be run on ONE of these servers.

To suppress System Events on a particular server, add the following setting:

mainConfig.SuppressSystemEvents=true

Certificate Pinning for Roam Devices

If Certificate Pinning is enabled, the Roam app will only be able to connect if the certificate key provided by the URL matches these setting.
Also, if a Roam device remains inactive for longer than the defined max-age, the device will be logged out.

By default, the setting is set to FALSE.

roam.certificatepinning.enabled=true
roam.certificatepinning.keys=<Comma separated list of the keys>
#The following time unit is in seconds
roam.certificatepinning.max-age=3000000

Please contact Customer Support for further details.

Controlling Frequency of Delta Downloads for Roam Devices

This optional setting allows clients to change the frequency of the Delta Downloads (i.e. downloading only modified records) from the standard value of 24 hours.

#The following value is in hours
roam.deltaDownload.frequency=12

• Valid Range: numbers >=1 (integers only)
• If not defined, or an invalid number is used, then the system will apply the standard value of 24.

Logging Downloads from Roam devices

To log either of the following:

• Roam users up-/download data
• The Roam cache is deleted

... add the following setting:

mainConfig.DebugSetting=roamDownloads

Virus Scanner

If your organization intends to use a Virus Scanner to check documents which are uploaded to the system, please check here for details.

Part of the setup will require additional entries in the config.properties file.

CSRF Token Cache Size

Some clients may find the following entry, if they have experienced issues caused by too small a pool for CSRF tokens.

Config.CsrfTokenCacheSize=50

Please do NOT modify this setting without prior consultation with Customer Support.

Content-Security-Policy (CSP)

By default, the system appliesthe following CSP header:
child-src *; connect-src 'self'; form-action 'self'; img-src * data:

Here a brief explanation of these directives:

• child-src:
  defines valid sources for web workers, such as <iframe>
• connect-src:
  restricts the URLs which can be loaded using script interfaces
• form-action:
  restricts the URLs which can be used as a target of a form submission from a given context
• img-src:
  specifies valid sources of images and favicons

However, clients can override these settings with the following parameter:

mainConfig.ContentSecurityPolicyHeader=child-src *; connect-src 'self'; form-action 'self'; img-src https://example.com

In this example, the application would only load images from the specified site.

More information about CSP can be found under this link:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy

Other Feature Flags

mainConfig.DatabaseStatementCancellationSeconds=300

This setting will identify any SQL Queries from List Views or type-ahead component lookups that have been running for longer than 300 seconds (5 minutes), and cancel the thread. This is an optional safeguard from long-running SQL Queries causing problems for other users. The user waiting for a cancelled SQL thread will see a popup error.

mainConfig.ContentSecurityPolicyHeaderDisabled=true

Some customers use an IIS redirector that adds it’s own CSP header to requests. This flag is a mechanism to stop our Web Application from including one, to avoid conflicts

Activation of Modified Settings

To activate any modification of these global settings, the following steps will need to be performed:

• For 'EmailServerAddress' and 'WebRoot':
  • Tomcat restart