Installing database drivers for Information Designer

To be able to access data from a JDBC-compliant data source with Information Services, you must install the appropriate JDBC driver on the computer that is running Spotfire Server.

About this task

To install drivers on the server, you can either install the drivers manually by logging in to the computer running Spotfire Server, or you can deploy a package (.spk) with the driver and install it to the Spotfire Server in the server administration pages.

Note: In a clustered server deployment, you must install the driver on all computers that run Spotfire Server in the cluster.

Installing JDBC drivers manually

If you have administrator access to the computer running the Spotfire Server, you can log in to the computer and install JDBC drivers manually.

Procedure

Download the database driver.
Place the driver in the following directory: <installation dir>/tomcat/custom-ext-informationservices.

Note: This is the recommended directory for most JDBC drivers. There might be some JDBC drivers that you must install to a different directory. For information on some known exceptions, see Spotfire JDBC Data Access Connectivity Details on the Community.

Note: If you are using Oracle as the Spotfire database and you want to access data with information services (regardless of whether you want to access Oracle data), you must add the same Oracle jar file in both directories <installation dir>/tomcat/custom-ext and <installation dir>/tomcat/custom-ext-informationservices.
Restart the Information Services process.

Installing JDBC drivers in the server administration pages

About this task

To install JDBC drivers through the server administration pages, you must first create a Spotfire package (.spk) with the JDBC driver, and then deploy it to the Spotfire Server.

Before you begin

To install and use JDBC drivers with this method, Information Services must be configured to run as an external process (this is the default), and not in-process with the main Spotfire Server process.

Building a Spotfire package with a JDBC driver

Before you begin

Download the Spotfire Package Builder console from the Spotfire Developer software. See Downloading Spotfire Developer.

Procedure

Download the database driver.
Create a new package description file (.pkdesc). See Package Description file.

Tip: You can use the example below as a starting point.
Set the following attributes in the PackageDescription element:
- IntendedClient="InformationServices"
- Type="JdbcDriver"
- Capability="INFORMATION_SERVICES"
Set the following attributes for the File element:
- SourceFile="[driver-name].jar"
- TargetFilename="[driver-name].jar"
- Type="File"
Tip: For all packages, remember to set values for Name, Version, and a unique SeriesId (a GUID). To learn more about the parameters in a package description, see Package Description file.
Save your changes.
To build your package file, open a command-line interface, and run the following command, where /pkdesc is the path to your .pkdesc file, /basefolder is the path to the directory where your .jar file is located, and /target is the name of the target .spk file:
```
Spotfire.Dxp.PackageBuilder-Console.exe /targettype:package /pkdesc:"my-driver.pkdesc" /basefolder:"C:\jar-directory\" /target:"my-package.spk"
```

Example package description

<?xml version="1.0" encoding="utf-8"?>
<PackageDescription 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
SchemaVersion="2.0" 
Name="driver-name" 
Version="1.0.0.0" 
SeriesId="67c46837-64f0-4a4f-bd32-c7496dc7490a" 
IntendedClient="InformationServices" 
Type="JdbcDriver" 
Capability="INFORMATION_SERVICES">  
<File SourceFile="driver-name.jar" TargetFilename="driver-name.jar" Type="File"/>
</PackageDescription>

Deploying your JDBC driver in the server administration pages

When you have created your Spotfire package, you must deploy it to a deployment area, and then fetch and update the new drivers for each Information Services instance.

Procedure

In a web browser, go to the server administration pages and log in as an administrator.
On the Deployments & Packages page, select the deployment area that you want to deploy your driver to.
Click Add packages.
In the Add packages dialog, select your driver .spk file, and then click Upload.
In the list of packages, review your changes, and then click Save area.
To update your Information Services instances with the new or updated drivers, go to the Nodes & Services page, and in the list, click to expand the server of interest in the list.
In the expanded list, click Information Services.
In the panel on the right, click Update drivers.

Tip: The Update drivers button is only shown when there are changes to the JDBC driver packages in the deployment area selected for the Information Services instance. To change the deployment area, click Edit.
In the Update drivers dialog, click Update.
The drivers are updated on the Spotfire Server, and the Information Services instance restarts.

Results

The JDBC drivers in the selected deployment area are installed to <installation-dir>\nm\services\InformationServices\is-drivers on the computer running the Spotfire Server. Any drivers that were removed or changed in the deployment area are also removed or updated.

Troubleshooting

Validation of data source template error: Driver not found

When you add or edit a data source template in the Spotfire Server configuration tool, if the corresponding JDBC driver is installed to the is-drivers directory (if you installed it in the server administration pages), the tool cannot find the driver to validate the template. An error message is shown stating that the driver cannot be found, but you can ignore the message and save the configuration.

Drivers installed to multiple locations

If the same driver class is installed in both directories (<installation dir>/tomcat/custom-ext-informationservices and <installation-dir>\nm\services\InformationServices\is-drivers) on the same Spotfire Server, the driver in the is-drivers directory is prioritized.

Important: Upgrading to Spotfire version 12.1 and later

In versions 12.1 and later, Information Services runs in its own subprocess, and uses the new default extensions directory <installation dir>/tomcat/custom-ext-informationservices for JDBC drivers. When you upgrade from an earlier version, all your JDBC drivers remain in the previous default directory, <installation dir>/tomcat/custom-ext, and the configuration property information-services.external-process.use-legacy-extensions is set to true. This way, Information Services can also use drivers from the custom-ext folder.

After upgrading, it is recommended that you manually move Information Services-related JDBC drivers to the custom-ext-informationservices directory. After you have moved your drivers, set the configuration property information-services.external-process.use-legacy-extensions to false.

What to do next

To connect to an external data source, you must also add and/or enable a data source template that matches the database and the specific database driver.

You can add and enable data source templates in two different ways:

Note: The database connection URL, used by the server to connect to the database, may differ for different database drivers; see Database drivers and database connection URLs.