Using a Dundas BI gateway

Contents[Hide]

1. Overview

For Dundas-hosted instances of Dundas BI, you can use a gateway to connect to your on-premise data or to install and use additional drivers for connecting to data sources.

Once the gateway is installed on your local network and configured in Dundas BI, users can create data connectors to access the following data sources via the gateway:

  • dBase (DBF) files
  • Flat files
  • MemSQL
  • Microsoft Excel
  • Microsoft SQL Server
  • MySQL
  • OData
  • ODBC (install ODBC drivers to use for additional data sources)
  • Oracle database
  • PostgreSQL
  • Teradata
  • XML files

Note
You don't need a gateway for cloud or publicly accessible data sources, if the data provider or driver is already available in your instance, or for uploaded files. Gateways can only be used with instances hosted and managed by Dundas.

2. System requirements

Some data sources may require drivers to be installed on the same computer as the gateway. The gateway also has minimum requirements for the operating system and for .NET that are similar to the server requirements for a Dundas BI instance, but the minimums listed for evaluation use can also be suitable for a gateway.

See Dundas BI - System Requirements for these requirements.

Note
The gateway should be installed on a computer that remains online in order to prevent errors when using data connectors in Dundas BI that use this gateway.

3. On Windows

3.1. Installation

Download BIGateway.msi from the My Account page on the support site, then run it on a computer that can be used to provide access to your data sources to start the Dundas BI Gateway Setup Wizard.

Gateway Manager installer
Gateway Manager installer

Follow the steps of the wizard. When complete, the Dundas BI Gateway Manager will be installed on the computer.

When a new version of this installation file becomes available corresponding with a newer version of Dundas BI, you can download it and run it again to upgrade your gateway manager to the new version, then use the gateway manager to update your gateway(s) as described below.

Note
If you decide to uninstall the gateway manager, you will need to first use the gateway manager to remove any existing gateways as described below in order to remove gateway files and services.

3.2. Managing gateways

On the computer where it was installed, run the Dundas BI Gateway Manager from the Start menu.

You can create a gateway for each Dundas-hosted instance of Dundas BI that you want to be able to connect to your local data sources through this computer.

Empty Gateway Manager
Empty Gateway Manager

Click the Add Gateway button to create a new gateway for a particular Dundas BI instance.

Add a gateway
Add a gateway

Enter the instance Name (for your reference), and the Dundas BI URL used to access it. For example: https://myinstance.mycompany.dundasbi.com/

You can customize the installation directory if preferred, then click Add to install the gateway files and service.

Gateway listed
Gateway listed

Once the process is complete, the new gateway is listed in the Gateway Manager along with its status, and a clickable link to the gateway's installation folder and its subfolders such as Logs in case of errors or issues. You can click to Restart the service if required for new installed drivers, for example, or click to Remove the gateway. After installing a new version of the Gateway Manager, you will also be able to click to Update the gateway to the newest version.

Next, click the link for the Config Override File to open it in a text editor, and note the GatewayId and PreSharedKey values located inside the <Setting> elements, which you will need to configure the gateway in Dundas BI.

4. On Linux

4.1. Installation

The Dundas BI Deployment wizard is used to create and manage gateways on Linux.

Follow the instructions in Installing Dundas BI on Linux for downloading and installing the Deployment wizard for your distribution of Linux. Rather than launching the wizard to create an instance, you will create a gateway as shown below.

When a new version of Dundas BI becomes available, you can download and install the new version of the Deployment wizard, then run the step to upgrade your existing gateway.

4.2. Managing gateways

Launch the Dundas BI Deployment wizard in a terminal using the --gateway option. For example:

sudo dundasbi --wizard --gateway

To create a new gateway, type the number indicated for the step Create Gateway followed by the enter key. There are also steps available to Upgrade Gateway and Remove Gateway.

Deployment wizard
Deployment wizard

A prerequisites check may run. Follow the prompts, or type y and the enter key to continue if the check passed.

You will be prompted to enter a Name for the Dundas BI instance you want to use this gateway (for your reference), followed by the Dundas BI URL used to access it.

Review gateway details
Review gateway details

These details will be displayed back to you next and you can type y followed by the enter key to confirm and create the gateway.

Gateway creation details
Gateway creation details

Once the tasks are complete, note the GatewayID and PreSharedKey values indicated in your terminal, as you will need these when configuring the gateway in Dundas BI. If you need to find them again later, they are also defined within the ConfigOverride.xml file in the App_Data folder.

Once created, your gateway's App_Data directory is located at:

/usr/share/dundas/bi/Gateways/Files/{InstanceName}/App_Data

In some cases, drivers may need to be installed in subdirectories created under this directory if indicated in links from the data sources section of Dundas BI's system requirements. There is also a Logs subdirectory with files that may record errors.

A service is also installed that needs to continue running in order to provide access to your data sources for Dundas BI. You can control or check the status of this service using the following commands (you may need to use the sudo command in front):

CommandResult
systemctl stop dundas-bi-gateway-{InstanceName}.service
Stops the Dundas BI gateway service.
systemctl start dundas-bi-gateway-{InstanceName}.service
Starts the Dundas BI gateway service.
systemctl restart dundas-bi-gateway-{InstanceName}.service
Restarts the Dundas BI gateway service.
systemctl status dundas-bi-gateway-{InstanceName}.service
Get the Dundas BI gateway service status.

5. On Docker

Like other Dundas Docker images, the gateway can be run as a Docker container using the image dundas/dundas-bi-gateway. This allows you to run on other machines besides the supported Windows and Linux environments if compatible.

The gateway is configured using environment variables set when starting the container:

Environment VariableDescription
DUNDAS_BI_EXTERNAL_APPLICATION_URL The URL to your Dundas BI instance, e.g.: https://myinstance.mycompany.dundasbi.com/
DUNDAS_BI_GATEWAY_ID A unique ID to identify this gateway. You could generate a UUID for this value using uuidgen in a terminal or online.
DUNDAS_BI_GATEWAY_PRESHARED_KEY A strong pre-shared key value matching the one you configure in your Dundas BI instance as described below to ensure only your gateway is granted access. You can generate one or find tips here.
DUNDAS_BI_AGREE_TO_TERMS_OF_GATEWAY_EULA You must accept the terms of the Dundas BI Gateway Application Licence Agreement to run the gateway. Set to true to confirm your acceptance.
DUNDAS_BI_PRINT_CONFIG_OVERRIDE (Optional) Prints configuration XML text containing the gateway ID and pre-shared key you specified, as confirmation.

You should set up the Gateway Manifest in Dundas BI as described in the following section first using the gateway ID and pre-shared key you plan to set as environment variables, and then start up your gateway container.

Here is an example for starting the container using docker run:

docker run -it \
-e DUNDAS_BI_EXTERNAL_APPLICATION_URL="https://myinstance.mycompany.dundasbi.com/" \
-e DUNDAS_BI_GATEWAY_ID="b3f999b0-5dc5-4790-bc9c-3a2e97d8701f" \
-e DUNDAS_BI_GATEWAY_PRESHARED_KEY="h9LR6yUxFpdXAserzdXjVxB4DQdNl3rTdKDj2Mxr" \
-e DUNDAS_BI_AGREE_TO_TERMS_OF_GATEWAY_EULA="true" \
dundas/dundas-bi-gateway

Important
If you are copying and pasting this command, change the gateway ID and pre-shared key first for security reasons.

6. Configure Dundas BI for your gateway

Log into Dundas BI as an administrator user and access the Admin area from the main menu on the left.

Click to expand Setup and then to navigate to Config to access Dundas BI's configuration settings.

Edit the gateway manifest
Edit the gateway manifest

Find or search for the Gateway Manifest setting (located in the Data category), and double-click it or select it and click Edit.

In the configuration dialog, click Edit value, and then enter your configuration as a JSON array like the following:

[{
    "Id": "c3c2e1f3-7962-4a38-a9d7-d0af3ea73e3b",
    "DisplayName": "Office",
    "PreSharedKey": "Ut5x8VGGPolxpylVmF5h5iVgmgDlphkJXiRUiTnf"
}]

If you have multiple gateways, you can provide multiple comma-separated objects as defined within curly braces { }. Each object should provide the following details for a gateway:

  • Id - The gateway ID provided to you earlier, from your gateway's Config Override File or from your terminal after adding the gateway on Linux.
  • DisplayName - The name used to identify this gateway when using it in a new data connector.
  • PreSharedKey - The pre-shared key value provided to you earlier along with the gateway ID.

Submit the dialog for the configuration to take effect.

7. Connect to your gateway

With the gateway created and any necessary drivers installed, after configuring it in Dundas BI, users can now use the gateway to connect to data sources in data connectors.

When creating or editing a data connector with Data Provider set to a supported data source, select the Use Gateway checkbox and then select your Gateway from the list that appears.

New data connector dialog with Use Gateway option
New data connector dialog with Use Gateway option

Now you can enter the connection details your gateway should use to access your data source.

8. Security

  • The gateway uses only outgoing connections, so your environment does not need to support incoming or inbound connections.
  • Your gateway connects to the Dundas BI URL you specified when adding it. Dundas-hosted instances use HTTPS encryption over port 443.
  • Trust is established between your Dundas BI instance and gateway through the pre-shared key used during configuration, so that your instance will only accept incoming connections from your gateway.
  • When data source connection details need to be communicated to your gateway, a pre-shared key is used with AES encryption and a SHA-512 hash function.

9. See also

Dundas Data Visualization, Inc.
400-15 Gervais Drive
Toronto, ON, Canada
M3C 1Y8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours:
Phone: 9am-6pm, ET, Mon-Fri
Email: 7am-6pm, ET, Mon-Fri