NOTE: some of the groups listed below are only accessible for the "BMS Admin" user.

Field

Valid Range

Notes

Primary Authentication Method

Select from:

• Basic Authentication
• OpenID Connect
• Dual Login (OIDC + Basic Authentication)
• Third Party
• Active Directory

Basic Authentication

Enable 2FA?

Available where the [Primary Authentication Method] is either "Basic Authentication" or "Dual Login".

When this feature is enabled, all basic auth (internally managed username and password) users will be emailed a code after logging in, and will need to enter the code before their login is completed.

The system will use the user’s Person’s email address if available, and the email address on the user account otherwise.

Dual Login

If some of your users are logging in using OIDC (e.g. your employees), while so other users need to log in using our basic authentication (e.g. contractors), select this option.

OIDC Button Label

The text entered here will be used in the login screen.

Basic Auth Button Label

The text entered here will be used in the login screen.

Third Party Authentication Enabled

Only set to yes if your organization is using Third Party Authentication Products which inject User Details into http headers.

Default User Identifier Enabled

• Yes: non Authenticated Users are identified via their Network Login
• No: non Authenticated Users are identified via their IP Address

Header Variable Name

max 255 characters

Field will become mandatory if Third Party Authentication is enabled.

The details for the variable Name are determined by this Third Party Tool.

Logout URL

This is address the user is taken to on clicking the Logout Button.

Active Directory

LDAP Server Name

Enter the full name of the LDAP Server.

• Only ONE LDAP Server can be added
• The domain name must be the Fully Qualified Domain Name. For example "myhost.example.com"

LDAP Server Port

Enter the port number for the LDAP or LDAPS Server.

SSL Enabled (i.e. LDAPS)?

Set only to Yes if your authentication is using SSL (LDAPS), otherwise set to No.

OpenID Connect (OIDC)

Open ID Connect (OIDC) is a standard, which is supported by several delegated authentication providers (e.g. AzureAD, Okta, etc).

Therefore, the information below is kept generic, as the details depend on the provider being used by a client.

A System Administrator will need to configure the provider with details of the SAI360 web and mobile applications. How this is done varies significantly between providers. Please contact your System Administrator for the details needed to complete the information below.

We support a variety of OpenID Connect providers (including Okta, ADFS 2016, Azure AD, Google) and we regularly test against Okta and Azure AD. However due to the flexibility of the settings available in SAI360, we expect many other OIDC providers will also be compatible. Each provider requires different configuration to setup, on both the provider-side, and on the SAI360-side. Setup guides are available for some of these identity providers, in separate documents.

NOTE:
to assist with trouble-shooting while defining OpenID, edit the file config.properties and provide the following setting:
mainConfig.DebugSetting=openid
This will provide a detailed logging of all the steps of the OpenId authentication in stderr file.

Authority URL

URL: the URL of the token issuer.

Custom Scopes - Web Application

Custom Scopes - Roam

A space separated list of scopes. These define any extra access privileges the SAI360 application is requesting.

Valid values are:

• email
• needs_consent
• offline_access
• openid

Resource (ADFS only)

Only required when using ADFS 2016, as configured in your system.

Obtain Username by

Select either of the following options, based on the setup of your authentication server:

• Validating and decoding JWT token
• Calling UserInfo endpoint

Depending on your selection, the subsequent fields which are displayed will vary.

Username Claim

The name of the claim in the access token which will contain the username.

Audience

An identifier of the recipient of the token, i.e. the SAI360 web application, as configured in the provider.

Accept Leeway

This is the amount of time in seconds past which an expired token will be accepted. Normally a leeway of only a couple of minutes should be set (ie: 120).

Non Standard Issuer

When validating tokens, the system will compare the "iss" supplied in the token against the well-known config value identified by the value entered here, rather than against the standard "issuer" value.

Roam Client ID and Web App Client ID

An identifier for each client, as configured in the provider.

You will need to supply separate IDs for

• Roam (separate for Android and iOS),
• and for the web application.

Roam Callback

The default value is usually suitable for all OIDC providers. Use the Google-specific value when using Google Authentication.

Non Standard Issuer

When validating tokens, the system will compare the "iss" supplied in the token against the well-known config value identified by the value entered here, rather than against the standard "issuer" value.

Client Secret

A 'secret' string which is used by the web server to authenticate to the OpenID provider.

Logout of OpenID Connect when logging out?

Determines what happens when a user is logging out of the SAI360 web application:

• When selected:
  - user will be logged out of the SAI360 web application, and out of OpenID Connect.
  - next time the user is logging into SAI360, the user will have to authenticate against the OpenID Connect provider.
• When not selected:
  - user will only be logged out of the SAI360 web application.
  - next time user is logging into SAI360, they will be logged in automatically, as the authentication against OpenID Connect is still valid.
  

Field

Valid Range

Notes

Accent Colour

Valid Hex Code

Either select a color from the cooler picker, or enter a Hex color code (e.g. #D2020E) which is to be used as the base color for the application.

This is the system accent color which will be used for highlighting buttons (such as Save or Cancel) underlining which tab a user is in for tabbed forms, workflow indicators etc. The system will work out variations to the accent color where required.

Visualization Color Palette

Valid Hex Codes

You can provide a comma separated list of hex color codes (e.g. #bfd6f6,#8dbdff,#64a1f4,#4a91f2,#3b7dd8) to define the color range being used for

• List View Visualization
• Progress Indicators on the Sustainability Questionnaire

If a Visualization requires more colors than defined, the web application will fill the gap with the standard colour palette.

Note: these settings will not be applied to Word Clouds.

PDF Header Image File

Relative Path for image which is being used in the header of the PDF files, for example:

custom\images\main_logo.png

Note: the image will be displayed with a height of 40px. Images with a different height will be rescaled (retaining the aspect) to achieve that height.
Ideally, the height of the file provided is >= (GE) than 40px, as upscaling an image could result in image quality issues.

Information about the supported fonts for PDF files can be found here.

Hierarchical Path Displayed

Specifies whether or not the full hierarchical path displays in a hierarchical field. This applies for both the web application, and the way such fields are displayed in emails.

• Yes: Full path is displayed
• No: Short path is displayed

Maximum List Rows

Number between 1 and 200

The maximum number of rows displayed per 'page' in a list view.

Maximum Number of Shortcut Items in User's Menu

Number between 0 and 100

Controls the behavior of the Shortcuts feature in the Web Application.

• if Value = 0:
  the Favorites feature is disabled. The system will always show the list of workspaces which are available for the current user.
  
• if Value > 0:
  the Favorites feature is enabled. The number will determine the maximum number of favorite items which can be presented to the current user.

List Views Related Data Limits

Number between 10 and 1,000,000

Will limit the number of related records list views will process when getting the data.

If the set limit of related records is reached for any of the root records, the system will not return any records for this column.

This is to protect the SQL server from potentially very expensive queries.

Field

Valid Range

Notes

Acceptable Input Deviation (%)

Number between 0 and 100

Is used for Emissions Data Entry Forms. If the currently entered value has a deviation from the average of the previous 4 records outside the acceptable range, users will be forced to enter a comment to explain the variation.

To disable this check, set the value for this field to 0 (zero).

Ditch Carbon URL

Provided by your SAI360 representative, once you have subscribed to receive automatic Emissions Factor downloads from DitchCarbon

Ditch Carbon Token

Provided by your SAI360 representative, once you have subscribed to receive automatic Emissions Factor downloads from DitchCarbon

Field

Valid Range

Notes

Maximum Invalid Login Attempts

Number between 0 and 10

The number of times a user can try to log in to the system with an incorrect user name or password. The default is 3.

Password Expiry Period (days)

Number between 0 and 10,000

The number of days a password can remain the same following first login and subsequent password change. After the number of days specified here, the user is prompted to change their password.

If the user doesn't change their password before it expires, on their next login they will be redirected to the Change Password page.

If you set a value of 0, then no restrictions apply. The password will remain valid over time.

NOTE:
the password expiry period WILL NOT APPLY to users who's password is verified using the Active Directory.

Auto Login

Automatic login allows users on a network or intranet to bypass the Login window when they launch a SAI360 application. Automatic login checks that the user has already logged into the network with a valid domain user name, then uses that user name to allow immediate access to the SAI360 applications.

Note: each SAI360 user has a corresponding setting. This user specific setting will override the Global Setting.

Change All Users' Login Type Setting To

• Manual: sets the login type for ALL users to be manual.
• Automatic: sets the login type for ALL users to be automatic.
• No change (default setting): leaves the current login settings as are.

Allow User Account Change

In an Auto Login scenario, this function allows you to specify whether users can log into the web application with a name different to their network name.

This is a global setting that applies to ALL users.

Please check here for more details on the Login/Logout Process.

Minimum Password Length

Number between 0 and 20

Sets the minimum character length for a user's password.

Maximum Password Length

Number between 0 and 20

Sets the maximum character length for a user's password.

Password Mask

max 255 characters

Sets a mask for passwords, using "regular expressions", which determines the character/number/upper/lower case patterns required.

The default is .* (a period preceding the asterisk), meaning that the user can use a password in any format.

Some of the password formats you can define are to enforce:

• Mixed case
• Inclusion of a Number
• Inclusion of Special Characters

Example: if you want to enforce that a password must contain at least one UPPER case, and one lower case character, then you could use this expression:

(\p{Lu}{1,}\p{Ll}{1,})|(\p{Ll}{1,}\p{Lu}{1,})

PASSWORD EXCLUSION LIST

As an additional means of preventing some passwords you can create a Password Exclusion List.

• File Name: password-exclusion.txt
• Location: typically the file is located on the same drive as the SAI360 web application, in the directory: <Drive:>\SAI360\config\

Enter each string which is to be excluded in a new line.

All entries are treated as 'wildcards' and are case insensitive. For example:

• String entered: acme
• Will for example prevent all of the following passwords:
  ACME, Acme, 123Acme, ACME123, myAcme, my Acme

NOTE:
any password length, mask or exclusion settings WILL NOT APPLY to users who's password is verified using the Active Directory.

BMS Admin Lockout Period (secs)

Number between 3,600 and 86,400

The time after which a disabled BMS Admin user will be automatically activated again (for example the maximum number of invalid logins has been reached).

Login Page HTML Source

Defines a HTML Source which can be displayed on the SAI360 Login Screen, next to the Login Box.

This is an optional field - if left empty, upon startup SAI360 will only display a basic login screen.

Login Help HTML Source

Defines a second HTML Source which, when defined, will display an additional Help link on the Login, as well as on the Password Expired screen.

This allows clients to present information to users who may have trouble with login in, for example:

• Whom to contact?
• What are the rules/patterns when defining a new password?

Field

Valid Range

Notes

All Fields

Clients will need to enter the following details:

• Feed, License, Profile, UserID

The details for each of these fields are client specific, and can only be provided once a license to subscribe to the RegScan by Enhesa feed has been purchased.

Field

Valid Range

Notes

Enable authentication check OnResume and OnStart

If set to Yes, Roam will check that the user’s authentication is valid every time Roam is started up, or brought back into the foreground.

This means that if a user’s basic authentication password has expired, or their Open ID Connect token/session has expired, they will be forced to re-login immediately after opening Roam.

If set to No, Roam will open slightly quicker, and will not force a user with an invalid authentication credential to re-login when the user does something that requires server communication, like when the user saves a record or attempts to open My Tasks.

Keep Alive Ping Frequency (seconds)

Number between 0 and 10,000

Used exclusively for "per App VPNs", where a regular ping to the VPN is required to keep the VPN active.

To disable, set value to 0.

Connection Check Retries

Used only to assist with connectivity problems. When Roam is 'resumed', if the initial connectivity check returns false, Roam will re-check every second for the defined number of seconds before entering 'offline' mode. Use 0 to disable.

Section "Forms and Data Download"

These settings are being used to fine-tune how Roam handles long running threads, which can occur when users are downloading full forms and data onto their devices.

The defaulted values should be seen as a baseline only. They can be modified, but there are no general recommendations for an optimal setting, as these will vary from client to client.

For example, they Payload (Cache) lifespan will depend on the expected change frequency of the relational data which need to be downloaded to the Roam device.

We suggest to contact the SAI360 Helpdesk if you intend to make any changes.

Polling Frequency (in seconds)

Number between 1 and 10,000

Polling Frequency at which Roam will check whether a request for Component Data has been completed.

This time set here must be LESS than time set for the Payload Cache Lifespan.

Retry Length
(in seconds)

Number between 1 and 10,000

Overall time for which Roam will keep polling to check if a request for Component Data has been completed.

Payload Cache Lifespan (in hours)

Number between 1 and 10,000

Duration for which Forms and Data download payloads will be preserved for re-use as cache.

Some Details:
The Payload Cache caches forms and data prepared for each user, for a configurable amount of time (Lifespan >= 1 hour), so that if another similar user who needs the same forms and data logs in, it can be given to them without server-side processing.

This is only the case for "full" forms and data downloads which is triggered from the menu within Roam, or when a user logs in. The regular delta downloads do not use any kind of caching.

Component Data Payload Generation Thread Pool Size.

Number between 1 and 100

Number of concurrent Forms and Data download requests processed in parallel (during a full Forms and Data Download).

Maximum Days Without Delta Download

Number between 1 and 100

If no successful delta download has been completed for a given user in the last X days (as specified here), Roam will prompt the user to perform a Full Forms and Data Download.

The user can defer the Download, but Roam will repeat the message every time when the user opens the app, until the Download is being performed.

The default setting is: 14

Location Aware Radius (meters)

Number between 1 and 1000

Maximum distance from the Roam device's current location (in meters) in which the Roam device will detect records/items which have been set up as 'Location Aware'.

PREREQUISITES
To make use of this feature, you need to:

• set up the underlying Component to be Location Aware.
• configure Roam List Views to support Location Awareness

CLEARING THE PAYLOAD CACHE:

Particularly during configuration projects, it can be useful to clear the Payload Cache, so that you can force new data to be downloaded. This can be done by logging in to the SAI360 web application as a user with the "System Role - System Administrator" role, and then manually accessing the following URL:

.....NetForms/jsf/rest/data/cache/state?clear=true

Field

Valid Range

Notes

Enable Self Register?

• Yes: allows new people to interactively register themselves as users of the system.
• No: new system users can only be created by administrators, or via an import process.

Enable Forgot Password?

• Yes: allows existing users to reset their password
• No: users will not be able to reset their password

Accepted Domains

To Self Register, the new user needs to specify an email address. You will need to provide a list of valid email Domains from which a user can register. To list several domains, you need to separate them with an semi colon.

For example: sai360.com;acme.com

Default Role for Self Registered Users

This is the role which the system will automatically assign to Self Registered Users.

Administrators Email

When a registration fails, the system will send an email to the address which is specified here. The message will show the email address and the full name of the person whose registration attempt failed.

New User Email Message

This is the message which will be sent to email address of the newly registered user.

You can enter your own text, and also make use of the following variables:

• {username}: the new username of the self registered user.
• {password}: the system created password for the new user.
• {weburl}: the URL to log into the system.

Forgot Email Password Message

This is the message which will be sent to an existing user when this user needs to reset their password.

You can use free text, as well as the variables which are shown above.

Field

Valid Range

Notes

Force users to spell check before saving

• Yes: when the user cancels out of the spell checker, the user is returned to the unsaved record.
• No: when user cancels out of the spell checking, they are given the option to save the record.

Allow misspelt proper nouns

• Yes: misspelt proper nouns will be ignored. E.g. 'africa' instead of 'Africa'.
• No: misspelt proper nouns will be highlighted as being spelled incorrectly.

Allow words with mixed case

• Yes: words which are typed in 'miXEd CAse' will be ignored.
• No: words which are typed in 'miXEd CAse' will be highlighted as being spelled incorrectly.

Ignore words in UPPERCASE

• Yes: words in UPPERCASE will be ignored for spell checking.
• No: words in UPPERCASE will be included in the spell checking.

Ignore words that contain numbers

• Yes: words containing numbers will be ignored for spell checking.
• No: words containing numbers will be included in the spell checking.

Include custom dictionaries in suggestions

• Yes: Custom Dictionaries will be included for spelling suggestions.
• No: system will only use the global dictionaries for suggestions.

Flag repeated words

• Yes: repeated words will be highlighted as being incorrect, e.g. 'There is is not a problem'.
• No: repeated words will be ignored.

Spell Checking will only be applied to fields which have been selected to be spell checked in the Form Designer.

Field

Valid Range

Notes

Enable Review Process

Select this to include an extra stage in the Sustainability Workflow, where all entered Sustainability data must be reviewed and approved, or can be rejected.

Field

Valid Range

Notes

Query Analyser Algorithm

Those settings alters the way the system is constructing SQL statements, which can affect performance.

Those setting should only be changed under advice from SAI360.

Email Default Fallback Address

When a new Email Action is created, the value which is defined here will be used as the default for the field "Fallback Address".

Date Format: On Demand Report

Deprecated functionality.

Reply To Messages

Yes: The recipient can reply to the email address set in the Email Default From Address.

• No: This is the default. Use this setting if the Email Default From Address contains a 'dummy' address, which is not monitored by anyone.

Session Timeout (secs)

Number between 0 and 86400

The time (in seconds) before the current login expires if no activity has been detected. The default is 3,600 (60 minutes). This is a general setting and is not based on users or any web server session timeout settings.

Enable Session Timeout Warning

• Yes: the Web Application will display a pop-up message 5 minutes prior to the user being logged out. Simply by confirming the message, the system will extend the Session Timeout by the time defined above.
• No: users will not receive this warning.

SiteID

Any 7 digit number

This number is for internal use only. It can only be modified by the BMS Admin user.

Notification Polling Interval (secs)

Number between 0 and 300

The interval (in seconds) that the client checks the server for System Notifications.

A value of '0' will turn notifications off altogether.

File Extensions Whitelist

• A comma separated list of all file-types which users can upload into the SAI360 database. File types which are not included in this Whitelist will be blocked from being uploaded.
• The system also supports wild-cards, for example:
• .doc*: to support the upload of files of type "doc", and "docx"
• .*: if there are no restrictions on the types of files a user can upload.

User-to-Person Value

• Is used to define how the system can create a link between the logged in User and a Person.
• The system will present a list of all Constants, and User Profiles which are linked to the Person Component. Typical examples are:
• .USER_OBJECT (a constant)

.Profile_Person (a Profile Value)

Maximum Upload Size (MB)

Number between 1 and 35

The total maximum size of files uploaded for storing in the database, per record.

Maximum Hierarchy Depth

Number between 1 and 100

Determines the maximum depth of hierarchies for BI reporting, and for List View Visualizations.

As the performance of the ETL will decrease with higher values, please only define a value as high is necessary to support your organizational structure.

Max number of list view columns before ‘Quick Filter’ is disabled

Maximum number of list view columns. If the columns exceed on the amount configured it will disable the List View Quick Filter. Set your number only as high as necessary, as this setting will influence the List View Quick Filter

Field Mappings

The following entries need only be changed for the VERY RARE occasion that the Component which is used as the Person Component has been deleted and replaced by another Component.

In most cases, these settings need to be left as they are.

Person Component

ID of the Person Component.

Standard Value: 9999999_101

Person Surname Field

ID of the field which contains a Person's Surname.

Standard Value: bms_9999999_1001

Person Given Name Field

ID of the field which contains a Person's Given Name.

Standard Value: bms_9999999_1002

Person Email Field

ID of the field which contains a Person's Email Address.

Standard Value: bms_9999999_1231

Person User Name Field

ID of the field which contains a Person's User Name.

Standard Value: bms_9999999_3692

APIs

The following attributes control a range of the APIs used by SAI360.

Enable Rest API

Set the flag to YES to enable the Rest API.

Enable Roam

Set this flag to YES to enable the use of the Roam mobile application.

Google API Key

You need to purchase and enter a Google API Key with both "Maps JavaScript API" and the "Places API" enabled to make use of

• Map Fields in the web application,
• Map Charts (part of Visualizing List View Data)

Once you save the record, the key will become hashed out.

Bing API Key

Only when using Roam for Windows, you need to purchase and enter a Bing API Key. Please contact your SAI360 representative for details.

Inline Manual Key

This specifies the key required for In-Product Training.

• In-Product Training carries an additional recurring licence and a one-time setup fee.
• Customers can purchase the add-on functionality to configure their Training or get our professional services team to do the configuration.
• In- Product Training is only available in the Web Application.

In-Product Training takes place directly within the web application to assist users with everyday system tasks. It may include product tours, interactive walkthroughs, videos, quick reference cards and links to other useful help resources.

Please speak to your Account Manager for further details.

Rest Callout Connection Timeout (Sec)

Rest Callouts (calls to external Rest APIs) will time out after this many seconds.