QuickBooks connector Update activities in Jitterbit Design Studio

Prior to being able to update 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 updating QuickBooks data, using an example of updating a phone number for an existing QuickBooks Customer via an XML file through Jitterbit. These steps are broken up into beginning the Update activity, defining the Operation components, and deploying and executing the Operation.

Creating a QuickBooks Update operation

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

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

2. The Endpoint screen of the QuickBooks Update Wizard asks you to select the endpoint that you would like to update the existing data in. 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 updates the data that was created in QuickBooks connector - create activities using a 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.

   

3. The Object screen of the QuickBooks Update Wizard asks you to select the Object that you would like to update existing data in. 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 Update Wizard displays all of the Components that are available for existing data to be updated within your connected QuickBooks instance. For purposes of this walkthrough, we will update existing Customer data (phone number) 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 updated within your connected QuickBooks Online instance. A new tab should appear in Studio called QuickBooks Update Activities. You can rename your create activity here if desired; in the example ours is called "Customer QuickBooks Update."

   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 update existing Customer data in QuickBooks.

7. A new tab should open in Studio called Operations, containing a graphical representation of the Update 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 Update 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: In the example, the following XML is an input request to update information for an existing Customer. This specific Customer was created in the example used in QuickBooks connector - create activities. The XML below shows that we want to update the Customer's PrimaryPhone to the value supplied in the XML.

  Important

  Notice that not all fields are listed in the XML file below – only the fields that we want to update. We are able to update only specific fields by setting:

  sparse="1"

  The value of 1 indicates a true value. When sparse is set to true, then at the time of the update, only the provided values will be updated. All other values not listed for the given customer remain the same.

  The value of 0 indicates a false value. If sparse were set to false, then all other fields that are not listed would be overwritten to a null value. Take extreme caution setting sparse="0" as this will effectively delete any existing data within fields that are not listed.

  Note

  It is important to use the Id and SyncToken used in QuickBooks to associate the customer whose record we want to update. If you followed the example used in QuickBooks connector - create activities, you can get the Id and SyncToken from your CustomerCreateResponse.xml.

  CustomerCreateRequest.xml

  <ns:INPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions">
      <Customer sparse="1">
          <Id>58</Id>
          <SyncToken>1</SyncToken>
          <GivenName>Peter1</GivenName>
      <PrimaryPhone>
        <FreeFormNumber>7678907699</FreeFormNumber>
        <Default>true</Default>
      </PrimaryPhone>
      </Customer>
  </ns:INPUT>
  

  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, the Folder is 'C:\projects\quickbooks' and the Get Files is 'CustomerUpdateRequest.xml'.

• Target: Double-click on the Target icon. In the example, we will output the updated data from QuickBooks to an XML file to make sure it has been updated. To do this, 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 'CustomerUpdateResponse.xml'.

• Request: Double-click on the Request icon and select Create New Transformation. Or click the Create Request button from the QuickBooks Update 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 'QuickBooksUpdateRequest.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 + on each of the Source side and the Target side to expand then items in each tree. Then click the Auto Map icon the appears below the Target side of the tree: 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 Update 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 'QuickBooksUpdateResponse.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 Update 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 updated data from QuickBooks output to the Target you specified. For the example, the file is now created in 'C:\projects\quickbooks\CustomerUpdateResponse.xml':

<ns:OUTPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions">
    <ns:Customer>
        <ns:Id>58</ns:Id>
        <ns:SyncToken>2</ns:SyncToken>
        <ns:MetaData>
            <ns:CreateTime>2016-11-21T10:31:59-07:00</ns:CreateTime>
            <ns:LastUpdatedTime>2016-11-21T10:36:35-07:00</ns:LastUpdatedTime>
        </ns:MetaData>
        <ns:GivenName>Peter1</ns:GivenName>
        <ns:FamilyName>Hynes1</ns:FamilyName>
        <ns:FullyQualifiedName>Soft Tech1</ns:FullyQualifiedName>
        <ns:CompanyName>Soft Tech1</ns:CompanyName>
        <ns:DisplayName>Soft Tech1</ns:DisplayName>
        <ns:PrintOnCheckName>SoftTech LLC</ns:PrintOnCheckName>
        <ns:Active>1</ns:Active>
        <ns:PrimaryPhone>
            <ns:FreeFormNumber>7678907699</ns:FreeFormNumber>
        </ns:PrimaryPhone>
        <ns:Mobile>
            <ns:FreeFormNumber>8678907676</ns:FreeFormNumber>
        </ns:Mobile>
        <ns:Fax>
            <ns:FreeFormNumber>9678907676</ns:FreeFormNumber>
        </ns:Fax>
        <ns:PrimaryEmailAddr>
            <ns:Address>softtech@test.com</ns:Address>
        </ns:PrimaryEmailAddr>
        <ns:WebAddr>
            <ns:URI>http://stech.com</ns:URI>
        </ns:WebAddr>
        <ns:DefaultTaxCodeRef>2</ns:DefaultTaxCodeRef>
        <ns:Taxable>1</ns:Taxable>
        <ns:BillAddr>
            <ns:Id>96</ns:Id>
            <ns:Line1>456 Chinna Street</ns:Line1>
            <ns:City>Tracy</ns:City>
            <ns:Country>USA</ns:Country>
            <ns:CountrySubDivisionCode>767</ns:CountrySubDivisionCode>
            <ns:PostalCode>95391</ns:PostalCode>
            <ns:Lat>37.7582199</ns:Lat>
            <ns:Long>-121.548418</ns:Long>
        </ns:BillAddr>
        <ns:ShipAddr>
            <ns:Id>97</ns:Id>
            <ns:Line1>456 Chinna Street</ns:Line1>
            <ns:City>Tracy</ns:City>
            <ns:Country>str1234</ns:Country>
            <ns:CountrySubDivisionCode>767</ns:CountrySubDivisionCode>
            <ns:PostalCode>95391</ns:PostalCode>
            <ns:Lat>INVALID</ns:Lat>
            <ns:Long>INVALID</ns:Long>
        </ns:ShipAddr>
        <ns:Job>0</ns:Job>
        <ns:BillWithParent>0</ns:BillWithParent>
        <ns:Balance>0</ns:Balance>
        <ns:BalanceWithJobs>0</ns:BalanceWithJobs>
        <ns:CurrencyRef name="United States Dollar">USD</ns:CurrencyRef>
        <ns:PreferredDeliveryMethod>Print</ns:PreferredDeliveryMethod>
    </ns:Customer>
</ns:OUTPUT>

In addition, when you check your QuickBooks account, you should find the Customer's phone number updated.