Troubleshooting the Salesforce CRM Integration with Epicor CPQ

If you discover problems with the integration to salesforce.com, here are some of the first things to try.

Setup-related issues

Did you follow the setup steps, but still encounter problems? Confirm these steps. 

1. Confirm the integration user account can login through the salesforce UI

Can you manually log in as your integration user at the URL https://login.salesforce.com with that integration account's username and password? 

2. Confirm the integration user account security settings are completed in salesforce

Let's say you can successfully log in as the integration user manually.  When you do log in, does salesforce ask you to complete any security measures for the account?  For example, does it ask you for a cell phone number, to set up 2-factor authentication?  If your company uses this (like many do), and you've filled in the "mobile phone" field on the integration user, you'll need to either...

• ...perform that step to complete 2-factor authentication for the integration user while logging in through the UI, or
• ...add the integration user to a permission set that a) turns off "Two-Factor Authentication for User Interface Logins", or b) defines an allowable IP Range.

Simply ignoring that 2-factor setup on the integration user when prompted is not an option.  Eventually an internal salesforce grace period will time out, and the integration won't work any more until you either complete the 2-factor authentication setup, or turn it off for this user.

3. Ensure you grant your integration user the necessary permissions in salesforce

As stated in the setup instructions, we suggest you grant your integration user 2 permissions for reliability and to future-proof it for deeper integrations you may build tomorrow.  Review the setup instructions to learn why we suggest you consider granting the "Password Never Expires" and "Modify All Data" permissions.  Each organization is different, so work with your salesforce administrator to discuss these options.

4. Review the logs in Epicor CPQ for useful information

If Epicor CPQ encounters errors during any salesforce integration, the APEX error message is written to the Server Logs for administrators to see, as well as in the log on the quote itself for your users to see, as in the example below.  This screenshot shows the Epicor CPQ page within the salesforce UI of our standard CRM integration, the history log visible after this user clicked "submit" on their quote, and a salesforce APEX error message within that history log. 

User experience-related issues

Is your integration working, but some users complain of problems? Try these suggestions.

5. Note that some stand-alone features are not shown when integrated.

On quotes not synchronized with salesforce.com, a delete button is shown on the quote page when it is displayed to users with sufficient rights to delete the quote.  However, once synchronized with Salesforce, that button is no longer displayed.  This helps maintain the synchronization between the two systems.  If you want to delete a quote that is in synch with salesforce, then use the salesforce native UI to do so.

6. Submitting a quote results in "Error synchronizing KBMax Customer with Account on Opportunity ID 006xxxxxxxxxxx"

Ensure your users in Epicor CPQ who use the salesforce integration have the permission to modify customers.  Specifically:

1. In Epicor CPQ, log in as a company administrator.
2. In the administrative interface, browse to Users and Roles > Users.
3. Look up the user who reported this error: note the roles this user has.
4. In the administrative interface, browse to Users and Roles > Permissions.
5. In the list of permissions, scroll to the "Modify Customers" permission.  Ensure that at least one of the roles you noted in step 3 is listed next to this permission.

For example, if users from SFDC are auto-assigned a role called "Salesperson", ensure that role is assigned to the "Modify Customers" permission.

Confirm your users' browsers allow 3rd-party cookies

If your users are launching salesforce.com directly or through a "Communities" portal, and then use the embedded Epicor CPQ interface to configure a product, these two systems must be able to share information in the user's web browser.  The foundation for that sharing is allowing 3rd-party cookie use.  If that is not allowed, your users may not be able to launch Epicor CPQ components from their salesforce.com session.

To ensure the correct settings, follow these steps:

For Chrome

1. Open Settings.
2. Search for "Content Settings", and open that page. 
3. On the "Content Settings" page, click the link "Cookies". 
4. On that page, ensure that the setting "block third-party cookies" is turned off. (The slider is grey, and to the left, as shown here.  Not in color and to the right.)
   

For Firefox

1. Open Options
2. Search for "cookie"
3. Next to "accept third party cookies", ensure either "always" or "from visited" is selected.
   

For Safari on Mac and iOS devices

1. Choose Safari > Preferences
2. click Privacy
3. Select a “Cookies and website data” option "Always Allow"

For Microsoft Edge

1. Click Settings
2. Click "View Advanced Settings"
3. Ensure "Don't Block Cookies" is set.
   

These are the simplest ways to allow the browser-side integration between salesforce and Epicor CPQ.  If your corporation does not allow you to adjust these settings, consult your IT department's help desk on other options, such as allowing third-party cookies for these sites specifically, or adding these sites to your browser's "trusted sites" list.

Custom integration-related issues

If the standard setup of Epicor CPQ in Salesforce is working, but your custom integrations or web service requests aren't, try these suggestions.

Increase the timeouts on your web service callouts

One of the strengths of Epicor CPQ is our API: just about everything you can do as a user in Epicor CPQ you can also do through web services.  You may be calling the Epicor CPQ web service from salesforce.com through salesforce's HttpRequest class. By default, this class has a short timeout of 10 seconds (for synchronous calls) or 30 seconds (for asychronous calls).  Try increasing the timeout in salesforce to resolve intermittent problems.  

Confirm any custom theme

When setting up this integration, the Canvas App URL parameter accepts an optional parameter to specify a custom theme This parameter is rarely used, but if you chose to, please refer to a theme ID number that actually exists in your org. Otherwise the console will show an error.

For example, if you use the following as your canvas app URL:
https://subdomain-environment.kbmax.com/sfdc?idtheme=3
And testing the integration shows this error in the console:
Cannot read properties of undefined (reading 'skin')  
Then you do not have a theme with ID of 3 in your org. Just remove the parameter to get it working with the default theme. You can play with themes later:
https://subdomain-environment.kbmax.com/sfdc

Configurator design-related issues

The Epicor CPQ platform is flexible, allowing you to build just about anything.  As you integrate your Configurators with Salesforce, here's a checklist of design modifications you might have overlooked.

Ensure your nested configurators are nesting price objects correctly

If you have a child configurator which has no pricing rules (because it has no price items), be sure that you disable the "nest price items" option off when you create the relationship in the parent configurator.  By default this option is on.  For example, you may have a parent configurator (a "Room" configurator) which has child configurators inside purely for display reasons (say a child "Sofa" or "Table" configurator which you use to help visualize the size of the room.  These child configurators have no price items.)  In your "Room" parent, when you create "Referenced Configurator" entries to connect the Sofa and the Table as children, turn off "Nest price items" in those references.  There are no child price items to nest.