Skip to content
English
More support Customer portal Sign in
Go to gathid.com
  • There are no suggestions because the search field is empty.

Salesforce - System Data Connector (API)

Getting started guide

Overview

 

Gathid can be configured to automatically download identity data from your Salesforce instance. This guide will help you configure your system so that Gathid can extract that data on a scheduled basis, without manual export and upload.

 The connector retrieves a list of Users (and, optionally, Profiles, Groups, Roles, and Permission Sets) from your Salesforce instance via the REST API. Authentication is performed using Salesforce's External Client App framework with OAuth 2.0. 

Version: This guide relates to version 7.7 of the Salesforce Data Connector.

Summary of steps

  1. Validate that the new Salesforce connector is available on your Gathid instance

  2. Create a new salesforce user with minimum privileges

  3. Create a new External Client app and obtain credentials

  4. Configure the Prep Script tab in the Salesforce System

1.  Validate the connector is available on your Gathid instance

  1. As an Administrator user, log into Gathid and navigate to Admin → Systems.

  2. You should see new Salesforce loader in the list, in a Disabled state. If it is not present, click Add System and select Salesforce. 

REMINDER: To be able to see Administration menu option you need to be in ADMINISTRATOR role.


2. Create a Salesforce user with minimum privileges

Gathid authenticates as a dedicated Salesforce user. Create one with the least privilege required for the data you intend to collect. 

  1. Login to your Salesforce instance as a user with sufficient privileges to create users.

  2. Create a New User from the  Administration → Users → Users.
    Example settings:

    Field Value
    First Name Gathid
    Last Name Integration
    Alias Gathid
    Email A monitored address on your organisation's domain (e.g. an IT distribution list) 
    Username gathid.integration@yourdomain.com
    Nickname gathidintegration 
    Role Can be left blank 
    Profile

    Minimum Access - API Only Integrations
    (see below) 

  3.  Set the Profile. Salesforce provides two Minimum Access profiles suitable for a least-privilege connector user: 

    • Minimum Access - API Only Integrations — recommended. Gathid only ever connects via the REST API and never needs interactive login, so this profile grants the least privilege and structurally removes UI sign-in as an access pathway.
    • Minimum Access - Salesforce — use this if the API Only profile is not available in your Salesforce edition.

    If neither Minimum Access profile is available, a Read Only profile can be used as a last resort, but it grants broader visibility than the connector requires.

  4.  If you plan to collect Profiles, Groups, Roles, or Permission Sets (configured later in Step 4), this user needs additional authorization. Grant it the View Setup and Configuration permission now. Skipping this is a common cause of optional data failing to collect. 

 Tip: Use naming that clearly identifies this as a non-human service account (owned by your organisation, on your domain), so it is easily recognised in user reviews and audits. The alias has an 8-character limit. 


3.  Create an External Client App and obtain credentials

Salesforce provides a framework called “External Client Apps” which allows a 3rd-party application (in this case, Gathid) to securely access your instance using OAuth 2.0 protocols. Further information can be obtain from their official documentation: Salesforce External Client Apps

Register the app

  1. Login to your Salesforce instance as a user with sufficient privileges to create a new External Client App.

  2. Navigate to Platform Tools → Apps → External Client Apps → External Client App Manager and create a new app. Suggested settings: 

Field Value
Name Gathid
API Name gathid
Email A valid, monitored address on your organisation's domain used to authorise the app
Enable and configure OAuth

Tick Enable OAuth and configure the following settings:

  • Callback URL: https://none.gathid.net
  • Selected OAuth Scopes: Manage user data via APIs (api)
  • Under Flow Enablement, enable Client Credentials Flow
  • Leave the Security settings as default

On the Policies tab:

  • Set the Start Page to OAuth
  • Under Plugin Policies, set Permitted users to "All users can self-authorize"
  • Set OAuth Start URL to your domain URL
  • Under OAuth flows and External Client App Enhancements, tick Enable Client Credentials Flow
  • Set Run As (username) to the username of the user created in Step 2
  • Leave the App Authorization as default
Retrieve the Consumer Key and Secret
  1. On the Settings tab, under OAuth Settings, click Consumer Key and Secret.
  2. A new browser window opens and asks you to verify the email address provided. After verifying, the tab displays a Consumer Key and a Consumer Secret.
  3. Copy both securely — you will need them in the next step.

Important: The Consumer Key and Consumer Secret authenticate the connector to your instance. Store them securely and treat the Consumer Secret like a password. If it is rotated, the new value must be entered in the Salesforce system prep-script before the next stack run, or data collection will fail. 


4. Configure the Prep Script in the Salesforce Loader

Have the following ready: your Salesforce Instance URL, Consumer Key, and Consumer Secret.

  1. As an Administrator, log in to Gathid and navigate to Admin → Systems.
  2. Select the Salesforce system and go to the Prep Scripts section.
  3. Enter the configuration details retrieved in the previous step.
  4. Toggle on any optional data to collect (Profiles, Groups, Roles, Permission Sets). Permission Sets are dependent on Profiles.
  5. Ensure the system run time is set close to your instance's stack start time.
  6. Click Save.


Credentials Checklist

Have the following ready before configuring the system:

Item Where to find it
Instance URL Your Salesforce instance address
Consumer Key External Client App → Settings → OAuth Settings
Consumer Secret External Client App → Settings → OAuth Settings
Minimum-privilege user Salesforce → Administration → Users

 


System Properties

The Salesforce connector retrieves the following data sets as CSV files. The fields collected for each are listed below.

Salesforce Accounts: Id, Username, LastName, FirstName, Name, CompanyName, Division, Department, Title, Email, IsActive, UserType, EmployeeNumber, ManagerId, LastLoginDate

Salesforce Profiles: Id, Name, Description, LastReferencedDate

Salesforce Groups: Id, Description, DeveloperName, Name, OwnerId, RelatedId, Type

Salesforce Roles: Id, Name, DeveloperName

Salesforce Permission Sets: Id, Description, HasActivationRequired, IsCustom, IsOwnedByProfile, Label, LicenseId, Name, PermissionSetGroupId, ProfileId, Type

 Next Steps: 

Add External Relationships