/
QuickBooks Desktop integration setup

QuickBooks Desktop integration setup

Introduction

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


Configure XTRF 

  1. Sign in to the XTRF Home Portal.

  2. Go to Configuration Menu → User Management → Users.

  3. Click the Add button on top of the list of users.  You need to create a new user for the purposes of the integration. Make sure that this user is given the rights to create and modify Clients, Vendors, and their Invoices. Also, ensure the user has an allocated license and can always log in to XTRF. To find out how to give users specific rights, see the User Groups and Rights article.

  4. Go to Integration → Quick Books.

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

  6. Check the QuickBooks Integration Enabled box. The settings menu expands.

  7. In the General Settings section:

     

    1. In the QuickBooks will Sign into XTRF as field, select the user you have created for the integration.

    2. Choose the Main Currency in your QuickBooks Installation.

    3. In the Synchronize Items Newer than field, set up the desired date of the first synchronization. This field will be updated automatically each time the synchronization occurs.

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

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

  8. In the Clients section, select whether the integration should synchronize XTRF Clients and Projects to QuickBooks by checking or unchecking Synchronize Clients and Synchronize Projects as QB Jobs boxes. If you choose to synchronize clients and projects, additional settings appear:

     

    1. In the QB Job Name Expression field, set up the way the Client Jobs are created in QuickBooks. By default, it is ${project.idNumber}.

    2. 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}.
      This option is not available if you select XTRF Payables/Receivables in the Add QB Invoice Items Based on field in step 7.d. of this guide.

    3. 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}.

    4. 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}.

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

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

  9. In the Vendors section, select whether the integration should synchronize XTRF Vendors by checking or unchecking the Synchronise 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}.
      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.

  10. Once you are done, click the Save button at the bottom of the page.

  11. Go to the QWC File Generation tab. Here you can generate a .qwc file that you will need to use later in the QuickBooks Web Connector.

     

  12. Click the Generate button to generate the .qwc file. Save the file on your local drive.

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.

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.


Configure QuickBooks 

QuickBooks Web Connector

To integrate your QuickBooks Desktop with XTRF, you first need to install the QuickBooks Web Connector provided by the developer of QuickBooks. It is a software application that runs on Microsoft Windows and enables specially designed web-based applications to exchange data with QuickBooks products. For more information, see the Get started with QuickBooks web connector article.

  1. Run the QuickBooks Web Connector software and open the .qwc file generated by XTRF.

  2. If asked, authorize XTRF to access QuickBooks.

  3. In the Password field, enter the password of the XTRF user created for the integration (see Configure XTRF step 3).

    •  Click Yes if asked if you would like the password to be saved.

  4. Check the box on the left of the XTRF application and click the Update Selected button to run the initial synchronization.

Your QuickBooks application and XTRF are now integrated.

See also: SSL Certificate Installation.


Field Mapping between QuickBooks Desktop and XTRF

Client

Client in XTRF is mapped into Customer in QuickBooks. 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

Name

customer.name

41

 

IsActive

 

 

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

CompanyName

customer.fullname

41

 

BillAddress

customer.address.*

 

see Address mapping below

ShipAddress

customer.address.*

 

see Address mapping below

Phone

customer.phone

21

 

Email

customer.email

1023

 

CurrencyRef

 

 

currency from price profile mapped into QuickBooks currency

Vendor

Vendor in XTRF is mapped into Vendor in QuickBooks.

QuickBooks field name

XTRF field name

Field length limit

Comment

Name

provider.name

41

 

IsActive

 

 

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

CompanyName

provider.fullname

41

 

VendorAddress

provider.address.*

 

see Address mapping below

Phone

provider.phone

21

 

Email

provider.email

1023

 

CurrencyRef

 

 

currency from price profile mapped into QuickBooks currency

Client Invoice

Client Invoice in XTRF is mapped into Invoice in QuickBooks.

QuickBooks field name

XTRF field name

Field length limit

Comment

CustomerRef

customerInvoice.customer

 

 

TxnDate

customerInvoice.finalDate

 

 

RefNumber

customerInvoice.finalNumber

11

 

BillAddress

customerInvoice.customerAddress.*

 

see Address mapping below

ShipAddress

customerInvoice.customerAddress.*

 

see Address mapping below

TermsRef

terms

 

see Payment mapping below

DueDate

customerInvoice.requiredPaymentDate

 

 

Memo

For client invoices use Description Expression

4095

 

Invoice Lines

customerInvoice.invoiceItems

 customerInvoice.tasks.receivables

 

see Invoice item 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 7.d.).

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. 

Desc

For client invoices use QB Item Description Expression

4095

 

Quantity

customerInvoiceItem.quantity

 

 

Rate

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

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. 

Desc

For client invoices use QB Item Description Expression

4095

 

Quantity

receivable.quantity

 

 

Rate

receivable.rate

 

converted into QB currency

Vendor Invoice

Vendor Invoice in XTRF is mapped into Bill in QuickBooks.

<