xODBC System Requirements for Windows

This article describes how to install the Xactly xODBC client driver on Microsoft Windows-based computers. After we get the driver installed, we’ll also have to add and configure a Data Source Name (DSN) to establish a connection with the Connect data service.

Xactly has tested the xODBC driver on Windows 7  Professional (32-bit and 64-bit edition), Windows 10, and Windows Server 2012. The xODBC installer installs both the 32-bit and 64-bit versions of the xODBC driver on 64-bit systems. On 32-bit Windows 7, only the 32-bit version of the driver is installed.

The xODBC driver communicates with Xactly Connect servers using HTTPS.

AnchorInstall the xODBC Client Driver

There are a few steps:

  1. Download the xODBC installer application. Contact Xactly Customer Support to obtain the xODBC driver installer for Windows (delta-xodbc-driver-win-x.x.x-RELEASE.exe).
  2. Double click delta-xodbc-driver-win-x.x.x-RELEASE.exe.
  3. When the Xactly XODBC Driver Setup dialog appears, click Next.screen-shot-2016-09-09-at-1-42-01-pm
  4. Accept the license agreement. The installation application begins installing the xODBC driver software on your computer.
  5. Click Close after the installation completes.

NOTE: On Windows 64-bit systems, the installer installs the 64-bit version of the driver in C:\Windows\SysWOW64\xodbc directory. The 32-bit version of the driver is installed in the C:\Windows\System32\xodbc directory.

AnchorConfigure a Data Source Name (DSN)

Next, you need to add a data source name (DSN) for the xODBC driver before you can create a connection to the Xactly Connect data service. DSNs include information about the Xactly server, along with the user credentials to use. You can do this using the Microsoft ODBC Data Source Administrator.

IMPORTANT: Incent users need Xactly Connect privileges to access Xactly Connect data services.

The following steps describe how to add a DSN using the Microsoft Windows 7 Professional 64-bit system. (The steps are similar for 32-bit versions of Windows 7, but are not enumerated in detail here. DSN configuration steps for other version of Windows may differ slightly).

    1. Launch the Windows Control Panel using the Start menu, and click the System and Security link.
      screen-shot-2016-09-09-at-1-42-12-pm
    2. Click the Administrative Tools link. The list of administrative tools appears.
    3. Double-click Data Sources (ODBC). The ODBC Data Source Administrator launches.Click the System DSN tab. The ODBC Data Source Administrator creates 64-bit ODBC driver connections, and is a shortcut to the following command:
      C:\Windows\system32\odbcad32.exe

      To create connections for 32-bit drivers instead, use the following command:

      C:\Windows\SysWOW64\odbcad32.exe

      The choice to create either a 32-bit or 64-bit DSN is determined by the ODBC client application you intend to use. Some Windows ODBC clients can only use DSNs created for 32-bit drivers; other applications use 64-bit DSNs. Some applications can use either 32-bit or 64-bit ODBC driver connections.

      NOTE: Windows also offers the option to create User DSNs and File DSNs. User DSNs are visible only to the Windows user account that created the DSN. System DSNs, in contrast, are visible to any user account with access to the Windows machine. Note, however, that the procedure to create a User DSN is the same. Finally, File DSNs are not relevant to the Xactly xODBC driver.

    4. Click Add and select XODBC64 in the dialog that appears. Click Finish. The XODBC DSN Configuration dialog appears.Complete the fields in the Connection tab:

      Field Description
      DSN Name (Required) The name of the data source. ODBC clients use this name to establish a connection to a particular DSN.
      Server Name (Required) The Connect server environment/pod to use.

      API Gateway URLs (xODBC 1.1.7+)

      For xODBC 1.1.7 and later, Xactly has enabled an API Gateway for customer use through Connect’s REST APIs and drivers.

      Xactly Customer Support must provide you “clientId” and “consumer” credentials before you can use the API Gateway URLs.  These gateway credentials will be shared within your organization and add an additional layer of security for accessing the Connect API platform. Valid Incent usernames and passwords with Xactly Connect roles are still required.

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

      api-sandbox.xactlycorp.com – Sandbox

      api.xactlycorp.com – Routes to your production instance

      Legacy URLs (xODBC versions preceding 1.1.7)

      Use one of the following legacy URLs with driver versions prior to 1.1.7. These URLs do not route through Connect’s  API Gateway and are accessible using valid Incent credentials.

      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.xacdtlycorp.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
      Server Port (Optional) The HTTPS port. The default is port 443, which is the standard used by Xactly servers.

      NOTE: Xactly does not allow connections over HTTP.
      Username (Optional) An Incent username that has been granted Xactly Connect privileges.

      This user has read access to all Incent data exposed through the Connect data service. This user can also execute any xSQL or xCL statement after connecting to Xactly Connect.
      Password (Optional) The password associated with the username.
      ClientId (Required) Introduced in xODBC 1.1.7. The API Gateway client id assigned to your organization (supplied by Xactly Customer Support). Client ids are unique to an organization. The API Gateway  uses ClientId to track which parts of the Connect API Platform your organization may access.
      Consumer (Required) Introduced in xODBC 1.1.7. The API Gateway consumer name assigned to your organization (supplied by Xactly Customer Support).
      QueryBatchSize (Optional) Introduced in xODBC 1.1.7. For SELECT statements, controls the number of rows returned by the Connect server to the caller in a given HTTP response. Default is 200. Maximum size is 1000.

      Example: If a SELECT statement result set has 1023 rows, Connect will return the result set in 6 batches (200, 200, 200, 200, 200, 23).
      EnableTLS1.1 (Optional) Introduced in xODBC 1.1.7. Controls whether the driver uses TLS 1.1 or 1.2 when authenticating to the Connect service. Default is false.  Some versions of Windows may experience intermittent Connect authentication errors when using TLS 1.2. This parameter allows these system to instead use TLS 1.1.
      Protocol Version (Required) The set/version of Xactly Connect REST API that the xODBC driver should use to interact with the Connect server.

      NOTE: Currently only one option is available: 1. Additional versions might be available in the future.
    5. Click Test Connection to check whether the DSN configuration settings are valid.Verify that you are able to connect successfully. If the connection fails, a dialog appears with an explanation. For example, “Authentication failed” indicates an invalid username and/or password.
    6. Click Save. Your new DSN should appear in the Microsoft ODBC Data Source Administrator, in the list of System Data Sources:screen-shot-2016-09-09-at-1-42-50-pm
      The system DSN is now ready to use in an ODBC-compliant client application.Next, you can specify additional settings in the Proxy, Configuration, and Logging tabs. These are optional and only necessary in specific situations.
    7. (Optional) If your company requires that HTTPS connections go through a proxy server, click the Proxy tab to configure the proxy server information.You can specify the following proxy settings:
      Setting Name Description
      Proxy Type (Optional) The proxy type, from among the following values: None, SOCKS4, SOCKS5, and HTTP.
      Proxy Hostname (Optional) The local proxy server that routes HTTPS requests to the Internet.
      Proxy Port (Optional) The port used to communicate with the proxy server.

      NOTE: Your network administrator can assist you with choosing the appropriate proxy settings.

    8. (Optional) To specify the encoding for single-byte strings, click the Configuration tab. The tab has only one setting:
      Setting Name Description
      Use UTF-8 for single-byte strings (Required) Specifies whether ANSI ODBC calls should return UTF-8 encoded strings (checked) or ANSI strings (unchecked). Xactly strongly recommends having UTF-8 enabled (the default), to ensure that there is no data loss when handling non-ASCII characters.
    9. (Optional) To specify how the DSN logs output to the local machine, click the Logging tab.By default, logging is disabled. Logging is principally used to help Xactly Support in troubleshooting xODBC driver issues.

screen-shot-2016-09-09-at-1-43-14-pm
The fields in the Logging tab are:

Setting Name Description
Enable logging Turn on logging.
Logging level The level of logging performed, from least to most detailed: ERROR, WARN, INFO, TRACE.

NOTE: TRACE logs can grow very large; use only when troubleshooting issues with Xactly Support.
Logfile path The local file system path and filename to which the logs are to be written. If left blank, the default log file location is c:\xodbc.log.
Buffer writes to log file Improves the performance of debug logging by batching log records in memory and then writing them to disk periodically. If buffering is enabled, the log file might not contain the most recent log messages (because buffered messages might not be written to the file). Therefore, when working with Xactly Support to debug logs, it is strongly recommended that you set this option to false.

 

AnchorModify or Delete a DSN

To change the configuration of a DSN, click Configure in the Microsoft ODBC Data Source Administrator, modifying the settings, and click Save.

To delete a DSN from the system, select the DSN in the list and click the Remove button.

screen-shot-2016-09-09-at-1-43-22-pm

AnchorUninstall the xODBC Driver

To remove the xODBC client driver from your Windows system:

  1. Launch the Windows Control Panel using the Start menu, and click the Programs > Uninstall a program link.
    screen-shot-2016-09-09-at-1-43-30-pm
    The list of installed applications appears.
  2. Find Xactly XODBC Driver in the list, right-click the entry, and select Uninstall in the dialog that appears. The Xactly XODBC Driver Uninstall utility launches.
    screen-shot-2016-09-09-at-1-43-37-pm
  3. Click Uninstall to remove the xODBC driver software.

NOTE: Uninstalling the xODBC driver does not delete any related DSN entries from the Microsoft ODBC Data Source Administrator. You will need to remove any unneeded DSN entries manually.

Troubleshoot the ODBC DSN Connection

If you are unable to connect to Xactly Connect servers using the DSN configured in the Windows ODBC Data Source Administrator:

  • Verify that the Xactly xODBC driver can write logs to the filesystem.Be sure to enable logging in your DSN configuration. By default, the log file is written to C:\unixodbc.log (if logging is enabled). View the log output in a text editor to help troubleshoot connection issues.
  • Ensure the DSN Server Name setting is correct. In most cases, it should be connect-i1.xactlycorp.com.If the server name setting is incorrect, the error log will show a message similar to:2015-10-14 16:20:45.397 [ERROR] Detailed libcurl messaged: Couldn't resolve host 'bogus.xactlycorp.com'
  • Double-check that the DSN Server Port is 443 or blank.Using the correct server name with a port other than 443 will cause the session to hang. Note that the xODBC log might not show any related messages when an invalid port is used.
  • Check whether you configured an incorrect username or password.In this case, the log file message will be similar to:2015-10-14 16:28:31.802 [ERROR] Authentication failed.
  • If you cannot establish a connection, a corporate firewall might be blocking access. Contact your IT department to determine if a proxy server is needed to access external web servers using SSL on port 443. The xODBC driver configuration parameters allow for proxy servers.