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. 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 RemovedImage Added

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.

Expand
title App assessment questionnaire - expand
General Questions App Information Authorization and Authentication API Usage Error Handling Security

Configure XTRF 

1. Sign in to the XTRF Home Portal.

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

   Image RemovedImage Added

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

   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.

    Image RemovedImage Added

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

    Image RemovedImage Added

    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.

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 (see Configure 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.