Synchronous calls

The QuickBooks Online Java SDK has APIs to wrap the QuickBooks Online APIs, either synchronously or asynchronously. These APIs enable apps to access QuickBooks Online resources such as accounts, customers, and invoices as well as access to platform services such as OAuth, connection management, and OpenID management. The following sections describe how to call the APIs synchronously.

To batch process multiple operations (such as add, delete, or update) on multiple resources in a single request, see Batch process.

1. Set up the configuration.

Configure the serialization and compression format of requests and responses in the properties file. For more information, see Making calls with the REST API. If you have defined custom settings already or do not need to configure custom settings for your app, go to step 2.

1. Create the Configuration file. In your app project, create an intuit-config.xml file.
2. Include the following script in the intuit-config.xml file to set the serialization format of requests and responses to XML and their compression format to Gzip:

 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>

2. Build the context.

Context is a parameter for all calls to QuickBooks Online Data Services. When you call a Data Service API to access QuickBooks Online data, the SDK first retrieves the available custom configuration settings to build the Context object. In the absence of custom settings, it uses the default values available within the SDK.

1. Create the OAuth2Authorizer object. A valid OAuth2Authorizer object ensures that the end-user has authorized your app to access QuickBooks Online data. For details on how to create an OAuth2Authorizer object, see Authorization.
2. Create an instance of the Context class. The following code snippet creates a Context object:

1
2
3
4
5

// Create OAuth object
OAuth2Authorizer oauth = new OAuth2Authorizer("accessToken"); //set access token obtained from BearerTokenResponse

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

3. Create the data service.

Create an instance of DataService by passing the Context object created in Step 2b as the argument:

1

DataService service = new DataService(context);

4. Create the data object.

Data objects (entities) represent QuickBooks company data, such as invoices and customers. The following code shows how to create a Customer object:

1
2

Customer customer=new Customer();
customer.setDisplayName("Mary");

5. Call the service.

To perform a CRUD operation on QuickBooks Online data, call the appropriate method on the service. The following code snippets show how to perform CRUD operations by calling Java methods on the service:

The following code creates a new customer:

1

Customer resultCustomer = service.add(customer);

This operation updates all writable properties of an existing entity. If a writable property is omitted in the request, that property’s value is set to NULL. The following code updates the customer entity:

1

Customer resultCustomer = service.update(customer);

To update only the property values specified in the request and leave the rest of writable properties unchanged, set the sparse property to true as shown in the following code:

1

customer.setSparse(true);Customer resultCustomer = service.update(customer);

The following code retrieves a customer by ID:

1

Customer resultCustomer = service.findById(customer);

The following code calls thefindAll() method to retrieve all customers and then extracts the name of each customer:

1
2
3
4
5
6

List<Customer> customers = service.findAll(customer);
Iterator itr = customers.iterator();
while (itr.hasNext()) {
   Customer customer = (Customer) itr.next();
   String customerName = customer.getName();
   ...}

The following code deletes the specified invoice and returns the deleted invoice information with status set as DELETED:

1

Invoice resultInvoice =  service.delete(invoice);

Name list entities, such as Customer and Vendor, cannot be deleted using the delete() method. To delete a name list entity, set the active flag to false, and use update() to update the entity.

To call Platform Services synchronously, perform the steps as shown in the following example.

Create an instance of IAPlatformClient:

1
2

import com.intuit.ia.connection.IAPlatformClient;
IAPlatformClient platformClient = new IAPlatformClient();

Get the request token and secret from Intuit using the consumerKey and consumerSecret generated for you when you created the app profile on the development site:

1

final Map<String, String>  requestTokenAndSecret = platformClient.getRequestTokenAndSecret(consumerKey, consumerSecret);

Pull the values out of the map:

1
2

finalString requestToken = requestTokenAndSecret.get("requestToken");
final String requestTokenSecret = requestTokenAndSecret.get("requestTokenSecret");

Now, persist requestToken and requestTokenSecret for the final request to Intuit for the access tokens and subsequent connection management.

Retrieve the authorize URL:

1

string OauthAuthorizeURL = platformClient.getOauthAuthorizeUrl(requestToken);

Get the access token and access token secret from Intuit:

1

final Map<String, String> accesstokenmap = platformClient.getOauthAccessToken(verifierCode, requestToken, requestTokenSecret, consumerKey, consumerSecret);

Pull the values out of the map:

1
2

finalString accessToken = oAuthAccessToken.get("accessToken");
finalString accessTokenSecret = oAuthAccessToken.get("accessTokenSecret");

Persist the CompanyID, accessToken, and accessTokenSecretin the app’s database for use in subsequent connection management.

This method disconnects the user from the QuickBookscompany file:

1

platformClient.disconnect(consumerKey, consumerSecret, accessToken, accessTokenSecret);

This method reconnects the current user to the QuickBooks company file. Use this method with your strategy to renew OAuth access tokens:

1

platformClient.reConnect(consumerKey, consumerSecret, accessToken, accessTokenSecret);

This method returns the current user:

1

User user = platformClient.getcurrentUser(consumerKey, consumerSecret, accessToken, accessTokenSecret);

This method returns the OpenID authorization URL:

1

string OpenIDAuthorizeURL = platformClient.getOpenIdAuthorizeUrl();

This method verifies the authentication response from the Intuit OpenID provider service:

1

Identifier verified = platformClient.verifyOpenIdResponse(receivingUrl, parameterMap);

Batch process is used to execute multiple operations (add, delete, update, and so forth) on multiple data objects (entities) in a single request. For more information, see Batch. To synchronously execute multiple operations, perform thesteps described in the following example:

1. Build the service context.

Context is a parameter for all calls to QuickBooks Online Data Services. When you call a Data Service API to access QuickBooks Online data, the SDK first retrieves the available configuration settings to build the Context object. In the absence of custom settings, it uses the default values available within the SDK.

1. Create the OAuthAuthorizer object. A valid OAuthAuthorizer object ensures that the end-user has authorized your app to access QuickBooks Online data. The following code creates an OAuthAuthorizer object:

1
2
3
4
5

String consumerKey = ...
String consumerSecret = ...
String accessToken = ...
String accessTokenSecret = ...
OAuthAuthorizer oauth = new OAuthAuthorizer(consumerKey, consumerSecret, accessToken, accessTokenSecret);

2. Create an instance of the Context class. The following code snippet creates a Context object:

1
2
3

String appToken = ...
String realmId = ...
Context context = new Context(oauth, appToken, ServiceType.QBO, realmId);

2. Create the data service.

Create an instance of DataService by passing the Context object created in Step 1 as the argument:

1

DataService service = new DataService(context);

3. Create the batch operation object.

The following code snippet shows how to create a BatchOperation object. Individual operation elements will be added to the BatchOperation object in a later step:

1

BatchOperation batchOperation = new BatchOperation();

4. Create the data object and query strings.

Data objects (entities) represent QuickBooks company data, such as invoices and customers. The following code shows how to create the Customer object and Query strings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

//Customer object
   Customer customer = new Customer();
   customer.setId("NG:2285964");
   customer.setSparse(true);
   customer.setDisplayName("L 34");
//Query string
   Customer c = Query.createQueryEntity(Customer.class);
   String query = select($(c.getId()), $(c.getDisplayName())).where($(c.getId()).eq("NG:2293936")).build();
//Report query
    stringString reportQuery = "report querydata";

5. Add request to the batch operation.

Each operation element in the batch is called a batch item and is represented by a unique batch ID. The ID is referenced in the batch response objects that are returned by the call to the service. The following code snippets show how to add the operation elements created in step 4, to the batchOperation object created in step 3:

1
2
3

batchOperation.addEntity(customer, OperationEnum.UPDATE, "bID1");
batchOperation.addQuery(query, "bID2");
batchOperation.addReportQuery(reportQuery, "bID3");

6. Execute the batch.

Call the service using the executeBatch() method to obtain a response object. Batch items are executed sequentially in the order specified in the request. The batchOperation response can have following response types:

• Entity: For operations such as create and update that return single entity responses.
• QueryResponse: For operations that return query results.
• Report: For report related operations.
• Fault: For operations that return exceptions due to one or more batch item in error.

The following code executes the BatchOperation:

1

service.executeBatch(batchOperation);

7. Implement logic to handle response.

The following section describes various ways to handle batch responses using the SDK.

The following code groups batch responses by ResponseType:

1
2
3
4
5
6
7
8

// to get fault
    resultsMap<String, Fault> faults = batchOperation.getFaultResult();
// to get query
    resultsMap<String, QueryResult> queryResults = batchOperation.getQueryResult();
// to get report
    resultsMap<String, Report> reports = batchOperation.getReportResult();
// to get entity
    resultsMap<String, IEntity> entities = batchOperation.getEntityResult();

The following code groups responses by ResponseType for a given batch ID:

1
2
3
4
5
6
7
8

// to get fault for the given bIdFault
fault = batchOperation.getFault(bId);
// to get query for the given bIdQueryResult
queryResult = batchOperation.getQueryResponse(bId);
// to get report for the given bIdReport
report = batchOperation.getReport(bId);
// to get entity for the given bIdIEntity
entity = batchOperation.getEntity(bId);

The following code returns a boolean response that shows under which response type a specified bId falls:

1
2
3
4
5
6
7
8

// to check fault for the given bIdbatch
Operation.isFault(bId);
// to check query for the given bIdbatch
Operation.isQuery(bId);
// to check report for the given bIdbatch
Operation.isReport(bId);
// to check entity for the given bIdbatch
Operation.isEntity(bId);

The following example shows how to handle the batch response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

List<String> bIds = batchOperation.getBIds();
   for(String bId : bIds) {
      if(batchOperation.isFault(bId)) {
         Fault fault = batchOperation.getFault(bId);
         // fault has a list of errors
         Error error = fault.getErrors().get(0);

         // error has error code, detail, message
      } else if(batchOperation.isEntity(bId)) {
         Customer c = (Customer) batchOperation.getEntity(bId);

         // cast to the corresponding entity and read values
      } else if(batchOperation.isQuery(bId)) {
         QueryResult queryResult = batchOperation.getQueryResponse(bId);

         // queryResult will have a list of entities, maxcount, startPosition and totalCount
      } else if(batchOperation.isReport(bId)) {
         Report report = batchOperation.getReport(bId);
         // report have reportheader, sections, reporttype,name and column description
   }
}