How to Reauthorise your Data Connector with Natterbox

A Natterbox support agent may inform you that there is an issue with your Data Connector or an API User.

Note: Please be aware that a deauthorised Data Connector/API User may lead to service failures such as missing call reports, an inability for the CTI to load, and failed calls. To restore full functionality, we advise reaching out to Natterbox Support immediately to have it re-authorised.

Permissions Required for the Data Connector / API User

The Data Connector is responsible for connecting the Natterbox Platform on our backend system to your Natterbox App within Salesforce.

Natterbox, like many other Salesforce applications, strongly recommends the API user being assigned System Admin permissions. This is to prevent issues as the Natterbox solution is heavily customisable and can interact with many objects and fields.

Should System Administrator access not be provided, the following will need to be granted at a minimum:

• API Enabled

• View all Custom Settings

• Customise Application

• Modify All Data

• Set Audit Fields upon Record Creation & Update Records with Inactive Owners - if users use Wrap- up functionality

The Natterbox permissions sets (NBVC Administrator and NBVC BasicUser) must also be assigned.

Furthermore, depending on the routing policies configured and desired call logging, modify access to the following objects is strongly recommended:

• Account

• Contact

• Case

• Lead

• Opportunity

• Task

Should any queries or DML be configured within the routing policies, the API user must also have access to the fields specified.

When making any future changes, it is important to note the custom permission limitations setup and impact this could have. Any changes are strongly recommended to be tested in a sandbox environment first

Here is a more extensive guide on the required permissions for data connector user.

Why Customise Application?

We use Salesforce Protected Custom settings for our API operation to store sensitive information and the API user will need modify access. Modify custom settings options is available for users with "Customize application" permission only.

Steps to Re-authorise

The support agent will request you to provide them with the name and email address of a Salesforce Administrator user within your Org.

Note: it is better if this user is also a Natterbox Administrator.

1. Once you have provided this information, the support agent will proceed to request the reauthorisation of the Salesforce Administrator as your Data Connector user.

2. The subsequent steps will need to be carried out by the designated Salesforce Administrator.

   1. They will receive an email from Natterbox, which will prompt them to authorise the Natterbox Platform to connect to their Natterbox App in Salesforce.

   2. Kindly advise the Salesforce Administrator to check their spam, junk, or similar email folders if they do not find the email from Natterbox.

   3. From the email, they will need to click the "Authorise" button or copy and paste the URL link provided at the bottom of the email into their browser.
      
      
      

   4. A separate page will open from Salesforce to confirm authorisation. Users are required to click the "Allow" button, which is highlighted in blue.
      
      
      

   5. Upon completion, the user should receive a notification confirming the successful authentication.
      

3. The subsequent steps must be carried out by a Natterbox Administrator, preferably the new Data Connector/API User.

   1. The user needs to navigate to the Admin Home tab within the Natterbox App in Salesforce.
      
      

   2. Within the "Admin Home" tab, users should navigate to the "System and Security" section and locate the "Scheduled Jobs" option.
      
      
      

   3. It is necessary to restart each scheduled job individually (see note below). This can be accomplished by selecting the blue "Stop Job" button adjacent to each scheduled job. This action will halt the selected scheduled job.
      Note: Each scheduled job will need to be stopped and restarted one at a time going down the list. Please only restart each scheduled job that is currently running.

      

   4. The user will need to wait for approximately ~10 seconds and then click on the button labeled "Start Job". This process should be repeated for each scheduled job individually.

Additional Steps for Swapping a User

If you are swapping over a Data Connector/API user and the previous user was not broken or inactive, you will need to do an additional step after the steps above. You can tell that this step is needed if all the other scheduled jobs are running in the new user but the call reporting is still being created with the old user.

1. Navigate to Salesforce Setup

2. Search for ‘Connected Apps OAuth Usage’ in quick find box

3. Look for Natterbox 01, and under User Count, if it shows more than 1, click on that number.
   
   

4. This will display the list of DC users

5. Click ‘revoke’ next to the user that is the old data connector user.
   
   

6. Now call reporting records should be created

Troubleshooting

Authorisation Fails With A Missing "code" Parameter Error

When you generate a new authorisation link to re-authorise or swap the Data Connector/API user, the authorisation can fail and display an error similar to the following, instead of completing successfully:

Error: "Failure – Request failed, the 'code' query parameter must be set."

Cause

This happens when the Natterbox 01 connected app in Salesforce is restricted to pre-authorised users and the user being authorised has not been granted access to it. In the OAuth Policies for the Natterbox 01 connected app, Permitted Users is set to "Admin approved users are pre-authorized".

With this setting, only users whose profile (or permission set) has the Natterbox 01 connected app assigned are allowed to authorise. If the authorising user's profile does not list Natterbox 01 under its Assigned Connected Apps, Salesforce blocks the authorisation callback before an authorisation code can be returned, producing the error above.

Resolution

1. In Salesforce Setup, open the OAuth Policies for the Natterbox 01 connected app and check the Permitted Users setting. If it is set to "Admin approved users are pre-authorized", continue with the steps below.

2. Open the profile assigned to the user being authorised and locate the Assigned Connected Apps section.

3. Add Natterbox 01 to that profile's Assigned Connected Apps. If connected app access is managed through permission sets in your Org, add it to the relevant permission set instead.

   

4. Generate and open a fresh authorisation link, then complete the authorisation again. It should now succeed without the missing "code" error.

Tip: Authorisation links are time-sensitive and expire quickly, so make sure the Salesforce Administrator is available and logged in when the link is generated, and complete the authorisation straight away.