QuickBooks Connector Delete Activities¶
All existing QuickBooks users are required to migrate to OAuth 2.0 authentication by December 17, 2019. See the Intuit Developer Blog Post April 10, 2019 and the Intuit OAuth Blog for additional information. After your QuickBooks account is migrated to OAuth 2.0, follow the steps to create a new endpoint at QuickBooks Connector OAuth 2.0 - Create Endpoint.
Prior to being able to delete 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 deleting QuickBooks data, using an example of deleting a Vendor Credit with a specific Id within QuickBooks via an XML file through Jitterbit. These steps are broken up into beginning the Delete activity, defining the Operation components, and deploying and executing the Operation.
As a limitation imposed by QuickBooks, it is not possible to delete some QuickBooks entities associated with a particular object. For example, Customer and Employee are not able to be deleted.
As a workaround, if you would like to delete data associated with a particular Component for which the Delete activity is not allowed, you can perform an Update activity and set sparse="0" to set all fields to null. See more under QuickBooks Connector - Update Activities.
For reference, see the Jitterpak QuickBooksExample.jpk and accompanying files in QuickBooksSampleRequestFiles.zip needed to execute the Jitterpak operations. Unzip the QuickBooksSampleRequestFiles.zip to your "C:\" drive, or if you unzip to another directory make sure to edit the source and target directories in the operations. If this is your first time using a Jitterpak see Importing a Jitterpak.
Creating a QuickBooks Delete Operation¶
Within your project within Jitterbit Studio, there are several ways to begin a new QuickBooks Delete activity. Each of the following options will start the QuickBooks Delete Wizard to guide you through the process.
- Go to File > New > Connectors > New QuickBooks Delete.
- In the tree on the left under Connectors, right-click on the QuickBooks category, then select New QuickBooks Delete.
- In the tree on the left under Connectors, double-click on the QuickBooks category, then right-click on QuickBooks Delete Activities and select New QuickBooks Delete.
- In the top toolbar, click the connector icon (orange jigsaw piece) . In the popup, select QuickBooks, then select QuickBooks Delete.
The Endpoint screen of the QuickBooks Delete Wizard asks you to select the endpoint that you would like to delete 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.
The example used in this documentation deletes a Vendor Credit for a specific customer in a QuickBooks sandbox account. For further reference, you can also follow along with the Create and Update examples for Vendor Credit provided in the Jitterpak.
The Object screen of the QuickBooks Delete Wizard asks you to select the Object that you would like to delete 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.
The Component screen of the QuickBooks Delete Wizard displays all of the Components associated with the Accounting object in your connected QuickBooks instance. For purposes of this walkthrough, we will delete an existing Vendor Credit and therefore select the VendorCredit component. Then click the Finish button.
Not all of these Components can necessarily be deleted from Jitterbit due to limitations imposed by the QuickBooks software.
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 Delete Activities. You can rename your create activity here if desired; in the example ours is called "Customer QuickBooks Delete."
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.
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 delete existing Vendor Credit data in QuickBooks.
A new tab should open in Studio called Operations, containing a graphical representation of the Delete 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 Delete 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.
There are many different types of data that can be used for each component of the Operation. To learn more about additional customization options, please refer to the Design Studio section of our documentation.
Source: In the example, the following XML is an input request to delete an existing Vendor Credit with the specified QuickBooks Id.
It is important to use the Id and SyncToken used in QuickBooks to associate the record we want to delete. Notice that sparse is set to "0" because we want to delete all Vendor Credit data.VendorCreditDeleteRequest.xml
<?xml version="1.0" encoding="utf-8"?> <ns:INPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions"> <VendorCredit sparse="0"> <Id>155</Id> <SyncToken>1</SyncToken> </VendorCredit> </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 'VendorCreditDeleteRequest.xml'.
Target: Double-click on the Target icon. In the example, we will output the deleted data from QuickBooks to an XML file to make sure it has been deleted. 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 'VendorCreditDeleteResponse.xml'.
Request: Double-click on the Request icon and select Create New Transformation. Or click the Create Request button from the QuickBooks Delete Activities tab. This will open the Transformation Wizard which will walk you through creating the Request.
- On the first screen, Name, select the Source type used above. For the example we chose XML. Leave the Target as default.
- On the next screen, Source, choose the button to Select an existing XML structure. In the dropdown select "QuickBooks Schemas." Then select 'QuickBooksDeleteRequest.xsd' to use as your structure file. On the next screen, click Finish.
- 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. 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: For this example, right-click on the Response icon and select Pass-Through. You could instead create a new Transformation and map your fields as in the Create, Query, and Update Activities.
Deploying and Executing the Operation¶
With the QuickBooks Delete 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 deleted data from QuickBooks output to the Target you specified. For the example, the file is now created in 'C:\projects\quickbooks\VendorCreditDeleteResponse.xml':
In addition, when you check your QuickBooks account, you should find that the specified Vendor Credit no longer exists.