Skip to main content
Gainsight Inc.

Onboarding Step 1: Install Gainsight & Configure


This article helps you to learn about how to install and onboard Gainsight application which is written on the Salesforce (SFDC) platform and into your current Salesforce instance.

IMPORTANT: You can install and initialize Gainsight only if you are a full SFDC Administrator.


Gainsight can be installed into the following Salesforce editions:

  • Developer Edition
  • Enterprise Edition
  • Higher Editions that have recently released

IMPORTANT: Contact your Project Manager to receive the package password that will be required during installation and when upgrading to new versions of Gainsight.  

Operating System and Browser Compatibility

In terms of operating systems, Gainsight supports whatever Salesforce supports when it comes to the browser compatibility.


Chatter is a prerequisite for installation. Chatter will be required in order to install Gainsight into Salesforce.
Note: Once Chatter is enabled, it cannot be disabled as Gainsight’s internal components refer to chatter components.

Install Gainsight

This section describes how to install Gainsight in your Salesforce environment. After you install Gainsight, you learn how to assign a Gainsight licence to one or multiple Salesforce users. Gainsight application is written on the Salesforce platform and installs into your current Salesforce instance.Someone with a full Salesforce administrator profile must install and initialize Gainsight.

To install Gainsight from AppExchange,

  1. Navigate to Salesforce’s AppExchange at the top-right of Salesforce as shown in the following image.

2-Salesforce’s AppExchange.png

  1. Search for Gainsight and download.


  1. Click Get it Now.

4-Get it Now.png

  1. Choose to Log in to the AppExchange and use your Salesforce credentials.


    5. Enter your Salesforce credentials and click Log In.


6. You return to the Appexchange page. Click Get it Now.

7-Get it Now.png

7. Select either Install in Production, or  Install in Sandbox option.

8-Install in Production.png

8. Review what you are installing and where you are installing. Scroll Down to Confirm installation Details section and click Edit Profile

9-Edit Profile.png

9. Enter your details and click Save, in the Edit Profile window.


10. Select the Terms and Conditions checkbox and click Confirm and Install.

11-Confirm and Install.png

11. Enter the package password that (you already received from your Project Manager).

12. Select the appropriate option from the ones described below.  
There are 3 options to choose from when determining the security level that will be used during installation and when upgrading to new versions of Gainsight:

  • Install for Admins Only - Users with your profile get full access This is the Gainsight recommended option. Use this option if you want all SF Admins to have full access to Gainsight, in the event a Gainsight License is assigned to that user. When you’re ready to give other users access, you will do so by editing the profile or assigning permission sets.
  • Install for All Users - All internal custom profiles get full access This is not recommended by Gainsight. Use this option if you want all users who are assigned to a custom profile to have full access to Gainsight, in the event a Gainsight License is assigned to that user.
  • Install for Specific Profiles - Not recommended for most packages; discuss with your Gainsight representative.


13. Click Install.


  • In some cases, the installation can be delayed and the following screen is displayed. Click Done.

  • When the installation is complete, you receive an email to confirm the same.


Best Practices:

  • When installing Gainsight, the Salesforce users who will be assigned Gainsight licenses will need to be granted Salesforce-level permissions along with the licenses.
  • Although the Salesforce Admin has the option to permission entire profiles (or even every Salesforce user), Gainsight recommends enabling for Admins only during installation.
  • Permission sets are then used to grant permissions to only the appropriate Salesforce users regardless of user profile. See Gainsight & SFDC Permission Sets for further detail.

Configure Gainsight

Perform the following steps to configure Gainsight,

  1. At the top of Salesforce, click Setup.
  2. On the left side under Build, click Installed Packages.
  3. Next to Gainsight CSM, click Configure.


  1. Click INITIALIZE.

  1. After the below screen appears, close the screen.



Add Users

Once Gainsight is installed, we need to activate your licenses. Please email your SFDC production ID to to request license activation.

Note: This step is not necessary in Sandbox.

Perform the following steps to add users:

  1. Click Setup in the top right.
  2. Type Install in the quick find and click on Installed Packages.
  3. Next to Gainsight CSM, click Manage Licenses.

19 add users.gif

      By default, the user who installed Gainsight is assigned a license. This screen shows the number of Allowed Licenses and number of Used Licenses.

  1. Click Add Users to assign the remaining licenses.
  2. Check the names of the users you want to assign.
  3. Click Add.


  • Admins may also need to add permission sets for some users in order for them to see the Gainsight app in their menu.

  • If your organization uses the Gainsight Survey module, and creates a survey site in Salesforce, a license will be assigned to the survey user. This license is used only for survey site setup and does not have an associated cost. The survey license will, however, be added to your organization's total number of purchased licenses on the Gainsight Licenses page.

Enable and Authorize MDA

As an SFDC Admin, you will leverage Gainsight’s powerful Rules Engine to move data into the Gainsight object structure, and evaluate positive and negative trends in behavior.  As part of your implementation you will also learn how to use Gainsight’s Email Service or your existing Marketo implementation to easily communicate with key contacts. The first step to leveraging these tools is to authorize the Integrations to connect to your Gainsight instance in Salesforce.

Best Practice:

The Salesforce User authorizing your integrations will need access to all Objects and Fields that may be used or referenced in Gainsight. If your organization has a systems or integrations user already provisioned in Salesforce, which will never expire and has a System Administrator Profile, we would recommend using that User to authorize the Gainsight integrations.    

Before you begin the data integration step, ensure that the Matrix Data Architecture (MDA) Settings are enabled from Administration > Operations > MDA Services. . You can access this page by navigating to the Administration tab within Gainsight.

For more information about MDA, refer to the Gainsight Matrix Data Architecture Overview article.

20-Enable MDA.gif

Note: If you do not see the Administration tab, at the top of your instance, you can click the “+” button and find “Administration” there. You can also customize your tabs in that view, as shown below.

A-customize your tabs.gif

Perform the following steps to authorize MDA.

  1. Navigate to the Administration tab.
  2. Click on Connectors, located under the Operations sub-header as shown below. This will take you to the Integrations tab.


Note: If you are experiencing issues with this page loading, please contact Gainsight Support (

Once in the Integration/Connectors tab, activate the Authorize MDA switch. Then authorize Gainsight MDA to use your Salesforce data by clicking on "Authorize". For more information, refer to the Authorize Matrix Data Platform (MDA) article.

  1. Click Allow.

4. Click Close when the window below displays:

Once Gainsight Matrix Data Platform is authorized, you will have the option to turn on and configure the following:

Verify OAuth Authorization

Perform the following steps to verify the OAuth authorization.

  1. Click Setup.
  2. Type ‘OAuth’ in the Quick Find field.
  3. Click Connected Apps OAuth Usage under Manage Apps.
  4. Confirm the Gainsight App is listed and click on the User Count number. From here, you can see who authorized the app and when.

24-OAUTH authorization.gif

Add External Sites in Remote Site Settings

Salesforce would make calls to an external (remote) site and accept responses only if it is known and trusted. While Gainsight application already knows to trust and makes calls to Gainsight's MDA, Gainsight has few application areas that call MDA via Salesforce. For all these functions to work correctly and for SFDC to trust MDA, you need to add as Remote Site.

An admin can add a site to Remote Site setting so that Salesforce can start trusting it. For more information about SFDC Remote Site Settings, refer here.

Following are the steps to create a new Remote Site:

  1. Navigate to Setup > [Enter Remote Site Settings in the Quick Find box] > [Select Remote Site Settings].


  1. Click New Remote Site.


  1. Enter a descriptive term for the Remote Site Name.
    Note:  The name can only contain underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

  2. In the Remote Site URL field, enter the following site URLs for allow listing: 


  1. Optionally, enter a description of the site.

  2. Click Save.

Create and Assign Permission Sets

The Gainsight Admin, Gainsight Standard, JBCXM_GS_Permission, Gainsight Viewer, and Gainsight Special permission sets allow control over the visibility of Gainsight objects within Salesforce. These permission sets are included in the Gainsight managed package.

  • Gainsight Admin - This permissions set grants access to all Gainsight Objects (ViewAll, ModifyAll), Apex Classes and Visualforce Pages.
  • JBCXM GS Permission - Used to grant access to Gainsight objects that have a master detail relation with Account.
  • Gainsight Standard - This permission set grants access to all the Gainsight Objects (Read, Create, Edit, Delete), Apex Classes and Visualforce Pages except admin pages.
  • Gainsight Viewer - This permission set grants access only to Gainsight widgets on the Account and Opportunity detail view pages, for the Salesforce products, Service Cloud and Sales Cloud. This permission set grants read only permission on all the Gainsight objects.
  • Gainsight Special - This permission set grants access to the Rule Config page.

Best Practice:

It is recommended to assign users the following permission sets:

  • Gainsight Admin - Gainsight_Admin , JBCXM_GS_Permission
  • Standard User - Gainsight_Standard , JBCXM_GS_Permission
  • Viewer User - Gainsight_Viewer, JBCXM_GS_Permission

Note: If any of the above users should create rules, you should also assign them, Gainsight_Special permission set. Typically, Gainsight Admins need access to Rules Engine.

Perform the following steps to create and assign Permission Sets:

  1. Click Setup in the top-right corner.


  1. Type Permission Sets in the search bar.

  2. Click Permission Sets under Manage Users.

29- Permission Sets .png

  1. Click on the JBCXM_GS_Permission.
    Note: If you are in a Sandbox this might not be available, in that case you will need to first Clone the Gainsight_Admin permission set and name it JBCXM_GS_Permission.


  1. Click Assigned Apps.

  1. Click Edit.

  2. Move JBCXM.Gainsight from Available Apps to Enabled Apps.

  1. Click Save.

  1. Click the Permission Set Overview Dropdown list

  2. Select Visualforce Page Access.

  3. Click Edit.

  1. Move everything that starts with the JBCXM prefix from the Available Visualforce Pages column over to the Enabled Visualforce Pages column.

  2. Click Save.

  1. Click the Permission Set Overview dropdown again and select Apex Class Access.

  2. Click Edit.

  1. Move everything that starts with JBCXM from the Available Apex Classes column over to the Enabled Apex Classes column.

  2. Click Save.

  1. Click the Permission Set Overview dropdown and select Object Settings.

  1. In the search bar, search for the following, and select each of the objects from under the “Object Settings” header:

  • Customers - Click Edit and check the Visible box (this will automatically check the Available box). Then, click Save.

  • Gainsight - Click Edit, check the Visible box (this will automatically check the Available box). Then, click Save.
  • Cockpit - Click Edit, check the Visible box (this will automatically check the Available box). Then, click Save.
  • Journey Orchestrator - Click Edit, check the Visible box (this will automatically check the Available box). Then, click Save.
  • NPS® - Click Edit, check the Visible box (this will automatically check the Available box). Then, click Save.
  • Survey - There will be two. Click Edit on the bottom one. Check the Visible box (this will automatically check the Available box). Then, click Save.
  • Customer 360 - Click Edit, check the Visible box (this will automatically check the Available box). Then, click Save.
  • Customers Info - Click Edit, check every single field. Click the “Edit Access” check field, which will automatically fill in the “Read Access” field on each associated field name. For the fields where you cannot choose edit access, check mark Read Access. (This one will look different than the previous five.)

Grant Gainsight Support Login Access

This is an optional step in which you can give Gainsight temporary access to your Salesforce org. This will help us troubleshoot any issues you might come across as you are completing the pre-work.

Perform the following steps to grant Gainsight support login access.

  1. Navigate your Salesforce administrator to the Salesforce User Menu > click My Settings .

  2. Navigate to Personal > Grant Account login access

  3. Grant your administrator or support personnel the ability to login as you and access your data.
    Note: You can decide the Access Duration.

39-grant Gainsight support login access.gif

Create Test Records

During onboarding, a series of business tasks and processes are performed.  In order to test your configuration and help you see the functionality in action, Gainsight recommends you to create the following test records in your Salesforce environment:

  • 1 Account
  • 3 Contacts with email addresses that you can access
  • 1 Contact for each Gainsight Implementation Team Member
  • 2 Closed Cases / Zendesk Tickets
  • 1 Open Case / Zendesk Ticket

Best Practice:

Create a new account record clearly labeled as a test that includes all of the same values as found with a standard client. Ensure that the three valid contact e-mail addresses are all internal and accessible.

Session Security Settings (Optional) 

Although not required for Gainsight, it is recommended that you consider implementing the following settings for increased security.  

  1. Require HttpOnly attribute

  2. Use POST requests for cross-domain sessions

For more information, refer here.  Note that these settings can cause issues depending on your Salesforce environment, so thorough testing is recommended if you decide to enable these settings.  

42-Require HttpOnly attribute .png

Recommended articles

  1. Onboarding: Gainsight Prep Work Overview This article will walk you through all of the prep work that needs to be completed before you begin the Gainsight Implementation Process.

  2. Onboarding Step 2: Data Preparation Covers step 2 of the onboarding process: "Data Preparation".

  3. Onboarding Step 3: Business Processes Details the 3rd step of the onboarding process. This includes information of Business Process including downloading email templates, approving nps sur...

  4. Onboarding Step 4: Email Service Configuration (Allowing) Covers the topic of onboarding (step 4) regarding allow listing your domain, steps for allowing, and reputation score calculation as it pertains...

NPS, Net Promoter, and Net Promoter Score are registered trademarks of Satmetrix Systems, Inc., Bain & Company and Fred Reichheld.
  • Was this article helpful?