Task API

Overview

The QBO Task module (ImportForm) allows you to easily track ad-hoc data, akin to a NoSQL store. Technically, we're storing ad-hoc XML data in a SQL table (ImportForm.XmlData). To use this:
  • Create a template representing the type of document you are tracking
  • Save data to an instance of a task using a RESTful API, or the Import Framework
  • Query the data

Create a Template


Assume you wish to track the following:
  • Tax assessment data on a Property
  • Federal jobs data for the neighborhood a Property is located in
  • School district characteristics for the neighborhood a Property is located in
For these examples, you should create 3 different task templates from Design > Tasks:
  • Tax Assessment (applies to Property)
  • Jobs Data (applies to Property)
  • School Characteristics (applies to Property)

Save Data

Assume we have an existing Property record in the QBO Property table, where the address is "123 Main Street, Anywhere, CA, 92101", and the PropertyID is 17.  
  • To save tax data, invoke the following URL:
    /Decision/ImportForm.ashx/Save?Object=Property&ObjectID=17&Template=Tax Assessment&TaxValue=250,000&TaxYear=2016&LandValue=117,254.55
  • To save jobs data, invoke the following URL:
    /Decision/ImportForm.ashx/Save?Object=Property&ObjectID=17&Template=Jobs Data&MedianIncome=72,000&MedianAge=42&MedianFamilySize=3.7
  • To save school characteristics data, invoke the following URL:
    /Decision/ImportForm.ashx/Save?Object=Property&ObjectID=17&Template=School Characteristics&AverageSAT=1880&PercentInAP=16
The gist is to call ImportForm.ashx/Save?Object={Parent table}&ObjectID={Parent key}&Template={Task Template}&{Ad Hoc Parameters you want to save}

At this point, there will be three new task (ImportForm) rows, each with different XmlData that looks like this:

<ImportFormXml>
  <TaxValue>250,000</TaxValue>
  <TaxYear>2016</TaxYear>
  <LandValue>117,254.55</LandValue>
</ImportFormXml>

You may save data via the Import Framework, passing data like this:

<ImportFormCollection>
<ImportFormItem>
<Object>Property</Object>
<ObjectID>17</ObjectID>
<Template>Tax Assessment</Template>
<TaxValue>250,000</TaxValue>
<TaxYear>2016</TaxYear>
<LandValue>117,254.55</LandValue>
</ImportFormItem>
<ImportFormItem>
<Object>Property</Object>
<ObjectID>17</ObjectID>
<Template>Jobs Data</Template>
<MedianIncome>72,000</MedianIncome>
<MedianAge>42</MedianAge>
<MedianFamilySize>3.7</MedianFamilySize>
</ImportFormItem>
<ImportFormItem>
<Object>Property</Object>
<ObjectID>17</ObjectID>
<Template>School Characteristics</Template>
<AverageSAT>1880</AverageSAT>
<PercentInAP>16</PercentInAP>
</ImportFormItem>
</ImportFormCollection>

Query the Data

You can query the XmlData a number of ways:
  • Invoke ImportForm.ashx/SearchXml?Object=Property&ObjectID=17&Output=Xml to get an XML document containing all three tasks and their XmlData
  • Invoke ImportForm.ashx/SearchXml?Object=Property&ObjectID=17&Output=Json to get a JSON document containing all three tasks and their XmlData
  • Invoke ImportForm.ashx/SummaryFlat?ID=X&Output=Excel to 'flatten' the structure from ad-hoc XML elements into a simple table

Retaining Data Across Multiple API Calls

Tasks are updated via the QBO UI, which will render and submit all data previously stored with a task, including all elements stored in ImportForm.XmlData.

Assume you make the following call:

ImportForm.ashx/Save?ID=12345&MyCustomField=Foo

At this point, the ImportForm.XmlData for ImportFormID 12345 is:

<ImportFormXml>
  <MyCustomField>Foo<MyCustomField>
</ImportFormXml>

If you then call:

ImportForm.ashx/Save?ID=12345&MyCustomField=Bar

You'd get what you expect:

<ImportFormXml>
  <MyCustomField>Bar<MyCustomField>
</ImportFormXml>

If you wish to remove MyCustomField from the XmlData, you call:

ImportForm.ashx/Save?ID=12345

This can present a problem if ImportForm/Save is called via an API call where the originating system does not know the existing fields in XmlData. To avoid removing fields accidentally from XmlData, simply pass a MergeXmlData parameters:

ImportForm.ashx/Save?ID=12345&MergeXmlData=1

This will not remove existing XmlData fields just because they're missing from the request.

The reason for this behavior is simple: check boxes! When rendering a check box as an HTML form element, a checked check box is passed over the wire, but an unchecked check box is not. In order for check boxes presented in the UI to behavior properly with ImportForm.XmlData, QBO assumes that the lack of an element in the request data means that it should be removed.  This is a good assumption for the majority of Task API calls, which are made from the QBO UI which renders things like check boxes.

Use of the MergeXmlData allows third parties to control which behavior they want.
Comments