When setting up a new Salesforce integration with Coconut it is required to log in to the target Salesforce org and grant access for Coconut to make API requests to Salesforce using those credentials.
Coconut’s recommendation to customers is to create an ‘Integration User’ with which to perform this authentication. An ‘Integration User’ is a user within the Salesforce org that is not tied to an actual individual within the company, as that type of user may be subject to role changes or departure from the company altogether that could affect the account’s permissions in a way that interrupts the behaviour of the integration.
About Salesforce Licenses
Multiple different License types can be used to create this Integration User, but it’s critical to ensure that the correct permissions are granted in order for the integration to perform its tasks.
At the same time, it’s generally a good security practice to limit the permissions of an Integration User to only what is required, whenever possible. For example, the ‘System Administrator’ profile can be used, which would grant all the necessary permissions, however Coconut recommends using the ‘Salesforce Integration’ license, which is a license designed for system-to-system integrations, and does not consume a normal, more expensive user seat.
Note: With this license, permissions start off restricted and must be added manually.
About Permission Sets
A ‘Permission Set’ is a way to manage the permissions that get assigned to a user in a contained way. Permissions get added to the Permission Set, allowing you to then assign it to one or more users and grant those permissions to them.
Coconut’s managed package provides a Permission Set that can be used when configuring an Integration User to ensure that all of the correct permissions for the integration's functionality are captured.
It is also necessary to assign the ‘Salesforce Integration’ Permission Set License to the user, to ensure the Permission Set can be added correctly.
Steps to Create and Configure an Integration User
1. Create a Profile
A custom Profile ensures additional settings, such as default record types to use when creating Events, Leads, Contacts, or Person Accounts, can be configured for this user.
Navigate to your organization’s admin Setup area.
In the left-hand sidebar, search for and select the Users → Profiles page.
Click the New Profile button, and complete the form.
Select ‘Minimum Access - API Only Integrations’ as the Existing Profile to inherit from.
Give this new Profile an identifiable name, such as ‘Coconut Integration’.
Click Save when done.
Default Record Type for Organizations with ‘Person Accounts’ Enabled
If your Organization has the ‘Person Accounts’ feature enabled, and you plan to configure your Coconut integration to create or modify Person Account records, you will need to configure this profile to use the 'Person Account' record type as the default.
Navigate to the Edit screen for the Profile that you created.
Scroll down to the Account Record Type Defaults section.
Click Edit next to Person Accounts.
In the Available Record Types field, select ‘Person Account’ and then click the Add button to move it into the Selected Record Types field.
Ensure ‘Person Account’ is selected in both Default Record Type → Default and Business Account and Person Account Default Record Types → Person Account Default Record Type.
Click Save to confirm these settings.
2. Create a Permission Set
Coconut’s managed Permission Set only contains permissions related to Coconut’s own custom resources. You will need to create a Permission Set to assign other required permissions.
Navigate to your organization’s admin Setup area.
In the left-hand sidebar, search for and select the Users -> Permission Sets page.
Click the New button, and complete the form.
Enter an identifiable Label, such as ‘Coconut Integration API Access’.
API Name should automatically complete, but if not, repeat the label from above, replacing spaces with underscores (for example: ‘Coconut_Integration_API_Access’).
Description can be filled if desired, and all other fields should be left as their default values.
Hit Save to proceed to the next step.
Under System Permissions, click Edit, and then check the boxes for:
Access Activities
Approve Uninstalled Connected Apps
Modify All Data
Note, selecting this permission will automatically select a number of other pre-requisite permissions. This is expected, and necessary.
Click Save to confirm these changes.
Return to Permission Set Overview, and under Object Settings → Contacts:
Under Object Permissions select the Enabled checkbox for all values (Read, Create, Edit, Delete, View All Records, Modify All Records, View All Fields).
Under Field Permissions, click Edit, and then select ‘Edit Access’ in the header to apply to all available fields
Click Save to confirm these changes.
Return to Permission Set Overview, and under Object Settings → Leads:
Under Object Permissions select the Enabled checkbox for all values (Read, Create, Edit, Delete, View All Records, Modify All Records, View All Fields).
Under Field Permissions, click Edit, and then select ‘Edit Access’ in the header to apply to all available fields
Click Save to confirm these changes.
Return to Permission Set Overview, and under Object Settings → Events:
Under Field Permissions, click Edit, and then select ‘Edit Access’ in the header to apply to all available fields
Click Save to confirm these changes.
Permissions for Organizations with ‘Person Accounts’ Enabled
If your Organization has the ‘Person Accounts’ feature enabled, and you plan to configure your Coconut integration to create or modify Person Account records, you will need to assign additional permissions as well.
Navigate to the Permission Set Overview screen for the Permission Set that you created.
Under Object Settings → Accounts:
Under Account: Record Type Assignments, select the Assigned Record Types checkbox for ‘Person Account’.
Under Object Permissions select the Enabled checkbox for all values (Read, Create, Edit, Delete, View All Records, Modify All Records, View All Fields).
Under Field Permissions, click Edit, and then select ‘Edit Access’ in the header to apply to all available fields
Click Save to confirm these changes.
3. Create the User
Navigate to your organization’s admin Setup area.
In the left-hand sidebar, search for and select the Users -> Users page.
Click the New User button, and complete the form.
Set an identifiable name for the user. It’s common for an Integration User to have no First Name, and the name of the integration (such as ‘Coconut Integration’) in the Last Name field.
Select the ‘Salesforce Integration’ User License and for Profile select the custom Profile created in 1. Create a Profile.
Configure Email and check the Generate new password and notify user immediately fields to ensure you are able to access and generate a password for this user.
Click Save when done.
4. Assign Permissions
Navigate to the User Detail (not Edit) screen for the Integration User you created in Step 3: Create the User.
Scroll down to the Permission Set License Assignments section and click Edit Assignments.
Check the box for ‘Salesforce API Integration’
Click Save to confirm and return to the User Detail screen
Scroll down to Permission Set Assignments and click Edit Assignments.
Select ‘Coconut Integration Config’ and the custom Permission Set created in Step 2: Create a Permission Set in the Available Permission Sets multi-select, and click the Add button to move them into the Enabled Permission Sets field.
Click Save to confirm the assignment.
5. Set the User’s Password
Check the email address for the value you configured in Step 3: Create the User. This mailbox should receive an email with login information.
Click the link in the provided email to log in, and follow the flow to set or reset the user’s temporary password.
Once complete, you should be shown the screen shown below. You can close the window at this point.
Ready for Integration
At this stage, your Integration User should be configured with all the pre-requisite permissions to be able to be used to connect your Coconut Integration.