Additional Configuration

Currency Symbol In XLSX Output

By default, the currency symbol used is (¤) is used when an XLSX output is generated. This may not be the desired symbol to use.

You can use the currency symbol “$” XLSX output for the RML reports and for dashboard export to XLSX.

To do so, add an extra line in the application.conf file:

  • For RML reports

    elixir.rml.xlsx.currency-symbol = "[$$-4809]"

  • For dashboard export to XLSX format (for Ambience only)

    ambience.dashboard.pivot { xlsx-export { currency-code: "[$$-409]" } }

ETL

ETL Logs

By default, the ETL job logs is created as the job runs. These logs allow you to observe the behaviour of the jobs. But these logs may not be useful for production systems as they may run the ETL jobs 24 hours a day, thus generating huge volumes of log. This may slow down the system.

You can turn off the job log by adding the following into the application.conf file.

ambience.etl.logging.write-to-server-log: false
ambience.etl.logging.write-to-job-log: false

Apose Extensions for ETL Steps

To enable the Apose extensions for ETL steps, you require a separate license. Add the following into the application.conf file.

ambience.docx-engine.aspose {
  enabled = true
  words-license = "/<pathname>/Aspose.Words.Java.lic"
}

Minimum XLSX Inflate Ratio

To allow ETL steps to be able to read lower zip ratio, you can customise the minimum XLSX inflate ratio to support Apache POI zip bomb detection.

In the application.conf file, add the following line:

elixir.poi.zip-secure-file.min-inflate-ratio = 0.006639

The inflate ratio used above is an example, it can be changed to suit your usage.

Config Editor

The Config Editor module in Ambience allows you to edit the configuration and save the changes onto MongoDB. This allows you to edit at one location and let other servers share the same configuration without the need to duplicate the application.conf file.

Before that can be done, the following need to be added into the application.conf file to allow the configuration in the Config Editor to be loaded.

ambience.config-loader.mongodb.enabled = true

This section is for Ambience only and does not apply to Repertoire.

Audit Log

Audit log will log any actions taken in the modules. Workflow module stores data either in elxPublic (server only) or elxPrivate (shared within browser). It does not know whether any data it is logging is sensitive. You can turn on or off the logging by adding the following into the application.conf file.

ambience.modules.workflow.audit {
  public: true
  private: false
}

The default will only show the public changes. Set private: true to include elxPrivate changes.

This section is for Ambience only and does not apply to Repertoire.

Redirect Using ETL

To use ETL chainset to redirect a URL, there needs to be an ETL user which has a role that is added to the appropriate chainset. This is needed as the user being redirected may not have permission to run ETL. So, this user acts as a proxy to run the chain the redirect uses.

In the application.conf file, add the following:

ambience.modules.redirect-edit.etl-user = "<username>"

This section is for Ambience only and does not apply to Repertoire.

Report Portal Limit Sharing By Role

When reports are rendered, it is useful to share the report to a role or user.

By default, all roles are listed as options in the “Users and Roles” dialog box. To restrict these options to those that the user belongs to, add the following line in the application.conf file.

ambience.report-portal.limit-sharing-by-role = true

Git Deploy

To use Git deploy, the application configuration file need to add some code to allow the Git Deploy module to know where to locate the repository, either local or remote.

In the application.conf file, add the following:

ambience {
  modules {
    git-deploy {
      repositories {
        ## remote key: value pairs where the value may be a remote git
        ## repository like:
        "remote-sample": "git@git.example.com:<path in Git>"
        ## or a local git repository (cloned earlier, or used git init to create)
        "local-sample": "<path of local git folder>"
      }
      collections: ["Ambience", "Chainsets", "Dashboards", "DashboardViews",
        "Datasets", "Forms", "GISExplorer", "Visualisations", "Wev", "WebStore",
        "Workflows", "Privileges"]
    }
  }
}

The values support {enc} encryption.

Only the collections listed here will be stored by git-push.

Only the collections listed here and included in the it repository will be loaded by git-pull.

Any collections not listed here will not be used, even if they are in the Git repository.

This section is for Ambience only and does not apply to Repertoire.

Disabling Modules

Developer Module

The Developer module is useful in test/UAT. But it should be disabled in production system, this is to avoid other users from using it, accidentally altering data or any attack on the server.

In the application.conf file, add the following:

ambience.developer.enabled = false

This will disable the Developer module regardless of the privileges given. The module will still be loaded but the output will appear as:

12:28:20.234 INFO ambience.developer.DeveloperModule -- Developer module enabled: false

This section is for Ambience only and does not apply to Repertoire.

Themes Module

The Themes module allows you to manage and edit the theme (colour, font, etc.) used in Ambience. To have a uniform and standard look on the software, this module may be disabled to avoid other users from changing the settings in the theme.

In the application.conf file, add the following:

ambience.theme.enabled = false

This will disable the Themes module regardless of the privileges given. The Themes module will still be loaded with a “(Disabled)” label beside the title. There will be no response to any selection done in the module.

This section is for Ambience only and does not apply to Repertoire.

External Vault

The Secrets module acts as a repository and manager for secrets. These secrets can be stored either internally (in Ambience) or externally (using Hashicorp vault).

By default, the secrets are stored internally in Ambience and external vault is disabled.

To use external vault (in this case, its Hashicorp), install the Hashicorp, then enable the external vault in the application-conf file.

Below is the procedure to install Hashicorp and enabling Hashicorp in Ambience.

  1. The Hashicorp vault can be downloaded from the below link:

    https://developer.hashicorp.com/vault/downloads

    Select the correct version for your OS and follow the instructions in the webpage to install the vault.

  2. There are two modes to run the vault:

    a. Developer mode – which is held in memory

    b. HCL configuration mode – starts server with an HCL configuration file

  3. To start the server, open a terminal window and navigate to the location where the Hashicorp is installed.

    1. Use the following command to run the server in developer mode:

      vault server -dev

      The vault server will produce a token. Copy the token.

    2. Use the following command to run the server with an HCL configuration file:

      vault server -config=<path>

      where <path> is the location of the HCL configuration file.

      Once the server is running, use the following command to generate a token:

      vault token create

      Copy the token.

  4. Enable Hashicorp and add the token copied in step 3 using the application.conf file in the Ambience “bin” folder. Edit the fields in bold as follows:

    ambience.secrets-store.location {
  default {
    ...
  }
  hashicorp {
    type = "hashicorp"
    enabled = true
    address = "http://127.0.0.1:8200"
    vault = secret"
    token = "<insert your value here>"
    is-addable = true
    is-linkable = true
  }
}

  5. Restart the Ambience server for the Hashicorp vault to take effect.

Next: Docker Setup Guide