Asynchronous calls

The QuickBooks Online .NET SDK has generic APIs to call Data Services using both synchronous and asynchronous methods. Asynchronous methods are potentially used to call object methods that require a long time to complete. Asynchronous calling enhances long running methods with an asynchronous variant that returns immediately while the original thread continues calling uninterrupted. It is also possible to subscribe and obtain return value when such long methods are complete. An example scenario where asynchronous method of calling can be used would be, calling thread is blocked until the method of loading data is complete. The following sections describe how to call the APIs asynchronously.

Data Services API

The .NET SDK provides asynchronous methods for accessing QuickBooks Online Data Services.

Note

Note

The .NET SDK supports globalization. Your app users can input data in languages such as Chinese or Japanese to obtain output in the same languages.

To asynchronously access a single data object, such as an account or customer, perform the following steps:

1. Reference the SDK Assemblies

Make sure the following assemblies have been referenced:

Include the following using statements:

1
2
3
4
using Intuit.Ipp.Core;
using Intuit.Ipp.DataService;
using Intuit.Ipp.Data;
using Intuit.Ipp.Security;

2. Set up Configuration

The SDK allows you to set configurations for features such as Logging in the application settings (Appsettings.json) file. If you have already defined custom settings or do not need to configure custom settings for your app, go to step 3.

a. Configure the request and response message formats. Configure the serialization and compression format of requests and responses. For more information, see Making calls with the REST API. Include the following script to set the Serialization format of requests and responses to net and their compression format to GZip:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
"Message":{
      "Request": {
         "CompressionFormat": "Gzip",
         "SerializationFormat": "Json"
       },
      "Response": {
             "CompressionFormat": "Gzip",
         "SerializationFormat": "Json"
       }
}

Note

Note

You can define additional features in the config file. For information, see Configuration. If custom settings are not defined in the config file, the SDK will use the default values.

3. Build the ServiceContext

The ServiceContext object is a parameter for all calls to QuickBooks OnlineData Services, Platform Services, and Reporting Services. When you call a data service API to access QuickBooks data, the SDK first retrieves the available custom configuration settings to build the ServiceContext object. In the absences of custom settings, it uses the default values available within the SDK.

a. Create the OAuth2RequestValidator object: A valid OAuth2RequestValidator object ensures that the end-user has authorized your app to access QuickBooks Onlinedata. For details on how to create an OAuth2RequestValidator object, see Authorization.

1
OAuth2RequestValidator reqValidator = new OAuth2RequestValidator(accessToken);
  1. Create an instance of the ServiceContext class. The following code creates a ServiceContext object:

1
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);

4. Create the DataService

Create an instance of DataService by passing the ServiceContext created in Step 3 as the argument.

1
DataService service = new DataService(context);

5. Create the Data Object

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

1
2
3
4
5
6
Customer customer = new Customer();
//Mandatory Fields
customer.GivenName = "Mary";
customer.Title = "Ms.";
customer.MiddleName = "Jayne";
customer.FamilyName = "Cooper";

6. Subscribe to Events

Setup the callback event for the asynchronous service:

Add API Callback Event

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
service.OnAddAsyncCompleted += (sender, e) =>
{
   if (e.Error != null)
   {
      // Error handling code
      // User e.Error to get Error object
   }
   else if(e.Entity!=null)
   {
      Customer addedCustomer = e.Entity as Customer;
   }
};
Update API Callback Event

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
service.OnUpdateAsyncCompleted += (sender, e) =>
{
   if (e.Error != null)
   {
      // Error handling code
      // User e.Error to get Error object
   }
   else if(e.Entity!=null)
   {
      Customer updatedCustomer = e.Entity as Customer;
   }
};
FindAll API Callback Event

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
service.OnFindAllAsyncCompleted += (sender, e) =>
{
   if (e.Error != null)
   {
      // Error handling code
      // User e.Error to get Error object
   }
   else if(e.Entities!=null)
   {
      List<IEntity> customers = e.Entities;
   }
};
FindByID API Callback Event

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
service.OnFindByIdAsyncCompleted += (sender, e) =>
{
   if (e.Error != null)
   {
      // Error handling code
      // User e.Error to get Error object
   }
   else if(e.Entity!=null)
   {
      Customer customer = e.Entity as Customer;
   }
};

6. Call the Service

To perform a CRUD operation on QuickBooks Onlinedata, call the appropriate method on the service.

The following code snippets show how to call CRUD methods asynchronously:

Add() Method

1
service.AddAsync<Customer>(customer);
Update() Method

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.

1
service.UpdateAsync<Customer>(customer);

Note

Note

To update only the property values specified in the request and leave the rest of writable properties unchanged, set the sparse property to true.

FindAll() Method

To paginate through all of the objects of a specific type in a given company, call the FindAll() method. Increment the startPosition parameter with each successive call. The maxResult parameter is the number of objects to fetch in each call. For example, the following code snippet gets the first ten accounts:

1
2
3
int startPosition = 1;
int maxResult = 10;
service.FindAllAsync<Customer>(customer, startPosition, maxResult);
FindById() Method

1
service.FindByIdAsync<Customer>(customer);
Batch process

To asynchronously access multiple data objects in a single request, perform the steps as shown in the following example. For more information, see Calling synchronous methods asynchronously.

1. Build the ServiceContext object

The ServiceContext object is a parameter for all calls to QuickBooks OnlineData Services, Platform Services, and Reporting Services. When you call a Data service API to access a QuickBooks company, the SDK first retrieves the available custom configuration settings to build the ServiceContext object.

  1. Create the OAuth2RequestValidator object. A valid OAuth2RequestValidator object ensures that the end user has authorized your app to access their QuickBooks company. The following code creates an OAuth2RequestValidator object:

1
OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(accessToken);

b.Create a ServiceContext object. The following code creates a ServiceContext object:

1
ServiceContext context = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);

2. Create the Data Service

Create an instance of DataServices by passing the ServiceContext as the argument:

1
DataServices dataServices = new DataServices(context);

3. Create the Batch object

The following code snippet shows how to create a Batch object:

1
Batch batch = service.CreateNewBatch();

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
3
4
5
6
Customer customer = new Customer();
//Mandatory fields
customer.GivenName = "Mary";
customer.Title = "Ms.";
customer.MiddleName = "Jayne";
customer.FamilyName = "Cooper";

5. Add Request to the batch

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 IntuitBatchResponse objects that are returned by the call to the service. The following code snippets show how to add the operation element to the batch object created in step 3:

1
2
3
4
5
//This code adds the Create request to the batch
batch.Add(customer, "bID1", OperationEnum.create);

//This code adds the Query request to the batch
batch.Add("Select * from Customer", "bID2");

6. Subscribe to the Event and execute the batch

To receive responses when batch processing completes, subscribe to the event and then execute the batch:

 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
try
{
   batch.OnBatchExecuteAsyncCompleted += new BatchProcessingCallback.BatchExecutionCompletedEventHandler
   (this.BatchExecutionCompleted);
   batch.ExecuteAsync();
 }
 catch (Ipp.Exception.IdsException ex)
 {

 }

private void BatchExecutionCompleted(object sender, BatchExecutionCompletedEventArgs eventArgs)
{
   if (eventArgs.Error != null)
   {
     Batch batch = eventArgs.Batch;
      IntuitBatchResponse addCustomerResponse = batch["addCustomer"];
      if (addCustomerResponse.ResponseType == ResponseType.Entity)
      {
          Customer addedcustomer = addCustomerResponse.Entity as Customer;
      }

      IntuitBatchResponse queryCustomerResponse = batch["queryCustomer"];
      if (queryCustomerResponse.ResponseType == ResponseType.Query)
      {
         List< Customer> customers = queryCustomerResponse.Entities.ToList().ConvertAll(item => item as Customer);
      }
   }
}