Using the Birst ODBC Driver

The Birst ODBC Driver provides integration with Open Database Connectivity (ODBC) clients such as Microsoft Excel and Tableau.

Important: One ODBC data source connects to one Birst space. If you need data from multiple existing spaces, create a new space containing all the data you need.

Installing and Configuring the ODBC Driver
Troubleshooting
Third Party Software

Prior to installing the ODBC Driver

Before installing the driver, be aware of the following prerequisites:

The ODBC Driver has both 32- and 64-bit versions and runs on Windows 7 and above.
The Windows user must have permission to install a driver on the system.
The Birst user must have access to the Birst spaces you want to access from the ODBC client.
The Birst account and the users must have OCI enabled. See Enabling the OCI Product for an Account and Users.
Custom subject areas are a Best Practice for organizing data for use by ODBC clients such as Tableau. See Creating a Custom Subject Area for OCI.
Uninstall any previous Birst ODBC drivers.

To obtain the ODBC Driver (ODBC Connector)

To obtain the ODBC Driver, create a support ticket to request a version of the ODBC driver.

The driver is available for customers with contract executed before June 1st, 2021. For customers with contract executed after May 31st, 2021, a new version of the OCI driver will be available as part of the Birst roadmap .

To install the ODBC Driver

Launch the BirstODBC.msi. Follow the Setup Wizard to:
Accept the End User License Agreement.
Select the installation directory.
Install the driver. Accept any security software prompts, if needed.
Finish and review the Release Notes.

The installer adds Windows menu items for the Birst ODBC Driver:

ODBC Administrator
Release Notes
Uninstall Birst ODBC Driver

To configure Birst as a data source

After the driver is installed, configure Birst as a data source using the ODBC Administrator. Configure one data source per Birst space.

From the Programs menu select Birst ODBC Driver - ODBC Administrator.
Under the User DNS tab click Add.
In the Create New Data Source window select the Birst ODBC Driver and click Finish.
In the Configure Birst Data Source window enter the Data Source and Login information.
- In the Data Source section name the new data source and enter a brief description.
- In the Login section enter the Birst Server URL, user name, and user password.
  Tip: If a proxy server is in use, the Server URL can contain proxy information in the following format:
  https://host;[user_name:password@]proxy_host[:proxy_port]
  The simplest example:
  
  The user name and password in the Server URL field are only required if the proxy uses basic authentication. User name and password on the server URL line cannot contain an at sign (@) or colon (:).
  
  Proxy_port defaults to 8080, so you can leave that off if it is the case.
As a Best Practice, if you set up Custom Subject Areas in Birst to use in the ODBC client, click Use Subject Areas.
Optionally, click Logging Options and choose from the list of logging levels for log messages to be recorded in the log file. The log files can be helpful for troubleshooting purposes.
- Choose a log level. By default logging is off.
  Tip: If there are issues in the future, you can come back to this screen and reset the log level. Higher levels of logging take more resources so if you don't need to troubleshoot using the logs, set it to LOG_INFO or a lower level.
- Enter a directory path for the log files. The directory must already exist. The driver will write the birst_odbc.log and birst_parsetree log files here.
  Tip: The birst_odbc file is used for troubleshooting.
- Important: Leave Log Namespace empty.
Optionally, click Store Password. If selected, you won't be prompted to login every time the driver needs access to Birst. The password is stored in clear text in the Windows Registry.
Click List Spaces. The driver connects to Birst and returns the list of spaces to which the specified user has access.
Select the space you want to use and click OK.
The Data Source Administrator lists the name of your new data source, and indicates that it is using the Birst ODBC Driver.
Click OK.

After installing and configuring the Birst ODBC Driver

If you need access to additional Birst spaces, configure another data source per space, using the same driver.

The driver configuration provides login access to a Birst space for use by ODBC clients. Use the ODBC interfaces in software programs such as Excel to set up access from the clients to a Birst space.

Troubleshooting ODBC Error Messages

You may see the following general issues with any ODBC client. These errors are generated by the client. For Tableau-specific errors see Troubleshooting Birst and Tableau.

Generic ODBC Error

Resolution: There may be limits to the amount of data, or number of tables and columns, that a client can successfully process. A general ODBC error indicates that the metadata for the space that is being connected to is too large for the client to handle, and is more often seen in Excel. To work around this define custom subject areas in Birst that limit the size of the resulting meta data. See Creating a Custom Subject Area.

Architectural Mismatch

If the ODBC client is 32 bit and the Birst ODBC Driver is 64 bit there is an “architecture mismatch” error. This is more likely with Excel, because even if your Windows 7 is 64 bit, by default MS Office installs its 32 bit version. If this happens, uninstall the Birst 64 bit driver and install the 32 bit driver instead.

Third Party Software

The Open Client Connect driver uses the following third party software:

Simba Technologies for the ODBC SDK. This product includes data access and analytics software including ODBC, JDBC, ADO.NET, ODBO, and XMLA developed by Simba technologies, Inc. (http:///www.simba.com).
OpenSSL for connecting to the Birst web services vis HTTPS o This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).