Customization

Using servers.json to Configure Immerse Options

This topic describes how to use the servers.json file to define the default connection behavior in Heavy Immerse. It describes how to enable default behavior using servers.json, provides basic syntax, and includes examples. You can define the HEAVY.AI database to connect to, as well as the username and password. You can also configure Immerse to use additional tile sources for geo charts.

Editing heavy.conf to Enable servers.json

To enable default behavior through a servers.json file, you must first edit heavy.conf to include servers.json information:

1. In your HEAVYAI_STORAGE directory, open heavy.conf. For information about heavy.conf and available options, see Configuration Parameters.

2. In the [web] section of heavy.conf, reference servers.json by adding the following line:

   servers-json = "/servers.json"

   Replace with the full path to servers.json.

3. Save heavy.conf.

servers.json File Properties

Property	Description
"database": "<database_name>"	The name of the database that Immerse connects to by default.
"host": "<hostname>"	Name of the database host.
"loadDashboard": "<id>"	ID number of the Immerse dashboard to load on login.
"login_panel_databases" : [ "database_1", "database_2", "database_3" ]	Dropdown menu of databases to select at login. Note: If you also provide the database key, it should be one of the databases listed in login_panel_databases, which is then selected by default.
"password": "<password>"	Immerse user password.
"port": "<port_number>"	Port used for connecting to the database host.
"protocol": "<protocol>"	Connection protocol to use: http or https.
"url": "<URL>"	Universal resource locator. Defines the path to the source database. Can be used as an alternative to identifying host and protocol.
"username": "<username>"	Name of the Immerse user.
"feature_flags": "<[options]>"	Set global default settings for the Immerse user interface. For options and details, see Feature Flags.
"immerse_ui_keys": "<[options]>"	Define the parts of the Immerse user interface that are visible. For options and details, Immerse User Interface Keys.
"immerse_ui_embed_keys": "<[options]>"	Same functionality as immerse_ui_keys; used when immerse is running embedded in an iframe.
"default_chart_type" : "<chart_type>"	Define the default chart type selected when adding charts to a dashboard. Chart types include: backendChoropleth (GPU Choropleth) backendScatter (Scatterplot) bar (Stacked Bar) choropleth (CPU Choropleth) gauge geoheat (Geo Heatmap) heat (Heatmap) histogram line line2 (original Combo) linemap number point map row (Bar) scatter (Bubble) table text (Text Widget) vega-combo (New Combo)
"hidden_charts": ["<chart_type>", "<chart_type>", ...]	Hide one or more chart types so that they are not visible on the Heavy Immerse interface. Chart types include: backendChoropleth (GPU Choropleth) backendScatter (Scatterplot) bar (Stacked Bar) choropleth (CPU Choropleth) gauge geoheat (Geo Heatmap) heat (Heatmap) histogram line line2 (original Combo) linemap number point map row (Bar) scatter (Bubble) table text (Text Widget) vega-combo (New Combo)
"maxBounds": [ [<lonMin>, <latMin>], [<lonMax>, <latMax>] ]	Sets the minimum and maximum bounds (longitude and latitude values) of new and existing maps. Zooming is permitted only within the bounds defined.
"offline": true	Set to true to help Immerse identify an offline environment and show a basemap (countries boundary geojson polygons) for Geo charts. Otherwise, Immerse shows Mapbox basemaps and any custom basemaps you have defined.
"enableJupyter": <boolean>	Set to true to enable Jupyter features in Immerse. For more information, see JupyterLab Installation and Configuration.
"SAMLUrl": "<url>"	Enable SAML in Immerse. The URL value is Identify Provider Single Sign-On URL. For more information about configuring SAML, see Connecting to HEAVY.AI Using SAML.
"customStyles": "<[options]>"	Productize Immerse by customizing colors, login text, logo, and other UI elements. For more information, see Enable Custom Styles.
"mapboxCustomStyles": "<[options]>"	Specify and use basemap styles other than those provided with Immerse. For more information, see Enable Custom Basemap Styles for Geo Charts.

Configuring Data Source and User Login Credentials

You can create a servers.json file to control the default configuration when you log in to Heavy Immerse. The information in servers.json can identify the database you connect to and credentials to use during automatic login.

1. If servers.json does not exist yet, create a file by that name in the HEAVYAI_STORAGE directory.

2. In servers.json, specify the database to connect to, as well as username and password information. You can use host, port, and protocol to specify the path to the data:

   [
      {
             "database": "<database_name>",
             "port": "<port_number>",
             "host": "<hostname>",
             "protocol": "<protocol>",
             "username": "<username>",
             "password": "<password>"
           }
   ]

   Alternatively, you can define the data source using a URL:

   [
      {
             "database": "<database_name>",
             "url": "<URL>",
             "username": "<username>",
             "password": "<password>"
           }
   ]

3. Save servers.json.

• If you leave the option values blank, the Immerse login form loads with blank fields.

• The contents of servers.json must be formatted as an array.

Feature Flags

The feature_flags section lets you set global default settings for the Immerse user interface.

Element	Description
"performance/query_cache_duration": <number>	Amount of time to store non-raster query results, in milliseconds.
"performance/query_cache_size": <number>	Number of queries (non-raster) to store.
"performance/vega_cache_duration": <number>	Amount of time to store raster map query results, in milliseconds.
"performance/vega_cache_size": <number>	Number of raster map queries to store.
"ui/dashboard_tabs": <boolean>	Set to true to enable the tabbed interface for dashboards. Tabbed interface is enabled by default (true).
"ui/default_filter_panel_open": <boolean>	Set to determine whether the filter panel is open. Filter panel is closed by default (false).
"ui/default_simple_filters": <boolean>	Set to determine if the filter panel opens in simple mode; off (false) by default. To set the filter panel to open in simple mode, set to true.
"ui/default_theme": "light" | "dark"	Set the default Immerse theme for all users. If a user has defined their own theme, that theme is used for that user's instance. If a user has not specified a theme, but the default theme is set in servers.json, that default theme is used. If no default theme is set, the system default is dark mode.
"ui/enable_auto_dashboard_refresh": <boolean>	Set to true to enable dashboard Auto Refresh dropdown dialog (default). When set to false, the Refresh button is still available, but the Auto Refresh dropdown option is unavailable.
"ui/enable_brush_filter_edits_from_chart": <boolean>	Set to true to enable editing of Combo chart brush ranges through text input in the upper-right corner of the chart. Disabled by default (false).
"ui/enable_chart_addons": <boolean>	Set to true to enable crossfilter replay. Enabled by default (true).
"ui/enable_contour_chart": <boolean>	Set to true to enable Contour charts. Enabled by default (true).
"ui/enable_crossfilter_replay": <boolean>	Set to true to enable crossfilter replay. Disabled by default (false).
"ui/enable_data_catalog": <boolean>	Control whether the Data Catalog is enabled in Immerse. The value is true by default. Set the value to false to disable and hide the Data Catalog.
"ui/enable_linked_zoom": <boolean>	Linked zoom is disabled by default (false). Set to true to enable linked zoom. Enabling linked zoom can impact performance.
"ui/enable_map_exports": <boolean>	Set to true to enable geoJSON and CSV export for Choropleth, Linemap, and Pointmap charts. Disabled by default (false).
"ui/enable_new_combo_chart": <boolean>	Controls whether the New Combo chart is available in Chart Editor, and also controls whether Duplicate as New Combo is available. true by default. Set to false to disable New Combo charts.
"ui/enable_trial_mode": <boolean>	Set to true to enable Trial Mode in Immerse. Trial Mode hides dashboard export options in the dashboard list, and hides individual chart export options on individual charts when viewed on a dashboard, for users who have the immerse_trial_mode role. Disabled by default (false).
"ui/enable_unrestricted_ percentage_view_pie_chart": <boolean>	By default (false), Pie chart percentage labels and All Others slice options can only be toggled on for a # Records or SUM() aggregate. Set to true to allow percentage labels to be toggled on or off for any aggregate value in a Pie chart.
"ui/geojoined-bounding-boxes":<boolean>	When a Choropleth chart is created with a geojoined table, by default (false) the bounding box of the geo table does not affect the fact table. If you pan or zoom on the Choropleth chart, other charts on the fact table are not affected. Set to true for panning and zooming on a geojoined Choropleth chart to affect other charts on the fact table.
"ui/global_side_nav":<boolean>	Set to true to enable all of the side navigation elements. Default: true.
"ui/limit_charts_per_dashboard": <number>	Set to limit the maximum number of charts in a dashboard. Does not retroactively remove charts from dashboards exceeding the chart limit. Default: 0 (no limit).
"ui/map_export_limit": <number>	Sets the limit for rows exported in map charts. Default: 100,000.
"ui/pointmap_default_points": <number>	Sets the default limit for pointmap points. Must be between 1000 and the value set in pointmap_max_points. Default: 10,000,000.
"ui/pointmap_max_points": <number>	Sets the maximum number of points on a pointmap. Must be greater than 1000. Default: 10,000,000.
"ui/restricted_viewing": <boolean>	Adds additional restrictions to the VIEW-only experience. If set to true, a user with VIEW-only access to a dashboard and no EDIT privileges cannot add new charts or modify existing charts. Default: false.
"ui/session_create_timeout":<number>	Modify login request timeout. Default: 10000 (10 seconds).
"ui/shift_to_zoom": <boolean>	Set to true to require that the Shift key be held down for pan/zoom actions on Combo and Map charts. By default, the Shift key is not required (false).
"ui/show_ui_config_panel": <boolean>	Controls visibility of the UI Settings panel for non-superusers. Panel is available by default (true). Set to false to make the panel unavailable.
"ui/show_ui_config_panel_axis_trunc": <boolean>	Controls visibility of Label defaults in the UI Settings panel for non-superusers. Label defaults is available by default (true). Set to false to make Label defaults unavailable.
"ui/show_ui_config_panel_chart_margin": <boolean>	Enable ability of non-superusers to configure chart margins. Set to true to allow chart margin configuration.
"ui/show_ui_config_panel_color_palettes": <boolean>	Controls visibility of the Color palette in the UI Settings panel for non-superusers. The Color palette is available by default (true). Set to false to make the Color palette unavailable.
"ui/start_of_week": "week_saturday" | "week_sunday" | "week"	Select the start-of-week day: week_saturday (Saturday),week_sunday (Sunday), or week (Monday; default).

Immerse User Interface Keys

The immerse_ui_keys section of servers.json enables you to configure which parts of the Immerse user interface are visible to the user.

Key	Description
"default": "[NONE | ALL]"	Configure Immerse to show all or none of the UI elements by default.
"ui_on": "<ui_element>" [, "<ui_element>", ...]	Configure UI elements to show in Immerse; see the following table for the list of UI keys.
"ui_off": "<ui_element>" [, "<ui_element>", ...]	Configure UI elements to hide in Immerse; see the following table for the list of UI keys.

For example, turn off all turn off all parts of the UI, and then explicitly turn back on tabs, the SQL editor, and the global side navigation.

"immerse_ui_keys": { 
   "default": "NONE", 
   "ui_on": ["tabs", "sql_editor", "global_side_nav"] 
   }

The following table shows the names of the user interface keys that can be used to turn UI features on or off. Values are not case sensitive and can be prepended with IMMERSE_UI_.

Key Value	User Interface Feature
"navbar"	Navigation bar
"headerbar"	Header bar
"side_panels"	Side panels
"filters"	Filter configuration
"parameters"	Parameters configuration
"config_ui"	Configuration UI
"crosslink"	Crosslinking
"filter_sets"	Filter sets
"annotation"	Annotation
"save"	Save a chart or dashboard
"refresh"	Refresh a dashboard
"add_chart"	Add a chart
"add_tab"	Add a tab to a dashboard
"user_dropdown"	Dropdown for user selection
"help_dropdown"	Dropdown for help
"sql_editor"	SQL Editor function
"jupyter_labs"	JupyterLabs button
"data_manager"	Data manager
"dashboards"	Dashboards list
"tabs"	Tabs configuration
"global_side_nav"	All side navigation
"global_side_nav_toggle"	Ability to toggle side navigation

Using Query Strings

You can use query strings in URLs to configure Immerse user interface keys, using the ui_on and ui_off parameters:

<url>?ui_on=<key_value>,[<key_value>...] 

<url>?ui_off=<key_value>,[<key_value>...]

For example, to turn on the tabs and SQL Editor button:

?ui_off=tabs,sql_editor

All of the key values described in Immerse User Interface Keys apply to query strings. Values are not case sensitive and can be prepended with IMMERSE_UI_.

Custom Styles

To productize Immerse, you can add the customStyles JSON object to servers.json. Use the customStyles elements to:

• Customize colors

• Customize the text displayed in the browser tab

• Add your own logo

• Customize the login text

• Disable the Help menu dropdown on the navigation bar

JSON Branding Elements

Element	Description
buttonPrimaryColor	Button color when inactive
buttonSecondaryHighlightColor	Button color when hovering.
colors	Hexadecimal color definitions used in charts.
custom	Custom colors, requires 11 or more colors. These are the options available in the Color by Dimension pop-up.
darkThemeLogoURL	URL to your dark mode logo. You can set different logos for light and dark mode. If no dark mode logo is configured, the logo defined in logoURL is used for both light and dark mode. Must be a browser-accessible http(s) URL, not a file system path.
disableHelpMenu	Set to true to disable Help dropdown on the navigation bar.
loginText	Specify custom text for the Immerse login page.
logoURL	URL to your logo. You can set different logos for light and dark mode. If a dark mode logo is configured in darkThemeLogoURL, the logo defined in logoURL is used for light mode only. If no dark mode logo is configured, the logo defined in logoURL is used for both light and dark mode. Must be a browser-accessible http(s) URL, not a file system path.
ordinal	4 scales, 1 or more colors each scale. Defines a range of colors that measures iterate through repeatedly. The size of the range can vary.
quantitative	4 scales, 1 or more colors each scale. Quantitative measures produce smooth, continuous gradients between each "stopping point" defined in the list of colors, in order.
secondaryButtonColor	Button color when pressed.
solid	Solid colors, requires 8 or more colors. All measures are assigned one color. The array of colors you provide defines which colors are available.
title	Text displayed in the browser tab.

Notes

• You can also set fonts and colors in the Immerse UI Settings panel. For more information, see Configuring the Dashboard User Interface.

• There are no visual design guarantees when using a large number of colors. For example, visual elements might bleed beyond borders or have an unexpected layout.

• Custom styles do not affect the settings for charts or dashboards saved before the custom styles are defined. However, you can edit existing charts and replace the colors in use to colors in your custom palette.

Loading Custom Stylesheets Using override.css

You can load custom stylesheets after the default Immerse styles by replacing override.css with with your own stylesheet.

The following example shows a login container style override. The code changes are reflected in the figures that follow.

*/ .login-container { 
   background-color: blue !important 
}
/* Dark mode variants (AKA "Heavier mode") can be specified with :not(.lighter-mode)

*/ .login-container:not(.lighter-mode) { 
   background-color: rebeccapurple !important; 
}

*/ .login-container:not(.lighter-mode) { background-color: rebeccapurple !important; }

Full servers.json Example

The following example shows a complete servers.json file that includes customization. When you want to change any of the settings in servers.json, you must replace all settings in servers.json, even if you duplicate the default values.

[
{
   "database": "heavyai",
   "url": "localhost",
   "port": "6273",
   "username": "admin",
   "password": "HyperInteractive",
   "feature_flags": {
      "ui/default_theme": "light"
   },
   "customStyles": {
      "logoURL": "http://www.heavyai.com/docs/latest/images/3_panda.png",
      "loginText": "Log in to Panda Bear Wear Ware",
      "title": "Where Panda Bear Wear Ware Wearers Dare Care",
      "buttonPrimaryColor": "#888888",
      "buttonSecondaryColor": "#444444",
      "buttonSecondaryHighlightColor": "#000000",
      "colors": {
        "solid": [
           "#333333",
           "#555555",
           "#777777",
           "#999999",
           "#aaaaaa",
           "#cccccc",
           "#eeeeee",
           "#ffffff"
        ],
        "custom": [
           "#000000",
           "#eeeeee",
           "#222222",
           "#cccccc",
           "#444444",
           "#bbbbbb",
           "#666666",
           "#aaaaaa",
           "#333333",
           "#dddddd",
           "#111111"
        ],
        "ordinal": [
           [
              "#111111",
              "#cccccc"
           ],
           [
              "#111111",
              "#777777",
              "#cccccc"
           ],
           [
              "#111111",
              "#555555",
              "#999999",
              "#bbbbbb",
              "#eeeeee"
           ],
           [
              "#111111",
              "#333333",
              "#555555",
              "#777777",
              "#999999",
              "#bbbbbb",
              "#dddddd",
              "#eeeeee"
           ]
        ],
        "quantitative": [
           [
              "#555555",
              "#cccccc"
           ],
           [  "#111111",
              "#eeeeee"
           ]
        ]
      }
   }
}
]

This example is for the totally-not-made-up company Panda Bear Wear Ware, where you can find all of your Panda Bear Wear Ware in one lair with time to spare. There is an understandable predilection toward black, white and everything in between on their color palette.

The first section contains branding information for their Heavy Immerse instance.

"logoURL": "http://www.heavyai.com/docs/latest/images/3_panda.png",
"loginText": "Log in to Panda Bear Wear Ware",
"title": "Where Panda Bear Wear Ware Wearers Dare Care",
"buttonPrimaryColor": "#888888",
"buttonSecondaryColor": "#444444",
"buttonSecondaryHighlightColor": "#000000",

The logo, labeling, and button colors are visible at the dashboard level.

The Solid palette colors all items in Line, Pie, Bar, and other charts with one color. You can define the array of available colors.

      "colors": {
        "solid": [
           "#333333",
           "#555555",
           "#777777",
           "#999999",
           "#aaaaaa",
           "#cccccc",
           "#eeeeee",
           "#ffffff"
        ],

The Ordinal palette defines a range of colors that are iterated repeatedly in a chart with many values. You can define multiple ranges from which to select.

"        ordinal": [
           [
              "#111111",
              "#cccccc"
           ],
           [
              "#111111",
              "#777777",
              "#cccccc"
           ],
           [
              "#111111",
              "#555555",
              "#999999",
              "#bbbbbb",
              "#eeeeee"
           ],
           [
              "#111111",
              "#333333",
              "#555555",
              "#777777",
              "#999999",
              "#bbbbbb",
              "#dddddd",
              "#eeeeee"
           ]
        ],

For example, a Pie chart can cycle through colors on the Ordinal palette to color each segment.

The Custom palette populates the Custom and Color By Dimension pop-ups, allowing you to assign specific colors to one or more values.

        "custom": [
           "#000000",
           "#eeeeee",
           "#222222",
           "#cccccc",
           "#444444",
           "#bbbbbb",
           "#666666",
           "#aaaaaa",
           "#333333",
           "#dddddd",
           "#111111"
        ],

The Quantitative palette gives a range of two or more colors. Values are expressed as a gradient on a continuum between the colors you define. You can create multiple value sets.

        "quantitative": [
           [
              "#555555",
              "#cccccc"
           ],
           [  "#111111",
              "#eeeeee"
           ]
        ]

Enable Custom Basemap Styles for Geo Charts

If you work extensively with geospatial data, you might need to use basemap styles that are different than those provided by Immerse. By modifying servers.json, you can use custom map styles created with Mapbox Studio, as well as third-party OGC-compliant raster tile sources.

To use different basemap styles, add the mapboxCustomStyles property, and then define the source.

Entering a source incorrectly can result in unexpected behavior in the geo charts, or cause Immerse to not load. Make sure that mapboxCustomStyles is an array, and that the objects in the array have label and value properties. To avoid errors, consider using a JSON validator like JSON Lint to make sure the code is correctly formatted before starting Immerse.

If you are an administrator, you can change the built-in styles to a new set of Mapbox tiles.

In releases before Release 6.1.0, custom styles with overlapping names would be appended to the list. This duplication of style names could cause unpredictable behavior. In Release 6.1.0 and higher, the style is defined by what is specified in servers.json.

To delete a theme, add a custom style without a value. For example, to delete the Satellite theme, add the theme and then define the value as follows:

{
    "label" : "Satellite"
    "value" : ""
}

A custom theme can be defined as the new default. Normally, the default theme is Current Immerse Theme, but by specifying "default" : true, the new theme becomes the default. For example:

{"label: "my-cool-theme", "value" : "mapbox://my.mapbox.url", "default" : true}

The default theme appears first in the map theme selector.

If a theme’s value is changed (including changing the value of an Immerse-installed theme), a map using them will update to keep the same theme, but use the new Mapbox URL value.

If a theme is deleted, then any maps referencing that theme revert to the default.

The following example syntax shows how to add custom base maps using the mapboxCustomStyles property, in the following order:

• A custom map style created in Mapbox Studio and hosted on mapbox.com.

• A basemap style hosted on a Mapbox Atlas Server.

• A third-party OGC-compliant raster tiles source not affiliated with Mapbox. This source must adhere to the Mapbox Style Specification.

[
  {
        "database": "<database>",
        "password": "<password>",
        "url": "<heavyaiserver>",
        "port": "<port_number>",
        "username": "<username>",
        "mapboxCustomStyles": [
          {
                "label": "custom-mapbox-studio-source",
                "value": "mapbox://styles/heavyai/<mapbox-studio-style-id>"
          },
          {
                "label": "mapbox-atlas-source",
                "value": "http://<domain>:<port>/pages/<style_name>/<style_name>.json"
          },
          {
                "label": "3rd-party-raster-source",
                "value": {
                  "version": 8,
                  "sources": {
                          "openstreetmap": {
                                  "type": "raster",
                                  "tiles": [
                                          "http://a.tile.openstreetmap.org/{z}/{x}/{y}.png",
                                          "http://b.tile.openstreetmap.org/{z}/{x}/{y}.png"
                                  ],
                                  "tileSize": 256
                          }
                  },
                  "layers": [{
                          "id": "openstreetmap",
                          "type": "raster",
                          "source": "openstreetmap",
                          "minzoom": 0,
                          "maxzoom": 22
                  }]
                }
          }
        ]
  }
]