Configuration

The QuickBooks Online Java SDK allows you to configure app settings such as minor version, number of retries, and logging. As installed, the SDK is configured with default values as listed in the table below. Override default settings as follows:

Note

Note

While overriding configs at the code level, care should be taken for multi-threaded applications to make sure the config is updated on each thread. If this is not done per thread, then the default configuration will be applied.

Features you can configure:

General configuration file structure can be found here.

Default values

The following table lists the default values configured in the Java SDK:

FEATURE CONFIGURATION FILE TAG DEFAULT VALUE
Base URL <baseUrl qbo="url"/> https://quickbooks.api.intui t.com/v3/company/
Serialization and compression
 <message>
Request
json
gzip
Retries <retry>
Fixed Retry
count: 3
interval: 30
Timeout <timeout> connectionTimeout: 0 (or no value) implies no timeout is set. requestTimeout: 0 or no value) implies no timeout is set.
TLS <tls>
Version
version: TLSv1.2
Minor version <minorVersion>
Latest minor version
updated with each release
Configuration Basics
Configuration file level

The SDK allows you to define custom, local app settings by creating a intuit-config.xml file. Then, when your app makes QuickBooks Online API calls to access QuickBooks Online data, the SDK by default checks for configuration settings in the configuration file before using its defaults.

To configure app settings at the configuration file level, override the default for a feature by editing the appropriate section of the configuration file as described on this page. To see the configuration file with the sections you can edit, click here.

Code level

To configure app settings at the code level, first build the service context and then override the feature setting as described on this page.

Base URL

A base URL defines the work environment accessed for REST API services. Supported work environments include:

WORK ENVIRONMENT OAUTH AUTHORIZATION KEYS QUICKBOOKS COMPANY BASE URL
Development App’s development keys Your sandbox data. For more information about sandboxes, click here. https://sandbox-quickbooks.api.intuit.com/v3/company/
Production App’s production keys Your user’s company data https://quickbooks.api.intuit.com/v3/company/

The default configuration accesses the QuickBooks Online production environment for REST API services. To test your code in the development environment using your QuickBooks Online sandbox, you can either create a configuration file setting or explicitly set the Base URL in Config object. For more information about sandboxes, click here.

Configuration file setting

A base URL defines the work environment in which the REST services are running. By default, the SDK uses production URL for the work environment. The SDK allows you to set the base URL for non-production environments. Include the following code in the configuration file and set appropriate values:

1
2
3
4
5
<intuit-config>
   <baseURL>
      <qbo>https://quickbooks.api.intuit.com/v3/company</qbo>
   </baseURL>
</intuit-config>
Code-level setting

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

The information required for authorization is passed using a Context object. An instance of the Context can be initialized by creating an OAuth2Authorizer object. In this type of authorization, the OAuth2Authorizer object uses an OAuth token to authorize and connect an app to the QuickBooks company. The following example creates the OAuth object and context, then creates the DataService object and makes a QuickBooks Online API call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Create OAuth object
OAuth2Authorizer oauth = new OAuth2Authorizer("accessToken"); //set access token obtained from BearerTokenResponse

// Create context
Context context = new Context(oauth, ServiceType.QBO, "realmId"); //set realm id

// Create dataservice
DataService service = new DataService(context);

// Make the API call
String sql = "select * from companyinfo";
QueryResult queryResult = service.executeQuery(sql);

Then, override the base URL setting as follows to override QuickBooks Online and Platform service base URLs respectively:

1
Config.setProperty(Config.BASE_URL_QBO,"");
Minor version

QuickBooks Online data services support minor versions in order to provide a way for you to access incremental changes without breaking existing apps. The SDK comes preconfigured to use the latest minor version. In order to take advantage of features in other versions, you can specify the minor version in the service context. Check release notes for current default value. Click here for more details about minor versions.

Code-level setting

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

The information required for authorization is passed using a Context object. An instance of the Context can be initialized by creating an OAuth2Authorizer object. In this type of authorization, the OAuth2Authorizer object uses an OAuth token to authorize and connect an app to the QuickBooks company. The following example creates the OAuth object and context, then creates the DataService object and makes a QuickBooks Online API call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Create OAuth object
OAuth2Authorizer oauth = new OAuth2Authorizer("accessToken"); //set access token obtained from BearerTokenResponse

// Create context
Context context = new Context(oauth, ServiceType.QBO, "realmId"); //set realm id

// override minor version
context.setMinorVersion("19");

// Create dataservice
DataService service = new DataService(context);

// Make the API call
String sql = "select * from companyinfo";
QueryResult queryResult = service.executeQuery(sql);
Serialization and compression formats

The SDK supports XML and JSON serialization for QuickBooks OnlineAPI request and response payloads. It also supports compression of request and response data to Gzip and Deflate formats. You must use the same serialization format for both request and response payloads. For more information on how to configure serialization and compression formats, click here.

Configuration file settings

Include the following code to set the serialization and compression formats of requests and responses:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<intuit-config>
   <message>
      <request>
         <compression>gzip</compression>
         <serialization>xml</serialization>
      </request>
      <response>
         <compression>gzip</compression>
         <serialization>xml</serialization>
      </response>
   </message>
</intuit-config>
Code-level settings

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

The information required for authorization is passed using a Context object. An instance of the Context can be initialized by creating an OAuth2Authorizer object. In this type of authorization, the OAuth2Authorizer object uses an OAuth token to authorize and connect an app to the QuickBooks company. The following example creates the OAuth object and context, then creates the DataService object and makes a QuickBooks Online API call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Create OAuth object
OAuth2Authorizer oauth = new OAuth2Authorizer("accessToken"); //set access token obtained from BearerTokenResponse

// Create context
Context context = new Context(oauth, ServiceType.QBO, "realmId"); //set realm id

// Create dataservice
DataService service = new DataService(context);

// Make the API call
String sql = "select * from companyinfo";
QueryResult queryResult = service.executeQuery(sql);

Then, override the request and response formats, as follows.

Serialization

Include the following code to serialize the request and response messages in XML format:

1
2
Config.setProperty(Config.SERIALIZATION_REQUEST_FORMAT,"xml");
Config.setProperty(Config.SERIALIZATION_RESPONSE_FORMAT,"xml");

Similarly, you can set the serialization to JSON.

Data compression

Include the following code to compress request and response code, respectively, data using Gzip format:

1
2
Config.setProperty(Config.COMPRESSION_REQUEST_FORMAT, "gzip");
Config.setProperty(Config.COMPRESSION_RESPONSE_FORMAT, "gzip");

Similarly, you can set data compression of requests to Deflateor leave it blank. When the compression value is left blank, the SDK leaves data uncompressed.

Retry policies

Retry policies enable your app to handle transient errors. For detailed information on configuring retry policies, click here.

Configuration file setting
Fixed retry policy

Include the following code to set fixed retry attempts:

1
2
3
4
5
6
7
8
9
<intuit-config>
   <retry>
   <mode>fixed</mode>
   <fixed>
      <count>3</count>
      <interval>30</interval>
   </fixed>
   </retry>
</intuit-config>
Incremental retry policy

Include the following code to set incremental retry attempts for a specified number of times:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<intuit-config>
   <retry>
      <mode>incremental</mode>
      <incremental>
         <count>3</count>
         <interval>30</interval>
         <increment>5</increment>
      </incremental>
   </retry>
</intuit-config>
Exponential retry policy

Include the following code to set randomized exponential retry attempts for a specified number of times:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<intuit-config>
   <retry>
      <mode>exponential</mode>
      <exponential>
         <count>3</count>
         <minBackoff>5</minBackoff>
         <maxBackoff>100</maxBackoff>
         <deltaBackoff>10</deltaBackoff>
      </exponential>
   </retry>
</intuit-config>
Code-level settings

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

The information required for authorization is passed using a Context object. An instance of the Context can be initialized by creating an OAuth2Authorizer object. In this type of authorization, the OAuth2Authorizer object uses an OAuth token to authorize and connect an app to the QuickBooks company. The following example creates the OAuth object and context, then creates the DataService object and makes a QuickBooks Online API call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Create OAuth object
OAuth2Authorizer oauth = new OAuth2Authorizer("accessToken"); //set access token obtained from BearerTokenResponse

// Create context
Context context = new Context(oauth, ServiceType.QBO, "realmId"); //set realm id

// Create dataservice
DataService service = new DataService(context);

// Make the API call
String sql = "select * from companyinfo";
QueryResult queryResult = service.executeQuery(sql);

Then, override the request and response formats, as follows. The Config class has the IntuitRetryPolicy constructors required to override the configuration file settings. The parameters of the IntuitRetryPolicy constructor determine the number and frequency of retries.

Fixed retry policy

Include the following code to set a fixed retry:

1
2
Config.setProperty(Config.RETRY_MODE, "fixed");
Config.setProperty(Config.RETRY_FIXED_COUNT, "5");
Incremental retry policy

Include the following code to set an incremental retry. Specify the retry count and an incremental TimeSpan:

1
2
3
4
Config.setProperty(Config.RETRY_MODE, "incremental");
Config.setProperty(Config.RETRY_INCREMENTAL_COUNT, "5");
Config.setProperty(Config.RETRY_INCREMENTAL_INTERVAL, "20");
Config.setProperty(Config.RETRY_INCREMENTAL_INCREMENT, "15");
Exponential retry policy

Include the following code to set an exponential retry. Specify the retry count and a randomized exponential Backoff:

1
2
3
4
5
Config.setProperty(Config.RETRY_MODE, "exponential");
Config.setProperty(Config.RETRY_EXPONENTIAL_COUNT, "10");
Config.setProperty(Config.RETRY_EXPONENTIAL_MIN_BACKOFF, "30");
Config.setProperty(Config.RETRY_EXPONENTIAL_MAX_BACKOFF, "200");
Config.setProperty(Config.RETRY_EXPONENTIAL_DELTA_BACKOFF, "15");
Timeout
Configuration file setting

Specify the connection and request timeout for QuickBooks OnlineData Services:

1
2
3
4
<timeout>
   <connectionTimeout></connectionTimeout>
   <requestTimeout></requestTimeout>
</timeout>
Code-level settings

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

The information required for authorization is passed using a Context object. An instance of the Context can be initialized by creating an OAuth2Authorizer object. In this type of authorization, the OAuth2Authorizer object uses an OAuth token to authorize and connect an app to the QuickBooks company. The following example creates the OAuth object and context, then creates the DataService object and makes a QuickBooks Online API call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Create OAuth object
OAuth2Authorizer oauth = new OAuth2Authorizer("accessToken"); //set access token obtained from BearerTokenResponse

// Create context
Context context = new Context(oauth, ServiceType.QBO, "realmId"); //set realm id

// Create dataservice
DataService service = new DataService(context);

// Make the API call
String sql = "select * from companyinfo";
QueryResult queryResult = service.executeQuery(sql);

Then, override the request and response formats, as follows.

Connection timeout

Include the following code to configure the connection timeout in ms for QuickBooks OnlineData Services:

1
Config.setProperty("timeout.connectionTimeout", "5000");
Request timeout

Include the following code to configure the request timeout in ms for QuickBooks Online Data Services:

1
Config.setProperty("timeout.requestTimeout", "3000");
Configuration file structure

The following shows the basic structure of the configuration file, with the sections you can add or edit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
<?xml version="1.0" encoding="ISO-8859-1" ?>
<intuit-config>
   <baseURL>
      <qbo>https://quickbooks.api.intuit.com/v3/company/</qbo>
      <platformService>https://appcenter.intuit.com/db</platformService>
      <entitlementService>https://quickbooks.api.intuit.com/manage</entitlementService>
   </baseURL>

   <tls>
    <version>TLSv1.2</version>
  </tls>

   <retry>
      <mode>fixed</mode>
      <fixed>
         <count>3</count>
         <interval>30</interval>
      </fixed>
      <incremental>
         <count>3</count>
         <interval>30</interval>
         <increment>5</increment>
      </incremental>
      <exponential>
         <count>3</count>
         <minBackoff>5</minBackoff>
         <maxBackoff>100</maxBackoff>
         <deltaBackoff>10</deltaBackoff>
      </exponential>
   </retry>

   <message>
      <request>
         <compression>gzip</compression>
         <serialization>json</serialization>
      </request>
      <response>
         <compression>gzip</compression>
         <serialization>json</serialization>
      </response>
   </message>

   <timeout>
      <connectionTimeout></connectionTimeout>
      <requestTimeout></requestTimeout>
   </timeout>

    <minorVersion>
      <latestMinorVersion>52</latestMinorVersion>
    </minorVersion>

</intuit-config>