QuickBooks Online integration setup

Introduction

To connect your QuickBooks Online (QBO) instance with XTRF, you have to set up some settings on both sides.


Configure QuickBooks Online

  1. Make sure you are running the latest version of XTRF.

  2. Log in to the .

  3. In the My Hub dropdown menu in the top right-hand corner, select App Dashboard.

  4. Select your app or create a new one.

    • If you create a new app, in the Add permissions screen, select both available options.

      New app.png

  5. In the app’s left-hand side menu, select the Keys and credentials section.

  6. Switch to the Production.

  7. Copy Client ID and Client Secret to QBO configuration in XTRF (see the Configure XTRF step 5.a.).

  8. In the app’s left-hand side menu, select the Settings section.

  9. Go to the Redirect URIs tab.

  10. Switch to the Production.

  11. Click the Add URI button and enter https://your.XTRF.address.here/xtrf/seam/resource/qboauth/acceptToken, for example, https://acme.xtrf.eu/xtrf/seam/resource/qboauth/acceptToken.

  12. Save the settings.

While registering a new application, you will need to complete the App assessment questionnaire. Click on the expand below to see how it should be filled in.

  1. General Questions

  1. App Information

  1. Authorization and Authentication

  1. API Usage

  1. Error Handling

  1. Security


Configure XTRF 

  1. Sign in to the XTRF Home Portal.

  2. Go to Configuration Menu → Integration → QuickBooks Online.

  3. In the Main Settings tab, click the Edit button.

  4. Check the QuickBooks Online Integration Enabled box. The settings menu expands.

  5. In the General Settings section:

    1. Provide the Client ID and the Client Secret from your QBOinstance. 

    2. Choose the Main Currency in your QuickBooks Installation.

    3. In the Synchronize Items Newer than field, set up the required date of the modification of synchronized items. This field will be automatically updated each time synchronization occurs.

    4. Select Branches for which the synchronization should take place.

    5. In the Add QB Invoice Items based on field, set up whether XTRF should send to QuickBooks Invoice Items or Payables/Receivables data.

    6. (Optional) Once the synchronization is performed, you will be able to browse the Logs. Also, you will be able to see the items that have been synchronized in the Integration Log tab.

    7. (Optional) For QBO International, check the Synchronize Invoices with Tax Rates as QB Tax Codes box.
      Before proceeding to the next step, close all other active QuickBooks sessions (sign out from QB in other browser tabs and close them).

    8. Click Connect to QuickBooks button. A pop-up window or a new tab appears:

      1. Sign in to QuickBooks Online.

      2. Click the Authorize button.

    9. Close the pop-up window (tab), go back to XTRF, and click the Save button.

  6. In the Clients section, select whether the integration should synchronize XTRF Clients to QuickBooks by checking or unchecking the Synchronize Clients box. If you choose to synchronize clients, additional settings appear:

    1. In the For Client Invoices Use QB Item Name Expression field, set up how the Client invoice items are created in QuickBooks. By default, it is  ${item.name}.
      Note: This option is not available if you select XTRF Payables/Receivables in the  Add QB Invoice Items Based on field in step 4.e. of this guide.

    2. In the For Client Invoices Use Description Expression field, set up how the Client invoice descriptions are created in QuickBooks. By default, it is ${entity.finalNumber}.

    3. In the For Client Invoices Use QB Item Description Expression field, set up how the Client invoice item descriptions are created in QuickBooks. By default, it is ${item.displayName}.

    4. In the For Client Invoices Use QB Default Item Name field enter a proper expression. By default, it is customerItem.

    5. In the Synchronize when Client Invoice Status is field, choose the first status of a Client Invoice in XTRF that will trigger the invoice transfer and synchronization to QuickBooks. By default, it is Ready.

  7. In the Vendors section, select whether the integration should synchronize XTRF Vendors to QuickBooks by checking or unchecking the Synchronize Vendors box. If you choose to synchronize vendors, additional settings appear:

    1. In the For Vendor Invoices Use QB Item Name Expression field, set up the way the Vendor invoice items are created in QuickBooks. By default it is ${item.activityType.name}.
      Note: This option is not available if you select XTRF Payables/Receivables in the Add QB Invoice Items Based on field.

    2. In the For Vendor Invoices Use QB Item Description Expression field, set up the way the Vendor invoice items are created in QuickBooks. By default it is ${item.displayName}.

    3. In the For Vendor Invoices Use QB Default Item Name field, enter a proper expression. By default, it is providerItem.

    4. In the Synchronize when Vendor Invoice Status is field, choose the first status of a Vendor Invoice in XTRF that will trigger the invoice transfer and synchronization to QuickBooks. By default, it is Confirmed.

  8. Click the Save button at the bottom of the page.

  9. Scroll up to the General Settings and click the Periodic Job button.

    Or 

    In the Configuration Menu on the left, choose Integration > Periodic Jobs.

  10. Click the Add button on top of the Periodic Job list to create a new entry. An Add page opens.

    • In the Type field, select QuickBooks Online Synchronization from the drop-down list.

    • Click the Save button. A Periodic Job configuration page opens.

  11. On the Periodic Job page:

    1. In the Execution Configuration section, set up when and how often the synchronization should be performed.
      Note: Once the synchronization is performed, you will be able to see the statistics and logs in the Job Statistics section.

    2. Click the Run Periodically button at the bottom of the page.

Your XTRF Platform is now ready to synchronize with QuickBooks Online.

In QuickBooks integrator, colon (:) has a special meaning: it is used as a separator for hierarchic structures in QB.

IMPORTANT!

Do not use QB Category names as item descriptors, as this will disrupt the synchronization.


Field Mapping between QuickBooks Online and XTRF

Client

Client in XTRF is mapped with Customer in QBO. Their names must be unique across the whole system, not only among clients but also among vendors.

QuickBooks field name

XTRF field name

Field length limit

Comment

DisplayName

customer.name 

500

 

Active

 

 

true if the client is not in state "Inactive" in XTRF

CompanyName

customer.fullname

100

 

BillAddr

customer.address.*

 

see Address mapping below

ShipAddr

customer.address.*

 

see Address mapping below

PrimaryPhone

customer.phone

30

 

PrimaryEmailAddr

customer.email

 

 

CurrencyRef

 

16 

currency from price profile mapped into QuickBooks currency

Vendor

Vendor in XTRF is mapped with Vendor in QBO. Their names must be unique across the whole system, not only among vendors but also clients.

QuickBooks field name

XTRF field name

Field length limit

Comment

DisplayName

provider.name

500

 

Active

 

 

true if the vendor is not in state "Inactive" in XTRF

CompanyName

provider.fullname

100

 

BillAddress

provider.address.*

 

see Address mapping below

PrimaryPhone

provider.phone

 

 

PrimaryEmailAddr

provider.email

 

 

CurrencyRef

 

 

currency from price profile mapped into QuickBooks currency

Client Invoice

Client Invoice in XTRF is mapped into Invoice in QBO.

QuickBooks field name

XTRF field name

Field length limit

Comment

CustomerRef

customerInvoice.customer

 

 

TxnDate

customerInvoice.finalDate

 

 

DocNumber

customerInvoice.finalNumber

21

 

BillAddr

customerInvoice.customerAddress.*

 

see Address mapping below

ShipAddr

customerInvoice.customerAddress.*

 

see Address mapping below

SalesTermRef

termsQB

 

see Payment terms mapping below

DueDate

customerInvoice.requiredPaymentDate

 

 

Invoice lines

customerInvoice.invoiceItems

customerInvoice.tasks.receivables

 

see Client Invoice Items or Receivables mapping below

Client Invoice Items

To choose this method of synchronization, select the XTRF Invoice Items in the Add Invoice Items Based on field (see Configure XTRF step 4.e.).

QuickBooks field name

XTRF field name

Field length limit

Comment

Name

For Customer Invoices Use QB Item Name Expression

100

Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., item:subitem:subsubitem in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem").

Each of the items/subitems can be up to 31 characters long. 

Description

customerInvoice.id customerInvoiceItem.id customerInvoiceItem.name

4000 

first 4000 characters of item.name

Qty

customerInvoiceItem.quantity

 

 

UnitPrice

customerInvoiceItem.rate

 

converted into QB currency

Receivables

To choose this method of synchronization, select the XTRF Payables/Receivables in the Add Invoice Items Based on field (see Configure XTRF step 4.e.).

QuickBooks field name

XTRF field name

Field length limit

Comment

Full Name

For Client Invoices Use QB Item Name Expression

31

Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., item:subitem:subsubitem in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem").

Each of the items/subitems can be up to 31 characters long. 

Description

For Client Invoices Use QB Item Description Expression

4000

 

Qty

receivable.quantity

 

 

UnitPrice

receivable.rate

 

converted into QB currency

Vendor Invoice

Vendor Invoice in XTRF is mapped into Bill in QuickBooks.

QuickBooks field name

XTRF field name

Field length limit

Comment

VendorRef

providerInvoice.provider

 

 

TxnDate

providerInvoice.finalDate

 

 

DueDate

providerInvoice.requiredPaymentDate

 

 

DocNumber

providerInvoice.finalNumber

21

 

PrivateNote

providerInvoice.invoiceNote

4000

 

Lines

providerInvoice.activities

providerInvoice.activities.payables

 

see Invoice items mapping below

It is possible to choose between using activities and payables data.

SalesTermRef

termsQB

 

see Payment terms mapping below

Vendor Invoice Items

To choose this method of synchronization, select the XTRF Invoice Items in the Add Invoice Items Based on field (see Configure XTRF step 4.e.)

QuickBooks field name

XTRF field name

Field length limit

Comment

Full Name

For Provider Invoices Use QB Item Name Expression

31

Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., item:subitem:subsubitem in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem").

Each of the items/subitems can be up to 31 characters long. 

Description

For Provider Invoices Use QB Item Description Expression

4000

 

Qty

always set to 1

 

 

UnitPrice

activity.totalAgreed

 

converted into QB currency

Payables

To choose this method of synchronization, select the XTRF Payables/Receivables in the Add Invoice Items Based on field (see Configure XTRF step 4.e.).

QuickBooks field name

XTRF field name

Field length limit

Comment

Full Name

For Vendor Invoices Use QB Item Name Expression

31

Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., item:subitem:subsubitem in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem").

Each of the items/subitems can be up to 31 characters long. 

Description

For Vendor Invoices Use QB Item Description Expression

4000

 

Qty

payable.quantity

 

 

UnitPrice

payable.rate

 

converted into QB currency

Address

QuickBooks field name

XTRF field name

Field length limit

Line1

*.address.address

500

Line2

*.address.address2

500

City

*.address.city

255

Country

*.address.country.name

255

CountrySubDivisionCode

*.address.province

255

PostalCode

*.address.zipCode

30

Payment Terms

QuickBooks field name

XTRF field name

Field length limit

Name

terms.displayName

31

DueDays

terms.dueDays

 

Taxes

Tax Rates names in XTRF must be manually configured to comply with QBO Tax Codes. 

XTRF client and vendor invoices are sent to QBO, and Tax Code is applied automatically per item, not per total.