This section describes how to set up ODBC connectivity and configure DSNs on several Linux distributions: Debian-based systems, like Ubuntu, and Red Hat Linux platforms, like Red Hat Enterprise Linux (RHEL) and Fedora.

Minimum Linux Versions

Here are the minimum supported versions for Red Hat-based and Debian-based systems:

OS	Min. Version
Ubuntu	18.04
Debian	10
RHEL	8
Fedora	28
SUSE	15

Installing the Driver Dependencies

Run the following commands as root or with sudo to install the necessary dependencies:

• Debian/Ubuntu:
  

  apt-get install libc6 libstdc++6 zlib1g libgcc1

• RHEL/Fedora:
  

  yum install glibc libstdc++ zlib libgcc

Installing the Driver

You can use standard package management systems to install the driver.

On Debian-based systems, like Ubuntu, run the following command with root or sudo:

dpkg -i /path/to/driver/setup/AcumaticaODBCDriverforUnix.deb 

On systems that support the RPM package format, run the following command with root or sudo:

rpm -ivh /path/to/driver/AcumaticaODBCDriverforUnix.rpm 

Licensing the Driver

Run the following commands to license the driver. To activate a trial, omit the <key> input.

cd /opt/cdata/cdata-odbc-driver-for-acumatica/bin/
sudo ./install-license.sh <key>

Connecting through the Driver Manager

The driver manager loads the driver and passes function calls from the application to the driver. You need to register the driver with the driver manager and you define DSNs in the driver manager's configuration files.

The driver installation registers the driver with the unixODBC driver manager and creates a system DSN. The unixODBC driver manager can be used from Python and from many other applications. Your application may embed another driver manager.

Creating the DSN

See Using unixODBC to install unixODBC and configure DSNs. See Using the DataDirect Driver Manager to create a DSN to connect to OBIEE, Informatica, and SAS.

Connecting to Acumatica

In order to connect to the Acumatica data source, you must specify the following connection properties.

• Url: (Required) The base URL for the Acumatica ERP instance. For example: https://domain.acumatica.com/.
• Schema: (Optional) There are two schemas that contain different data. The default one is REST, which uses the Acumatica REST Contract-Based API, and the OData schema, which uses the Acumatica OData API. The OData schema is used to query Acumatica Generic Inquiries.
• Company: (Partially required) Set this to the name of your company or tenant. It is required if Schema is set to OData.
• EndpointVersion: (Optional) The version of the Web Services endpoint. For example: 17.200.001. This applies only to the REST schema.
• EndpointName: (Optional) The name of the Web Services endpoint. For example: Default. This applies only to the REST schema.

To find out the EndpointVersion and EndpointName for your Acumatica instance, log into Acumatica in a web browser, and then navigate to the Web Service Endpoints page. If necessary, navigate to this page by editing the web browser URL and replacing ScreenId=00000000 (the homepage) with ScreenId=SM207060. If you are redirected back to the homepage, this means your user does not have the necessary permissions to access web services. Under Endpoints properties get the Endpoint Name and Endpoint Version.

Authenticating to Acumatica

There are two authentication methods available for connecting to Acumatica data source, Basic and OAuth.

User Credentials

Set the AuthScheme to Basic and set the User and Password to your login credentials.

OAuth

OAuth requires the authenticating user to interact with Acumatica using the browser, so all OAuth flows require a custom OAuth application. Also, for all flows, set AuthScheme to OAuth. The following sections assume that you have done so.

Desktop Applications

CData provides an embedded OAuth application that simplifies OAuth desktop Authentication. Alternatively, you can create a custom OAuth application. See Creating a Custom OAuth App for information about creating custom applications and reasons for doing so.

For authentication, the only difference between the two methods is that you must set two additional connection properties when using custom OAuth applications.

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set this to the client Id in your application settings.
• OAuthClientSecret: Set this to the client secret in your application settings.
• CallbackURL: Set this to the Redirect URL in your application settings.

When you connect the driver opens the OAuth endpoint in your default browser. Log in and grant permissions to the application.

Web Applications

When connecting via a Web application, you need to create and register a custom OAuth application with Acumatica. See Creating a Custom OAuth App for more information about custom applications. You can then use the driver to acquire and manage the OAuth token values.

Get an OAuth Access Token

Set the following connection properties to obtain the OAuthAccessToken:

• OAuthClientId: Set this to the client Id in your application settings.
• OAuthClientSecret: Set this to the client secret in your application settings

Then call stored procedures to complete the OAuth exchange:

1. Call the GetOAuthAuthorizationURL stored procedure. Set the CallbackURL input to the callback URL you specified in your application settings. If necessary, set the Scope parameter to request custom permissions.

   The stored procedure returns the URL to the OAuth endpoint.

2. Open the URL, log in, and authorize the application. You are redirected back to the callback URL.
3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB. Set the Verifier input to the "code" parameter in the query string of the callback URL. If necessary, set the Scope parameter to request custom permissions.

Once you have obtained the access and refresh tokens, you can connect to data and refresh the OAuth access token either automatically or manually.

Automatic Refresh of the OAuth Access Token

To have the driver automatically refresh the OAuth access token, set the following for the first data connection:

• InitiateOAuth: Set this to REFRESH.
• OAuthClientId: Set this to the client Id in your application settings.
• OAuthClientSecret: Set this to the client secret in your application settings.
• OAuthAccessToken: Set this to the access token returned by GetOAuthAccessToken.
• OAuthRefreshToken: Set this to the refresh token returned by GetOAuthAccessToken.
• OAuthSettingsLocation: Set this to the location where the driver saves the OAuth token values, which persist across connections.

On subsequent data connections, the values for OAuthAccessToken and OAuthRefreshToken are taken from OAuthSettingsLocation.

Manual Refresh of the OAuth Access Token

The only value needed to manually refresh the OAuth access token when connecting to data is the OAuth refresh token.

Use the RefreshOAuthAccessToken stored procedure to manually refresh the OAuthAccessToken after the ExpiresIn parameter value returned by GetOAuthAccessToken has elapsed, then set the following connection properties:

• OAuthClientId: Set this to the client Id in your application settings.
• OAuthClientSecret: Set this to the client secret in your application settings.

Then call RefreshOAuthAccessToken with OAuthRefreshToken set to the OAuth refresh token returned by GetOAuthAccessToken. After retrieving the new tokens, open a new connection by setting the OAuthAccessToken property to the value returned by RefreshOAuthAccessToken.

Finally, store the OAuth refresh token so that you can use it to manually refresh the OAuth access token after it has expired.

Set the Driver Encoding

The ODBC drivers need to specify which encoding to use with the ODBC Driver Manager. By default, the CData ODBC Drivers for Unix are configured to use UTF-16 which is compatible with unixODBC, but other Driver Managers may require alternative encoding.

Alternatively, if you are using the ODBC driver from an application that uses the ANSI ODBC API it may be necessary to set the ANSI code page. For example, to import Japanese characters in an ANSI application, you can specify the code page in the config file '/opt/cdata/cdata-odbc-driver-for-acumatica/lib/cdata.odbc.acumatica.ini':

[Driver]
AnsiCodePage = 932