Menu
▾
▴
Settings
Settings
Certain settings are used to configure how ART works. Use the Configure | Settings menu to manage ART settings.
| Setting | Description |
|---|---|
| SMTP Server | The host name for the email server used to send emails |
| SMTP Port | The port to use for SMTP |
| Use StartTLS | Defines whether to use the StartTLS protocol when sending emails |
| Use SMTP Authentication | Defines whether the SMTP server requires a username and password in order to send emails |
| SMTP Username | The username to be used when sending emails if the email server is configured to require SMTP authentication |
| SMTP Password | The password to be used when sending emails if the email server is configured to require SMTP authentication |
| SMTP From | An email address to be used as the "From" email address for all jobs. Leave blank to use separate email addresses as configured in each job. |
| SMTP Server | An already configured smtp server that can be used for sending emails |
| Default Authentication Method | The authentication method that will be used by ART. OAuth authentication is currently experimental and is subject to change. |
| Windows Domain Controller | Used with windows domain authentication. The IP address of the windows domain controller. |
| Allowed Windows Domains | Used with windows domain authentication. The domain name of the windows domain used for authentication. Multiple domains can be specified, each separated by a comma. |
| LDAP Server | Used with LDAP authentication. IP address of the LDAP server. |
| LDAP Port | Used with LDAP authentication. LDAP server port. |
| LDAP Connection Encryption Method | Used with LDAP authentication. Defines which protocol to use for the LDAP connection. |
| LDAP URL | Used with LDAP authentication. LDAP server URL. If the LDAP server and port fields have been used, leave this setting blank. This setting only provides an alternative way of specifying the location of the LDAP server. |
| Use Anonymous Bind | Used with LDAP authentication. Defines whether to use anonymous bind when connecting to the LDAP server in order to search for and authenticate users. |
| LDAP Bind DN | Used with LDAP authentication. The DN to use when connecting to the LDAP server in order to search for and authenticate users. |
| LDAP Bind Password | Used with LDAP authentication. The password to use when connecting to the LDAP server in order to search for and authenticate users. |
| LDAP User ID Attribute | Used with LDAP authentication. The LDAP attribute which will be used to match ART usernames. |
| LDAP Authentication Method | Used with LDAP authentication. The authentication method to be used with the LDAP server |
| LDAP Realm | Used with LDAP authentication. The LDAP realm when using the Digest-MD5 authentication method. If blank, the default realm will be used. |
| HTTP Authentication Variable | Used with http header authentication. The name of the http header that will contain the username of an already authenticated user. |
| OAuth Provider | The OAuth 2.0 provider to use for oauth authentication |
| OAuth Client ID | The Client ID from the oauth provider |
| OAuth Client Secret | The Client Secret from the oauth provider |
| OAuth User Matching | The field in ART to use to match the oauth user |
| Azure Tenant ID | For oauth authentication using the Microsoft Azure provider, the tenant id of the Azure account if using a Single tenant application |
| Default Max Rows | The default maximum number of rows to output for a report |
| Specific Max Rows | The maximum number of rows to output for specific report formats, defined as a comma separated list of settings with each setting in the format viewmode:value e.g. htmlGrid:5000,xls:10000. Report formats are case sensitive. |
| PDF Font Name | Name of a custom font that should be used in generation of pdf output, and charts. For jasper reports, custom fonts need to be defined in the jrxml file. See the Tips documentation for details on how to use custom fonts with jasper reports. |
| PDF Font File | Path to a font file that contains the custom font |
| PDF Font Directory | Path to a directory that contains font files, one of which may be used in the pdf font name field |
| PDF Font Encoding | Encoding to use for the custom font |
| PDF Font Embedded | Whether the custom font should be embedded in the generated pdf output |
| Administrator Email | Email address which is displayed in link at the bottom of ART web pages |
| Date Format | Format to be used for date fields. Format strings to be used is as per the Java SimpleDateFormat class. |
| Time Format | Format to be used for time fields. Format strings to be used is as per the Java SimpleDateFormat class. |
| Report Formats | The report formats that will be available to users when they run a report, defined as a comma separated list. Report format names are case sensitive and the order specified will be respected in the list shown to users. |
| Max Running Reports | The maximum number of reports that can be running at any one time |
| Show Header in Public User Session | Whether to show the menu bar and page footer for reports that are run by a public user |
| Mondrian Cache Expiry Period | Number of hours after which the mondrian cache is automatically cleared. Set to 0 to disable automatic clearing. |
| Scheduling Enabled | Defines whether scheduled jobs will run |
| Max File Upload Size (MB) | Maximum file upload size. Set to -1 for no limit. |
| ART Base URL | The base URL for ART e.g. http://art-server:8080/art. This is used with a number of features including publish job reminder emails. Don't put a slash at the end. |
| System Locale | The locale to use in non-interactive scenarios e.g. jobs. An example is en. Leave blank to use the default, which will be the server locale. |
| Default Language | The language to use by default for the user interface |
| Hide Language | Whether to hide the language selection box on the login page |
| JWT Token Expiry (Mins) | The expiry time in minutes for JWT tokens generated for REST API authentication. A value of 0 means no expiry. |
| Enable Direct Report Emailing | Whether users can directly email generated report files |
| Help Link | A URL to your own page that provides help with the ART application. If set, a Help menu will be added to the main application menu, and the link will open in a new window/tab. |
| Job Error Notification | Email address to send emails to when an error occurs while running a job. Multiple email addresses can be specified separated by commas. |
| Pipeline Error Notification | Email address to send emails to when an error occurs while running a pipeline. Multiple email addresses can be specified separated by commas. |
| Encryption Key | Used in updating the encryption key used by ART |
| Error Notification To | Email address to send emails to when errors occur within the application. Multiple email addresses can be specified separated by commas. Set blank to disable error notification. The SMTP server used is the one configured in the Settings page. |
| Error Notification Subject Pattern | A string representing how the error notification email subject will look like. The syntax is Logback syntax. |
| Error Notification Level | The level for which error notification emails will be sent |
| Error Notification Logger | The logger for which error notification emails are sent. Blank means notifications are sent for errors logged from all classes. If you would like to only receive notifications for errors occurring in jobs, you can set this to art.jobrunners.ReportJob. Multiple loggers can be specified separated by commas. |
| Error Notification Suppress After | The condition at which to suppress sending of duplicate error emails. See the Whisper documentation for details. |
| Error Notification Expire After | The amount of time after which duplicate error email suppression is expired. See the Whisper documentation for details. |
| Error Notification Digest Frequency | The frequency with which to send duplicate error email digest messages. See the Whisper documentation for details. |
| Minimum Password Length | The mimimum password length when a password is set from the Password page. If set to 0, this check is not done. |
| Minimum Lowercase Characters | The minimum number of lowercase characters in a password as set from the Password page. If set to 0, this check is not done. |
| Minimum Uppercase Characters | The minimum number of uppercase characters in a password as set from the Password page. If set to 0, this check is not done. |
| Minimum Numeric Characters | The minimum number of numeric characters in a password as set from the Password page. If set to 0, this check is not done. |
| Minimum Special Characters | The minimum number of special characters in a password as set from the Password page. If set to 0, this check is not done. |
| Options | Additional settings in JSON format |
| CSS | Custom css to override existing styles within the application |
Options
A number of options can be specified in the Options field. These are defined in JSON format with the following possibilities.
| Property | Data Type | Description |
|---|---|---|
| dtExtraOptions | Object | Extra options for the htmlDataTable report format. Refer to the [Reports] section for more details. |
| excel | Object | Extra options for xls and xlsx report formats. Refer to the [Reports] section for more details. |
| homeDtOptions | Object | DataTable options for the home page. For the lengthMenu option, use a 1-dimentional array with -1 as the placeholder for the All option e.g. [10, 20, -1], and not a 2-dimentional array as in the DataTables documentation. For other options, use as per the DataTables documentation, e.g. setting the pageLength option of this object can change the default number of reports displayed in the home page. |
| configDtOptions | Object | Similar to homeDtOptions but applies to config pages |
| oauth | Object | Options for an oauth provider |
OAuth Options
Options for an oauth provider can be provided in an object as follows.
| Property | Data Type | Description |
|---|---|---|
| providerName | String | The name for the provider that is displayed to users on the login page. This is optional and can be used to provide a name different from the default. |
| providerType | String | The name of the OAuthProvider enum corresponding to a provider type e.g. "MicrosoftAzure". This is optional for use when specifying providers in the art-custom-settings.json file, to give an indication of the type of provider. |
| clientId | String | The client id. This should not be set in the Settings options but rather the OAuth Client ID field should be used. It should be used when specifying providers in the art-custom-settings.json file. |
| clientSecret | String | The client secret. This should not be set in the Settings options but rather the OAuth Client Secret field should be used. It should be used when specifying providers in the art-custom-settings.json file. |
| scope | String | The scope to use. This is not required if using the providers listed on the Settings page. By default openid will be used, or as per defaults for listed providers e.g. for Microsoft Azure, the default is openid profile. |
| usernameAttribute | String | The name of the claim or attribute within the id token that contains the username to use. This is not required if using the providers listed on the Settings page. This defaults to sub, or the defaults for the listed providers. |
| active | Boolean | When using the art-custom-settings.json file, can be used to turn off an oauth provider. Default is true. |
| userMatching | String | The name of the OAuthUserMatching enum corresponding to a user matching method e.g. "Email". This should not be set in the Settings options but rather the OAuth User Matching field should be used. It can optionally be used when specifying providers in the art-custom-settings.json file. |
| azureTenantId | String | For the Microsoft Azure provider, the tenant id of the Azure account if using a Single tenant application. This should not be set in the Settings options but rather the Azure Tenant ID field should be used. It should be used when specifying providers in the art-custom-settings.json file. |
OAuth Providers
Some notes are provided for oauth providers as follows.
Microsoft Azure
- You will need to set the Azure Tenant ID field if using a Single tenant application
- For the logout experience, if you don't want the user to be prompted to choose the account to logout from, you will need to add an Optional claim to your application. To do this, within Azure, select your application under the App registrations menu then select the Token configuration option and click on Add optional claim. In the given screen, select the Token type as ID and then check the login_hint claim and click on Add.
OAuth Notes
Some general oauth notes are provided below that apply to all oauth providers.
Login redirect URL
The login redirect or callback url to register with the oauth provider is <art base url>/oauthCallback. e.g. http://localhost:8080/art/oauthCallBack. This is the url that ART will set in the redirect_uri parameter when initiating a login request with the oauth provider, and is the url that the provider will redirect to after successful login.
Logout redirect URL
The logout redirect url to register with the oauth provider is <art base url>/login. e.g. http://localhost:8080/art/login. This is the url that ART will set in the post_logout_redirect_uri parameter when initiating a logout request with the oauth provider, and is the url that the provider will redirect to after successful logout.
Global Logout
To have your ART instance participate in global logout or single logout or front-channel logout, the url to register with the oauth provider is <art base url>/oauthLogout. e.g. http://localhost:8080/art/oauthLogout
Updating the encryption key
ART uses symmetric encryption to store some fields e.g. datasource passwords. This requires the use of an encryption key, which is included in the WEB-INF\classes\art\encryption\AesEncryptor.java file. If you would like to change the key used to encrypt values within the application, take the following steps.
Using an encryption key
- Backup the application files and the ART database. If something goes wrong, it may not be possible to decrypt password fields and so they may all need to be re-entered. This not only applies to datasources but also to reports which have open/modify passwords, destinations e.g. ftp servers among others.
- Login to ART. Ensure that no other users are using the appliction when embarking on an encryption key update.
- Once you have logged in and confirmed that the application is working OK, go to the file system and modify the WEB-INF\art-custom-settings.json file and set the encryptionKey field to the key to be used. This would use AES encryption and so the key would need to be either 128 bits (16 bytes), 192 bits (24 bytes) or 256 bits (32 bytes). If there was already a key set in this field, copy it somewhere in case something goes wrong and you need to replace it. Save the file. Do not stop the application or make this change while the application is not running. The application needs to be running already.
- Now go to the browser and on the Settings page, for the Encryption Key field, click on the Update button. If you get a success message, the update was successful. View the logs using the View | Logs menu to confirm that there were no errors or warnings. If there was an error, modify the art-custom-settings.json file and return the encryptionKey field the way it was before you attempted the update.
- If successful, in order to test/confirm, stop the application and then start it again. If you can run reports, the update should be successful.
- Once you have changed the encryption key, when you perform an upgrade of the application, you need to copy this key to the new version's art-custom-settings.json file before you first start the application. You can do this by unzipping the art.war file to a directory e.g. one named
art. You can use any zip utility for this as a .war file in just a .zip file. Make the necessary change and then deploy the new directory e.g.artto your applicaiton server. - In case you would like to go back to the default key, repeat this same process and set the encryptionKey field to the empty string "" when updating.
Using an encryption password
Instead of specifying the encryption key directly, you can supply a password which will be used to generate the encryption key. Take the same steps as for using an encryption key but specify the password in the encryptionPassword.password field. Additionally, set the desired key length of the generated key in the encryptionPassword.keyLength field. The key length must be either 128, 192 or 256 as per the AES algorithm.
Testing string encryption/decryption
You can test or encrypt/decrypt strings used in the ART application by running the ART encryptor on the command line. To do this, open a command prompt window and navigate to the WEB-INF\classes folder. Use the command java -cp "../lib/*;../etc/*;." art.encryption.AesEncryptor on windows or java -cp "../lib/*:../etc/*:." art.encryption.AesEncryptor on linux. You can then supply a string to encrypt/decrypt together with appropriate parameters. An example of encrypting a string using a password may be ...AesEncryptor -e -t "clear text to be encrypted" -p "encryption password" -l 256. You can use the help option to see available parameters e.g. ...AesEncryptor -h.
Note:
- If you change the ART Database and that database was based on a different encryption key, you will get errors. You would therefore need to remember which encryption keys were used with which database.
