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.
     
     

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

   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. In the Periodic Job page:
    
    
    
    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.

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.

Client Invoice

Client Invoice in XTRF is mapped into Invoice in QBO.

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

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

Vendor Invoice

Vendor Invoice in XTRF is mapped into Bill in QuickBooks.

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

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

Address

Payment Terms

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.