Package Setup

Firstly, it is necessary to install the QuickBooks package into the client's org - contact the Seven20 Product team to obtain the link for the latest package version. Seven20's QuickBooks package is dependent on the following core product packages:

• Seven20 - Utilities
• Seven20 - Core
• Seven20 - Billing

Assign User Permissions

• Assign the packaged QuickBooks Configuration (QuickBooks_Configuration) Permission Set to any System Administrator who will be involved in setup and configuration
• Assign the packaged QuickBooks User (QuickBooks_User) Permission Set to any User who will be using the integration
• Users will also need to be assigned additional permissions for External Credential Principals that get created during package setup. For more information, see Set up the credentials in Salesforce and Create a Permission Set for External Credentials

danger

Any users who should not be sending data to QuickBooks should:

• Not have permission to edit the field seven20__Billing__c.seven20__Send_To_QuickBooks_Status__c
• Not have permissions for External Credential Principal Access

warning

Users assigned the Permission Sets above will have access to all of the integration's functionality. Finer control of user access to the integration requires additional configuration

Connect a QuickBooks developer app

Create the QuickBooks app

• Navigate to the QuickBooks Developer site and sign in (or sign up)
• Navigate to the Dashboard tab and create a new App and complete the fields on the page
  • For the API, select com.intuit.quickbooks.accounting
  • Sandbox: access the Client ID and Client Secret in the Keys & Credentials page
  • Production: complete the necessary pre-requisites on the Keys & Credentials page to access the Client ID and Client Secret
  • Keep the tab with the keys open as we will need them in a later step

Set up the Auth. Provider in Salesforce

• In Salesforce setup navigate to Auth. Providers and create a new record with the values below:

Auth. Provider Field	Value
Provider Type	Open ID Connect
Name	QuickBooks
URL Suffix	QuickBooks
Consumer Key	Return to the QuickBooks configuration tab, copy the Client ID and paste the value in this field
Consumer Secret	Return to the QuickBooks configuration tab, copy the Client Secret and paste the value in this field
Authorize Endpoint URL	https://appcenter.intuit.com/connect/oauth2
Token Endpoint URL	https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
Default Scopes	com.intuit.quickbooks.accounting openid profile email phone address
Send access token in header	Checked
Include Consumer Secret in SOAP API Responses	Checked

Update the Redirect URIs in QuickBooks

• Under Salesforce Configuration for the newly created record find and copy the Callback URL
• Return to the QuickBooks configuration tab and add the value under Redirect URIs
• Save the changes

Set up the credentials in Salesforce

info

If connecting to multiple QuickBooks companies the below steps must be completed once for each Company. Take care to label and name records appropriately to make them identifiable.

• With the Auth. Provider created, an OAuth 2.0 external credential must now be created
• Follow the Salesforce guidance here using the configuration specified below:

External Credential Field	Value
Label	Appropriate name relating to the QuickBooks Company this will be connected to
Name	Appropriate name relating to the QuickBooks Company this will be connected to
Authentication Protocol	OAuth2.0
Authentication Flow Type	Browser Flow
Authentication Provider	Select the Auth. Provider created above, QuickBooks

• Configure and authenticate a Principal with the below configuration

Principal Field	Value
Parameter Name	QuickBooks
Sequence Number	1
Identity Type	Named Principal

• The authentication process will launch a browser flow where the user must sign into QuickBooks and select the relevant Company for the integration to access

  info

  Ensure the Principal has been authenticated following the steps in the Salesforce documentation

• Follow the Salesforce guidance to create a named credential with the below configuration:

Named Credential Field	Value
Label	Appropriate name relating to the QuickBooks Company this will be connected to
Name	Appropriate name relating to the QuickBooks Company this will be connected to
URL	For production: https://quickbooks.api.intuit.com For sandboxes: https://sandbox-quickbooks.api.intuit.com
Enabled for Callouts	Enabled
External Credential	Select the External Credential created above
Generate Authorization Header	Checked
Allowed Namespaces	seven20

Create the Quickbooks Company in Salesforce

In order to associate the Named Credentials with a Company in Quickbooks, it is necessary to create a QuickBooks Company (seven20__QuickBooks_Company__c) record - in Seven20 navigate to the QuickBooks Company tab and create a new record with the below configuration:

QuickBooks Company Field	Value
Name	Appropriate name relating to the QuickBooks Company this will be connected to
seven20__Named_Credential_API_Name__c	API Name of the Named Credential created above
seven20__QuickBooks_Id__c	The Id of the company in QuickBooks*. QuickBooks provide instructions on where to find this here

caution

*The company Id must be entered as a continuous string of digits. Remove any spaces present in the id. The following are examples of an incorrect and correct format for the Id (the actual id may have more or less characters than in the examples):

• XXXX XXXX XXXX XXXX XXXX ❌
• XXXXXXXXXXXXXXXXXXXX ✔️

Create a Permission Set for External Credentials

Create a new permission set called QuickBooks_External_Credentials

• Enable access to the external credential principles
  • On the permission set, select the settings for External Credential Principal Access
  • Enable all the Principals relating to the Named Credentials just created
• Assign Read permissions for the User External Credentials Object
  • On the permission set, select the Object Settings
  • Navigate to User External Credentials
  • Enable Read permissions
• Assign this Permission Set to all users who will be using the integration

Retrieve Tax Codes and Items

In order to correctly populate Tax Code and Item fields when sending Billing Items to QuickBooks it is necessary to retrieve the underlying Ids for the Tax Codes and Items from each Company in Quickbooks - navigate to the Developer Console and run the below commands in an Execute Anonymous window:

seven20.RetrieveQuickBooksTaxCodesBatch.retrieveTaxCodes();
seven20.RetrieveQuickBooksItemsBatch.retrieveItems();

Set up the Webhook

Create a Site in Salesforce

• In Salesforce setup create a site and copy the created site's URL - this will be needed within Quickbooks
• Assign the below Permission Sets to the guest site user:
  • QuickBooks Guest Site (QuickBooks_Guest_Site)
  • QuickBooks External Credentials (QuickBooks_External_Credentials)

Configure the Webhook in QuickBooks

• Return to the QuickBooks developer app and navigate to Webhooks
• In Endpoint URL paste the Salesforce site's URL appended with /services/apexrest/seven20/quickBooksEvent
• Under Event triggers select Create and Update for BillPayment and Payment
  • Ensure all other Event triggers are deselected - only those listed here are necessary for the integration
• Save the changes
• Copy the Verifier Token
• In Salesforce setup navigate to Custom Metadata Types and select Seven20 Configuration Setting
• Navigate to the QuickBooks Webhook Key metadata record
• Paste the copied token into the Value field and save the record

Setting up multiple currencies

If multiple currencies will be used when sending invoices, they must be enabled in QuickBooks.

danger

Sending a currency from Seven20 that has not been configured in QuickBooks will cause a failure.