QuickBooks Online integration setup

This is an old version of the article. Please check the actual version in our new Knowledge Base.

QuickBooks Online integration setup

  • Configure QuickBooks Online
  • Configure XTRF
  • Field mapping between QuickBooks Online and XTRF

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. Go to https://developer.intuit.com/app/developer/myapps .
  3. Select your app or create a new one.
    • If you create a new app, in the Select a scope field, select both available options.

      Image 2419

  4. Go to Production > Keys & OAuth 2.0
  5. Copy Client ID and Client Secret to QBO configuration in XTRF (see the Configure XTRF step 4.a.)
  6. Add Redirect URI as https://your.XTRF.address.here/xtrf/seam/resource/qboauth/acceptToken, for example, https://acme.xtrf.eu/xtrf/seam/resource/qboauth/acceptToken
  7. Save the settings.

Configure XTRF

  1. Sign in to the XTRF Home Portal.
  2. Go to :ConfigurationMenu: Configuration Menu > Integration > QuickBooks Online.

    Image 2420
  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:

    Image 2421

    a. Provide theClient ID and the Client Secret from your QBOinstance.
    b. Choose the Main Currency in your QuickBooks Installation.
    c. 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.
    d. Select Branches for which the synchronization should take place.
    e. In the Add QB Invoice Items based on field, set up whether XTRF should send to QuickBooks Invoice Items or Payables/Receivables data.
    f. (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.
    g. (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).
    i. Click Connect to QuickBooks button. A pop-up window or a new tab appears:
        i. Sign in to QuickBooks Online.
       ii. Click the Authorize button.
    j. 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:

    Image 2422

    a. In theFor 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.
    b. 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}.
    c. 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}.
    d. In the For Client Invoices Use QB Default Item Name field enter a proper expression. By default, it is customerItem.
    e. 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:

    Image 2423

    a. 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.
    b. 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}.
    c. In the For Vendor Invoices Use QB Default Item Name field, enter a proper expression. By default, it is providerItem.
    d. 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.

    Image 2424

    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.

    Image 2425

    • In the Type field, select QuickBooks Online Synchronization from the drop-down list.
    • Click the Save button. A Periodic Job configuration page opens.
  11. In the Periodic Job page:

    Image 2427

    a. 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.

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

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

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

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

Note: XTRF Projects and QuickBooks Client Jobs are synchronized only one way, from XTRF to QuickBooks. If an XTRF Client Invoice contains tasks from only one project, it gets linked to the Client Job. QuickBooks bills are linked to Client Jobs too.

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

PrivateNote

For Client Invoices Use Description Expression

4000

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 (seeConfigure 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.

Note: It is not possible to send XTRF invoices to QBO when Tax Rate has no corresponding Tax Code found in QBO. Such invoices will not synchronize. Here is a sample error to be found in logs:
Error on processing request for entity with id: 61 com.radzisz.xtrf.integration.qb.exception.QuickBooksIntegrationReportableException: Cannot determine QB tax code id for XTRF tax name.

Integrations QuickBooks

This article was helpful for 3 people. Is this article helpful for you?