Salesforce Connector - Configuration

This document is currently pre-release and is subject to change, for any questions please reach out to the RecordPoint support team.

Use this guide to add, authorize, and enable the Salesforce Connector so that RecordPoint can manage content from your Salesforce environment.

Prerequisites

Before you begin, ensure:

• You have the Application Administrator role in the RecordPoint platform.

• You have Salesforce System Administrator access (or equivalent) in your Salesforce org, including the ability to:

  • Create and manage External Client Apps.

  • Create or modify Permission Sets and assign them to users.

• You know whether you are connecting to a Salesforce Production or Sandbox environment.

• You have a dedicated Salesforce integration user whose identity the connector will impersonate via the External Client App Run As setting.

Note: The Salesforce Connector uses OAuth 2.0 Client Credentials Flow - a server-to-server authentication method that requires no interactive user login. It authenticates using an External Client App Client ID and Client Secret, and all API calls are made in the context of a designated Run As user.

Step 1 – Create an External Client App in Salesforce

The RecordPoint Connector authenticates to Salesforce using OAuth 2.0 Client Credentials Flow. Begin by creating an External Client App in your Salesforce org so that you have the Client ID and Secret needed to configure the RecordPoint connector.

1. Sign in to your Salesforce org as a System Administrator.

2. Go to Setup → External Client Apps (search for "External Client Apps" in Quick Find).

3. Select New External Client App.

4. In the API (Enable OAuth Settings) section:

   • Select Enable OAuth Settings.

   • Set Callback URL to <https://localhost/administration/connectors/genericcallback> (placeholder - not used in client credentials flow).

   • Under Selected OAuth Scopes, add:

     • Access and manage your data (api)

     • Perform requests at any time (refresh_token, offline_access)

   • Select Enable Client Credentials Flow.

5. Select Save, then Continue.

6. After saving, note the Consumer Key (Client ID) and Consumer Secret - you'll need these in Step 4's Client ID and Client Secret fields.

Important: Treat the Consumer Secret as a password. Store it in a secrets manager and never commit it to source control.

Configure the Run As user (required for Client Credentials Flow)

The Client Credentials Flow doesn't carry a user identity in the token request. Salesforce requires a Run As user on the External Client App - all API calls execute in that user's permission context.

1. Open the External Client App record in External Client Apps.

2. Select Edit Policies.

3. Under Client Credentials Flow, set Run As to the dedicated integration user you'll create in Step 2.

4. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized.

5. Select Save.

Important: The Run As user's profile and Permission Sets are the effective permissions for all connector API calls. Use the dedicated least-privilege user created in Step 2 - do not run as a System Administrator.

Step 2 – (Optional) Create a Least-Privilege Permission Set and Integration User

RecordPoint requires read access to all objects in scope, and hard-delete access for disposal actions. The integration user created here is also designated as the Run As user on the External Client App (Step 1).

2a - Create a Permission Set

1. Go to Setup → Permission Sets.

2. Select New.

3. Select Save.

4. Enable System Permissions → API Enabled.

5. If hard-delete disposal is required, also enable Bulk API Hard Delete.

2b - Create or Designate an Integration User

1. Go to Setup → Users → New User (or use an existing dedicated integration user).

2. Set the Profile to a profile with minimal access (for example, a cloned Minimum Access – Salesforce profile).

3. Assign the RecordPoint Connector Permission Set to this user.

4. Note the username - this user will be set as the Run As user on the External Client App (Step 1).

2c - Assign the Permission Set to the External Client App

1. Return to Setup → External Client Apps → open the RecordPoint Connector External Client App.

2. Select Manage Permission Sets.

3. Add the RecordPoint Connector Permission Set to the External Client App's permitted set.

Important: Grant only the minimum permissions required. Avoid using a full System Administrator profile for the integration user.

Step 3 – Add the Salesforce Connector in RecordPoint

1. Sign in to the RecordPoint Platform as an Application Administrator.

2. Select the Settings icon in the main toolbar.

3. Select Add Connector.

4. In the Connector Gallery, select the Salesforce Connector.

5. Select Add.

The Salesforce Connector Details page appears. The connector instance is created but isn't yet enabled.

Step 4 – Configure the connector

On the Salesforce Connector Details page, complete the required configuration fields using the values obtained from Steps 1 and 2:

Note: The Instance URL must include the full My Domain hostname. Legacy <https://na1.salesforce.com-style> URLs aren't recommended.

Save the connector configuration.

Important: Ensure the connector Status remains Disabled. Do not enable ingestion yet. Complete object configuration (Step 5) before enabling the connector.

Step 5 – Configure the Aggregation Object and Entity Hierarchy

Use the generate_connector_config.py script to connect to your live Salesforce org, browse available objects and fields, and produce a connector_config.json ready to upload to RecordPoint.

Prerequisites

• Python 3.10 or later

• The requests package: pip install requests

• One of the following authentication methods (same credentials configured in Steps 1–2):

  • Salesforce CLI (recommended): install from developer.salesforce.com/tools/salesforcecli and authenticate with sf org login web --target-org <alias>

  • A pre-obtained Bearer access token and your org's instance URL

  • The Client ID and Client Secret from the External Client App created in Step 1

5a. Run the script in interactive mode

Interactive mode is the recommended approach. Run the script without --aggregation:

# Salesforce CLI (recommended)
python generate_connector_config.py --sf-org <alias>

# Pre-obtained Bearer token
python generate_connector_config.py --domain https://{tenant}.my.salesforce.com --token <token>

# OAuth Client Credentials
python generate_connector_config.py --domain https://{tenant}.my.salesforce.com --client-id <id> --client-secret <secret>

The walkthrough guides you through the following steps:

After the walkthrough, the script prints a summary and prompts for confirmation before writing the output file (default: connector_config.json).

5b. Non-interactive mode

For CI pipelines or when you already know the object names, supply --aggregation to skip the walkthrough:

python generate_connector_config.py --sf-org <alias> --aggregation Case --records Attachment,EmailMessage

This produces sensible field and mapping defaults. Binaries, references, and self-record configuration are not populated - edit the JSON directly or re-run in interactive mode.

5c. Inspect a single object's schema

To download the full describe payload for a Salesforce object before configuring it:

python generate_connector_config.py --sf-org <alias> --describe-object Case
python generate_connector_config.py --sf-org <alias> --describe-object Case --schema-output schemas/Case.schema.json

5d. Validate the config

Before uploading to RecordPoint, validate the generated file:

# Structural check only (no Salesforce connection required)
python generate_connector_config.py --validate connector_config.json

# Structural check + live org field/object verification
python generate_connector_config.py --sf-org <alias> --validate-org connector_config.json

If the config is valid, you see:

Fix all reported issues before proceeding to Step 6.

Core field mapping reference

The following RecordPoint core fields must be mapped for every Aggregation and Record object. The script configures these during the core mappings step (Step C above).

Note: Multiple connector instances can be created within the same Salesforce org to cover different Aggregation objects (for example, one instance for Case, another for Account).

Example: Case as aggregation

This example uses a connector instance configured with Case as the Aggregation object and SelfRecordEnabled: true.

Entity hierarchy:

Case (Aggregation)
├── Case (Record - self-record, enables disposal of the Case)
│   ├── Contact fields flattened (Reference - ContactId → Name, Email, Phone, Title)
│   ├── Account fields flattened (Reference - AccountId → Name, Phone, Industry)
│   ├── Asset fields flattened (Reference - AssetId → Name)
│   ├── EmailMessage fields flattened (Reference - SourceId → Name)
│   ├── Product2 fields flattened (Reference - ProductId → Name, ProductCode, Family)
│   ├── Case fields flattened (Reference - MasterRecordId → CaseNumber)
│   └── Case fields flattened (Reference - ParentId → CaseNumber)
├── Attachment (Record - legacy file attachments linked to the Case)
│   └── Attachment (Binary - file content)
├── Case (Record - child cases linked via ParentId)
│   └── Case (Binary - case content file)
└── EmailMessage (Record - emails linked to the Case)
    └── EmailMessage (Binary - email content file)

Aggregation core field mappings (Case):

Record core field mappings:

Step 6 – Enable the Salesforce Connector in RecordPoint

Once the Connected App is configured in Salesforce and the entity hierarchy is validated:

1. Return to the RecordPoint Platform → Settings → Connectors.

2. Open the Salesforce Connector instance you created.

3. Review the configuration settings and confirm all fields are correct.

4. Change the connector Status to Enabled and select Save.

The connector starts its initial sync. The duration depends on the volume of records in your Salesforce org.

Validation and next steps

After you enable the connector, consider:

• Confirm that records are appearing in RecordPoint from your Salesforce environment. Allow time for the initial sync to complete before checking.

• Review any classification rules and retention policies that apply to the ingested objects (for example, SOX retention for Opportunities and Contracts, GDPR rules for Contact records).

• Work with your records management team to verify that ingested records, self-records, and Binaries are behaving as expected.