QuickBooks connector Query activities in Jitterbit Design Studio

Prior to being able to query QuickBooks data from Jitterbit, you will need to have created a QuickBooks endpoint within Jitterbit Studio (see QuickBooks connector OAuth 1.0a - create endpoint or QuickBooks connector 2.0 - create endpoint). Now that Jitterbit has access to your QuickBooks Online instance, you can perform four main activities with your QuickBooks data: Query, Create, Update, or Delete.

This page focuses on querying your QuickBooks data, using an example of querying existing QuickBooks data on a specific Customer via an XML file through Jitterbit. These steps are broken up into beginning the Query activity, defining the Operation components, and deploying and executing the Operation.

Creating a QuickBooks Query operation

1. Within your project within Jitterbit Studio, there are several ways to begin a new QuickBooks Query activity. Each of the following options will start the QuickBooks Query Wizard to guide you through the process.

   • Go to File > New > Connectors > New QuickBooks Query.
   • In the tree on the left under Connectors, right-click on the QuickBooks category, then select New QuickBooks Query.
   • In the tree on the left under Connectors, double-click on the QuickBooks category, then right-click on QuickBooks Query Activities and select New QuickBooks Query.
   • In the top toolbar, click the connector icon (orange jigsaw piece) . In the popup, select QuickBooks, then select QuickBooks Query.

2. The Endpoint screen of the QuickBooks Query Wizard asks you to select the endpoint that you would like to query data from. You should have already set up endpoints in QuickBooks connector OAuth 1.0a - create endpoint or QuickBooks connector 2.0 - create endpoint. Select the appropriate endpoint, for example a sandbox or production endpoint. Click Next when finished.

   Note

   The example used in this documentation queries a set of sample data provided in every new QuickBooks sandbox. To access your sandbox, go to https://developer.intuit.com/ and sign into your QuickBooks Online account. Once logged in, go to Docs & Tools > Sandbox > Go to company for the sandbox you want to use. Within the sandbox you will see the sample data available for testing purposes.

   

3. The Object screen of the QuickBooks Query Wizard asks you to select the Object that you would like to query from. In this example we used the Accounting API during creation of the QuickBooks Online app and thus have have only one Object to select: Accounting. Click on the Object and then click Next to continue.

   

4. The Component screen of the QuickBooks Query Wizard displays all of the Components that are available to be queried within your connected QuickBooks instance. For purposes of this walkthrough, we will query for a Customer and therefore select the Customer component. Then click the Finish button.

   

5. Jitterbit Studio will then proceed with creating a QuickBooks API Request and Response structure that will allow data to be queried for within your connected QuickBooks Online instance. A new tab should appear in Studio called QuickBooks Query Activities. You can rename your query here if desired; in the example ours is called "Customer QuickBooks Query."

   Click the + icon on the far right of both the Request and Response structure views in order to expand all elements within each structure. With each side now expanded, you should now see a screen that is similar to the image shown below.

   

6. Next, on the same screen, click the button Create Operation located under Use in an Integration in the upper right corner. This will create the Jitterbit operation that will query QuickBooks for Customer data.

7. A new tab should open in Studio called Operations, containing a graphical representation of the Query activity. Save your Operation by clicking either the single disk icon to save just this Operation or the multiple disk icon to save all changes in your integration project. You should see the asterisk on the Operations tab and Operation title disappear as your new Query activity is now created and saved to your project.

Defining the operation components

Now we need to define the other components of the Operation that appear within the graphical representation, including Source, Request, Response, and Target. For purposes of this walkthrough, we provide the following examples for reference above: Jitterpak QuickBooksExample.jpk and accompanying files QuickBooksSampleRequestFiles.zip .

• Source (Optional): In the example, the following XML is an input request to fetch for a Customer with the first name, or GivenName as it is known in QuickBooks, of 'Mark':

  CustomerQueryRequest.xml

  <ns:INPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions">
  <Customer>
  <Fields></Fields>
  <Condition>GivenName='Mark'</Condition>
  </Customer>
  </ns:INPUT>
  

  Note

  In the above example, the Fields are left empty which will fetch all fields for the Customer. If only certain fields are needed, use a "," (comma) delimiter between field names (e.g. field1,field2,field3). Then to apply Conditions to the query, specify the desired clause in Conditions as in the example below.

  As of version 8.25, the Condition field can also contain an ORDERBY clause, and/or the keywords STARTPOSITION and MAXRESULTS individually or on combination. For example:

  <Fields>Name,GivenName,FullyQualifiedName,AccountType</Fields> <Condition>GivenName='Mark' ORDERBY Name STARTPOSITION 0 MAXRESULTS 10</Condition>

  To use the XML file, first double-click on the Source icon, then select a new Source type. For this example, we are using a private agent with local files enabled, and thus select a Type of "Local File" and then Browse to the location. If you are using the example files and extracted to the recommended location C:\, the Folder is 'C:\projects\quickbooks' and the Get Files is 'CustomerQueryRequest.xml'.

  Note

  You can choose to bypass using a Source by right-clicking on the Source icon and selecting Remove from Graph. If you do this, then while specifying the Request, choose a Source of "None" and instead you can double-click on the variables on the right side (Target side) of the mapping to specify values. These more advanced options are covered under Transformations.

• Target: Double-click on the Target icon. In the example, we want to write to an XML file with the query output, so we will again select a Type of "Local File" and Browse to a location on the private agent where we want to save the data. In the example, the Folder is 'C:\projects\quickbooks' and the Filename is 'CustomerQueryResponse.xml'.

• Request: Double-click on the Request icon and select Create New Transformation. Or click the Create Request button from the QuickBooks Query Activities tab. This will open the Transformation Wizard which will walk you through creating the Request.

  1. On the first screen, Name, select the Source type used above. For the example we chose XML. Leave the Target as default.
  2. On the next screen, Source, choose the button to Select an existing XML structure. In the dropdown select "QuickBooks Schemas." Then select 'QuickBooksQueryRequest.xsd' to use as your structure file. On the next screen, click Finish.
  3. The Transformations tab should open where you can complete your mapping. Click and drag "Fields" from the left side (Source side) to "Fields" on the right side (Target side). Do the same with "Condition." Your mapping screen should now look similar to that below.

• Response: Double-click on the Response icon and select Create New Transformation. Or click the Create Response button from the QuickBooks Query Activities tab. This will open the Transformation Wizard which will walk you through creating the Response.

  1. On the first screen, Name, select the Target type used above. For the example we chose XML. Leave the Source as default.
  2. On the next screen, Source, choose the button to Select an existing XML structure. In the dropdown select "QuickBooks Schemas." Then select 'QuickBooksQueryResponse.xsd' to use as your structure file. On the next screen, click Finish.
  3. The Transformations tab should open where you can complete your mapping. Click the + at the bottom of each of the Source side and the Target side to expand then items in each tree. Click and drag the "OUTPUT" folder from the left side (Source side) to the "OUTPUT" folder on the right side (Target side). Your mapping screen should now look similar to that below.

Deploying and executing the operation

With the QuickBooks Query activity all set up, we are ready to deploy and execute the Operation.

From the Operations tab, click the Deploy icon. Then click the Execute icon to place the Operation in the queue for execution.

In the lower portion of the screen, the Operation monitor should indicate that your Operation was run successfully. If not, you can double-click the Status icon to view any log messages.

You should also now see the output of the query generated in the Target you specified. For the example, the file is now created in 'C:\projects\quickbooks\CustomerQueryResponse.xml':

title-"CustomerQueryResponse.xml" <ns:OUTPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions"> <ns:Customer> <ns:Id>17</ns:Id> <ns:SyncToken>0</ns:SyncToken> <ns:MetaData> <ns:CreateTime>2017-09-17T18:12:16-06:00</ns:CreateTime> <ns:LastUpdatedTime>2017-09-25T13:57:24-06:00</ns:LastUpdatedTime> </ns:MetaData> <ns:GivenName>Mark</ns:GivenName> <ns:FamilyName>Cho</ns:FamilyName> <ns:FullyQualifiedName>Mark Cho</ns:FullyQualifiedName> <ns:DisplayName>Mark Cho</ns:DisplayName> <ns:PrintOnCheckName>Mark Cho</ns:PrintOnCheckName> <ns:Active>1</ns:Active> <ns:PrimaryPhone> <ns:FreeFormNumber>(650) 554-1479</ns:FreeFormNumber> </ns:PrimaryPhone> <ns:PrimaryEmailAddr> <ns:Address>Mark@Cho.com</ns:Address> </ns:PrimaryEmailAddr> <ns:Taxable>0</ns:Taxable> <ns:BillAddr> <ns:Id>17</ns:Id> <ns:Line1>36 Willow Rd</ns:Line1> <ns:City>Menlo Park</ns:City> <ns:CountrySubDivisionCode>CA</ns:CountrySubDivisionCode> <ns:PostalCode>94304</ns:PostalCode> <ns:Lat>37.450412</ns:Lat> <ns:Long>-122.170593</ns:Long> </ns:BillAddr> <ns:ShipAddr> <ns:Id>17</ns:Id> <ns:Line1>36 Willow Rd</ns:Line1> <ns:City>Menlo Park</ns:City> <ns:CountrySubDivisionCode>CA</ns:CountrySubDivisionCode> <ns:PostalCode>94304</ns:PostalCode> <ns:Lat>37.450412</ns:Lat> <ns:Long>-122.170593</ns:Long> </ns:ShipAddr> <ns:Job>0</ns:Job> <ns:BillWithParent>0</ns:BillWithParent> <ns:Balance>314.28</ns:Balance> <ns:BalanceWithJobs>314.28</ns:BalanceWithJobs> <ns:CurrencyRef name="United States Dollar">USD</ns:CurrencyRef> <ns:PreferredDeliveryMethod>Print</ns:PreferredDeliveryMethod> </ns:Customer> </ns:OUTPUT>