PilotFish Interface Exchange (PIE)

Description

QuickBooks Online - popular accounting software developed by Intuit. Mostly designed for small business it helps to manage a company's interactions with customers and sales prospects.

This interface allows to easily exchanging data with QuickBooks Online via RESTful web services API. For example, you can export customer's data from your CRM system to QuickBooks and backwards.

The input data for this interface is the XML file of specific format, described below. Format and type of inputted data can be changed to meet end-user requirements.

Using this interface template user can create, get by ID, update or delete customer's information from your account at QuickBooks Online.

Input XML file format

The root element of input XML file is <Request>.

1. To create a new Customer need use section <create>. This section should contain element <data> which should contain <Customer> elements. <Customer> element must contain all the elements necessary to create - such as Type of Customer, LastName, FirstName, Title etc.. The exhaustive list of possible customer elements you can find in section 'List of the customer fields'.

   <create>
     <data>
        <Customer>
          <TypeOf>Person</TypeOf>
          <LastName>James</LastName>
          <FirstName>Bond</FirstName>
          <Salutation>Mr.</Salutation>
          ...

2. To read the Customer's data by ID from QuickBooks Online need use section <getCustomerByID/>

3. To update the Customer data one needs to use the section <update>. This section should contain element <data> which should contain <Customer> elements. <Customer> element must contain the <Id> element (unique identifier of the customer) and the elements to update - such as Type of Customer, LastName, FirstName, Title etc. The exhaustive list of possible customer elements you can find in section 'List of the customer fields'.

   <update>
     <data>
        <Customer>
          <TypeOf>Person</TypeOf>
          <Id>007</Id>
          <LastName>James</LastName>
          <FirstName>Bond</FirstName>
          <Salutation>Mr.</Salutation>
          ...;

4. To delete the Contact need use section <delete>. This section should contain element <data> which should contain elements <Customer>. <Customer> element must contain the <Id> element, which represents ID of the actual customer record on the QuickBooks Online.

   <delete>
     <data>
       <Customer>
         <Id>007</Id>
       </Customer>
     </data>
   </delete>
   Example of the input XML file is available in the folder date->samples.

Response XML file format

Let's read the Customer's data by ID. As response from QuickBooks Online we get XML like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Customer xmlns="http://www.intuit.com/sb/cdm/v2"
xmlns:ns2="http://www.intuit.com/sb/cdm/qbopayroll/v1" 
xmlns:ns3="http://www.intuit.com/sb/cdm/qbo">
<Id>17</Id>
<SyncToken>0</SyncToken>
<MetaData>
<CreateTime>2010-09-13T02:09:18-07:00</CreateTime>
<LastUpdatedTime>2010-09-13T02:09:18-07:00</LastUpdatedTime>
</MetaData>
<Name>James Bond</Name>
<Address>
<Line1>Park Avenue</Line1>
<Line2></Line2>
<City>Woodland Hills</City>
  <CountrySubDivisionCode>CA</CountrySubDivisionCode>
  <PostalCode>91367</PostalCode>
</Address>
<Phone>
<DeviceType>Fax</DeviceType>
<FreeFormNumber>(770) 349-1300</FreeFormNumber>
</Phone>
<Phone>
  <DeviceType>Mobile</DeviceType>
  <FreeFormNumber>(770) 349-1200</FreeFormNumber>
</Phone>
<WebSite>
  <URI>http://www.example.com/</URI>
</WebSite>
<Email>
  <Address>james_bond@example.com</Address>
</Email>
<GivenName>James</GivenName>
<MiddleName>J</MiddleName>
<FamilyName>Bond</FamilyName>
<DBAName>Mint</DBAName>
<SalesTermId>5</SalesTermId>
</Customer>

Later this XML can be converted to specific for your system format. At this interface we convert it to our sample format. Processed XML is stored to output directory.

List of the customer fields

As you may have noticed, typical update and create XML messages contain customer fields. The exhaustive list of the possible customer fields (XML element names) you can find below:

• Id
• MetaData
• Name
• Address
  Line1
  Line2
  Line3
  Line4
  Line5
  City
  CountrySubDivisionCode
  PostalCode
  Tag
  

• Phone
  DeviceType
  FreeFormNumber
  

• WebSite URI
  

• Email Address
  

• ExternalId
• GivenName
• MiddleName
• FamilyName
• Suffix
• Gender
• BirthDate
• DBAName
• TaxIdentifier
• ShowAs
• SalesTermId
• SalesTaxCodeId
• SalesTaxCodeName
• PaymentMethodId
• PaymentMethodName
• OpenBalance

Using interface template

Even though this is a template, it is fully functional interface.

To run a sample transaction you need to do the following steps:

1. Specify the input, output and processed directories in the environment settings of the interface. You can access environment settings either from the XCS eiConsole menu (Route -> Environment Properties) or by simply editing the 'environment-settings.conf' file, located in the root of the interface folder.

2. Define the input XML. This XML should contain proper credentials and necessary input data. See 'Input XML file format' section for details.

3. Put the input XML file to the input directory.

4. Run the interface (test run can be performed using the EIP Emulator of the XCS eiConsole).

5. Find the result file(s) in the output directory.

Note: There are 2 authorization types at QuickBooks Online: INTUITAUTH or Oauth (OAuth Core 1.0 Revision A.) type. Authorization routine must be implemented before using interface template.

Implementation notes

This interface template consists of 6 routes:

1. QB1_ActionProcess - main route which create request action to the QuickBooks Online service according to the data from input XML file.

2. QB2_getCustomerResponse - receives a replay after getCustomer request and stores it in to output directory.

3. QB3_CreateResponse - receives a replay after Create request and stores it in to output directory.

4. QB4_UpdateResponse - receives a replay after Update request and stores it in to output directory.

5. QB5_DeleteResponse - receives a replay after Delete request and stores it in to output directory.

6. Error_Handling_Route - Error Handling is performed using transaction monitoring functionality of the XCS eiConsole. Special error-handling route 'QB_Error' catches all of the execution errors of the interface and put report about detected error to the specified output directory, to the file with name 'error.xml'

Release Details

This is the initial release of the QuickBooks online Integration Interface Template.