Install the Connect JDBC Driver (beta release)

The Xactly Connect data service will soon support JDBC. Xactly is creating a JDBC driver that developers can use in Java programs and third party SQL editors, ETL, and BI applications. Xactly will soon begin a limited beta program to give customers early access to a pre-release version of the JDBC driver. Contact Xactly Customer Support for more information regarding participation in the beta program.

Configuration Summary

The JDBC driver comes in two flavors:

  • The driver xjdbc-version-jar-with-dependencies.jar contains both the Xactly JDBC driver classes, and open source third party libraries that the driver requires.  This is the easiest version of the driver to use in JDBC client GUI applications.
  • The driver xjdbc-version.jar contains only the Xactly JDBC driver classes; the user must install all external third-party libraries to use the JDBC driver. These additional dependencies include:

Xactly Connect Servers

Be aware, Xactly is currently transitioning Connect from legacy URLs to new “API Gateway” URLs. The JDBC driver can access either set of URLs. More information here: API Gateway Updates from Product Management

Old & New Server List and Description
Legacy URLs Xactly will disable the legacy URLs in Spring 2017.  All users will need to transition to the API Gateway URLs. Until then, users may authenticate using the legacy URLs (no API Gateway clientId or consumer credentials required). The servers your account has access to depend on the contract negotiated between your company and Xactly.

connect-i1.xactlycorp.com – Implementation/Development Pod

connect-sb.xactlycorp.com – Sandbox

connect-s1.xactlycorp.com – Secure1 Production

connect-s2.xactlycorp.com – Secure2 Production

connect-s4.xactlycorp.com – Secure4 Production
API Gateway URLs Xactly has enabled the API Gateway for customer use through Connect’s REST APIs. Connect’s ODBC driver will support the API Gateway in late February 2017. The JDBC driver supports both legacy and API Gateway URLs.

Xactly Customer Support must provide you “clientId” and “consumer” credentials before you can use the API Gateway URLs. These credentials will be shared within your organization. Incent usernames and passwords are still required and should be unique to each developer/user.

api-implement.xactlycorp.com – Implementation/Development Pod

api-sandbox.xactlycorp.com – Sandox

api.xactlycorp.com – Routes to your production instance

 

Configuring a JDBC Connection

As with all JDBC drivers, the Xactly JDBC driver has three primary ways of establishing a connection:

  1. Using the Driver class with a connection string (most common in third party applications)
  2. A DataSource with various connection properties
  3. ConnectionPoolDataSource with connection properties.

These usage options are described below.

Usage Type 1: Connecting Through the Driver Class

The following picture shows an example JDBC driver connection to Xactly’s new API Gateway configured in the RazorSQL client. RazorSQL is a third party SQL editor available here: http://razorsql.com/.  The application is available for Mac and Windows and will let you issue xSQL queries and xCL commands using JDBC against the Xactly Connect data service.

Most third-party, JDBC client applications will have a similar configuration screen for defining a JDBC “connection” to a particular database. The Xactly Connect  data service acts as the “database” (though it is not one in the traditional RDBMS sense). Xactly Connect is a RESTful web service that allows JDBC and ODBC connections from Xactly’s drivers.

Screen Shot 2017-01-23 at 6.21.38 PM

 

The connection example shows several key pieces of information that are described in this section.

  • Driver Location – Any client that uses the JDBC must know the location of the Xactly JDBC jar file on you filesystem.
  • Driver Class – The xJDBC driver class name is com.xactly.connect.jdbc.Driver.  Although the driver supports the JDBC4 auto-discovery mechanism, it can also be loaded via the older mechanism:

Class.forName("com.xactly.connect.jdbc.Driver");
Connection conn = DriverManager.getConnection("jdbc:xactly://...");

  • Login/User Name – an Incent user account  with privileges to use the Connect data service.
  • Password
  • JDBC URL – URLs can point either to the new the API Gateway URLs or legacy Connect URLs. Legacy Connect URLs will be disabled in Spring 2017. Contact Xactly Customer Support to obtain information and credentials necessary to use the API Gateway.

The legacy JDBC connection URL takes the form:

“jdbc:xactly://servername[:port][?param1=value[&param2=value[&...]]]“

The new Xactly API Gateway form is:

“jdbc:xactly://servername[:port]/api[?param1=value[&param2=value[&...]]]“

Notice the “/api” path.  If the “/api” path is given then the “clientId” and “consumer” query parameters must be included to authenticate via the API Gateway, otherwise the connection will not be successful. Xactly Customer Support must provide your organization a shared set of API credentials , the “clientId” and “consumer”, before you can use the API Gateway URLs. In addition to the aforementioned parameters, authentication requires a valid Incent username and password.

The following table lists all available xJDBC parameters. These can be submitted as parameters in the URL string. Here is an example connection string to the API Gateway that instructs the driver to verify the server’s SSL certificate: “jdbc:xactly://api-implement.xactlycorp.com:443/api?sslVerifyServer=true&clientId=you_need_one&consumer=you_need_this_too”

Parameter Description
 user =username

(Required) Specifies the Incent username for authentication to the Connect service.  Typically, JDBC applications will have another mechanism that doesn’t require the username to be specified in the connection URL, but this is not always present.
 password =password

(Required) Specifies the password for authentication. Typically, JDBC applications will have another mechanism that doesn’t require the password to be specified in the connection URL, but this is not always present.
 useSSL =true|false

(Optional) Tells the driver whether to use HTTP or HTTPS (i.e. HTTP over SSL/TLS) in connecting to the Xactly Connect service.  The default is false, but is automatically set to true when port 443 is given in the connection URL. False is available for Xactly’s internal testing purposes. only. All customer connections to Xactly’s production servers must use SSL over port 443.
 sslVerifyServer =true|false

(Optional) If HTTPS is used, this property will tell the driver whether or not to verify the server’s SSL certificate.  Almost always, if useSSL is true then sslVerifyServer should also be true. Default is false.
 proxyType =socks4|socks5|http

(Optional) If the xJDBC driver should connect through a proxy, this specifies the type of proxy to connect through.  If this property is set then the proxyHost property is also required.  The proxyPort is optional in these cases; a default value will be chosen based on the proxy type.
 proxyHost =hostname

(Optional) This is the hostname of the proxy server to connect through.  Required if proxyType is specified.
 proxyPort =port

(Optional) This is the proxy server port number.  This property is optional when proxyType is specified; a default will be chosen based on the type of proxy specified.  For HTTP proxies, port 3128 is the default.  For SOCKS4/5 proxies, port 1080 is the default.
 clientId  =xactly-api-gateway-client-identifier 

(Optional) Specifies the client identifier which will be used while communicating with the API Gateway URI.  If the JDBC URI has been set to the API Gateway then this value is required and must become part of the URI when the JDBC driver communicates with the API Gateway.

Xactly Customer Support can provide a clientId and consumer name for use across your organization and is required when using the API Gateway URLs.

The default value of this property is null.
 consumer  =xactly-api-gateway-consumer-name

(Optional) This optional property specifies the API Gateway consumer name.  If the JDBC URI has been set to the API Gateway then this value is required and must become part of the URI when the JDBC driver communicates with the API Gateway.

Xactly Customer Support can provide a clienti_d and consumer name for use across your organization and is required when using the API Gateway URLs.

The default value of this property is null.

 

Usage Type 2: DataSource Configuration

The JDBC data-source class name is com.xactly.connect.jdbc.XactlyDataSource. Data sources expose configuration through JavaBeans properties, allowing them to be easily configured in a container-based platform with JNDI. (JavaBeans expose their properties via getters and setters that follow specific naming conventions, so that applications can discover them through Java reflection.)

The XactlyDataSource class exposes all of the above configuration settings as JavaBeans properties.

In many application-server settings, the Driver implementation will be used rather than the DataSource implementation; in those cases, the details in the previous section can be used.
If the DataSource is to be used, the configuration might look something like this (e.g. for Spring):

<bean id=”dataSource” class=”com.xactly.connect.jdbc.XactlyDataSource” destroy-method=”close”>
<property name=”serverName” value=”bogus.xactlycorp.com” />
<property name=”user” value=”user@company.com” />
<property name=”password” value=”some_secret_password” />
<property name=”useSSL” value=”true” />
<property name=”sslVerifyServer” value=”true” />
</bean>
This corresponds to the driver connection URL “jdbc:xactly://devdelta01?user=hsawhney@xactlycorp.com&password=demoUser1&useSSL=true&sslVerifyServer=false”

 

Usage Type 3: ConnectionPoolDataSource Configuration

The JDBC connection-pool data-source class name is com.xactly.connect.jdbc.XactlyConnectionPoolDataSource.  Connection-pool data sources also expose their configuration through JavaBeans properties, and as with the XactlyDataSource class, all of the above configuration properties are also available on the XactlyConnectionPoolDataSource.

The connection-pool data source is not meant to be used directly as a data source.  Rather, it is used with a connection pool implementation (typically provided by the application-server or container framework) to provide more efficient access to database connections.

As with the DataSource, app-server / container connection-pooling configuration will usually use the JDBC Driver rather than the ConnectionPoolDataSource.  Connection-pool implementations often provide data-source wrappers as well as connection-pool support.