Salesforce

How it works#

The Salesforce connector indexes documents from your Salesforce. These documents organized around the Objects that you indicate. Examples are below.

Setting up#

Authorization#

OAuth is the recommended authentication method for self hosted deployments (not yet supported on cloud). You can also use a Salesforce username, password, and security token.

Configure OAuth for self-hosted Nexus#

Configure a Salesforce client application for the school deployment. Do not skip this step unless the operator has confirmed an existing application and its permissions.

Self-hosted deployments must create a Salesforce External Client App (ECA) and configure Nexus with its credentials. Before you begin:

• Enable My Domain for your Salesforce organization.

• Use a stable HTTPS URL for your Nexus WEB_DOMAIN.

• Sign in to Salesforce as an administrator.

Create an External Client App#

In Salesforce Setup, open External Client App Manager, select New External Client App, and set Distribution State to Local.

Configure OAuth#

Enable OAuth and set the callback URL to:

  {WEB_DOMAIN}/connector/oauth/callback/salesforce

The callback URL must exactly match your Nexus deployment's WEB_DOMAIN, including its scheme, host, base path, and port.

Add OAuth scopes#

Add these scopes:

• Manage user data via APIs (api)

• Perform requests at any time (refresh_token)

Configure OAuth security#

Enable all of the following:

• Require a secret for the web server flow

• Require a secret for the refresh token flow

• Require PKCE for supported authorization flows

• Refresh token rotation

Nexus uses the OAuth 2.0 authorization code flow with S256 PKCE.

Save the app credentials#

Save the ECA, then copy its Consumer Key and Consumer Secret. Store the secret securely.

Salesforce can take several minutes to activate a new app or policy change.

Set permitted users#

Open the ECA's Policies tab and select a permitted-user policy.

For controlled deployments, select Admin approved users are pre-authorized, then assign the ECA to the required profiles or permission sets. Use All users may self-authorize only if your school's policy permits it.

Each user who authorizes Nexus also needs access to the Salesforce objects and fields you want to index.

Configure Nexus#

Set both variables on the Nexus API server and all background workers:

  SALESFORCE_CLIENT_ID=<ECA consumer key>
  SALESFORCE_CLIENT_SECRET=<ECA consumer secret>

Restart the affected Nexus services. OAuth is unavailable if either variable is missing.

Use manual credentials#

If you cannot use OAuth, authorize Nexus with a Salesforce username, password, and security token:

Log in to Salesforce#

Log in to Salesforce as an organization member with access to the data you want to index.

Open Settings#

Select your profile avatar, then select Settings.

Reset security token#

Select My Personal Information → Reset My Security Token.

Check email for token#

Check your email for the security token.

Indexing#

Create a new Salesforce Connector#

Navigate to the Admin Panel and select the Salesforce Connector Tile.

Create a new credential#

Select Create New, then choose an authentication method:

• Connect with Salesforce: Enter your school's HTTPS My Domain root, then complete the Salesforce OAuth flow. For example, enter https://company.my.salesforce.com or, for a sandbox, https://company--dev.sandbox.my.salesforce.com.

• Enter credentials manually: Enter your Salesforce Username, Password, and Security Token.

For OAuth, do not enter login.salesforce.com, a path, a query, or a custom port.

Select the credential#

Select the new credential and click Continue.

Define the Salesforce Object(s) you wish to index#

Simple#

Enter the [Salesforce
Object(s)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_list.htm)
you wish to index and organize your Nexus documents by.

* Make sure to use the singular version of object name (e.g. Opportunity instead of
  Opportunities)
* If no objects are indicated, it will default to indexing by **Account**
* Each Nexus Document extracted from Salesforce contains all fields and associations of each
  object. For example,
  when indexing each Account we include the fields of the AccountFeed and AccountShare objects as well (but not the
  associations of those objects).
  This can lead to bloated queries and memory intensive indexing in larger salesforce instances.

Use the Advanced mode to have finer grain control over what is indexed.

Advanced#

Specify which objects, fields, and associations get indexed with a json object.

Top level keys are Salesforce Objects, each value is a JSON object specifying:

* `fields`: a list of strings describing the fields of the object to index
* `associations`: a JSON object mapping a Salesforce Object associated with the parent object to a list of fields to be indexed for the child object

    {
      "Account": {
        "fields": ["Id", "Name", "Industry", "CreatedDate", "lastModifiedDate"],
        "associations": {
            "Contact": ["Id", "FirstName", "LastName", "Email"],
            "Opportunity": ["Id", "Name", "StageName", "Amount", "CloseDate"]
        }
      },
      "Lead": {
        "fields": ["Id", "FirstName", "LastName", "Company", "Status"],
        "associations": {}
      }
    }

Click on the Connect button.#

Click on the Connect button and your connector will be created. Nexus will automatically begin indexing your Salesforce data.

An Example#

You indicate you'd like to organize information by Account and click connect

Nexus will generate a document for every single Account in your Salesforce. Attached to each document will be all the information associated with that Account. This information would also include information from the Account's children objects (E.g. all associated Contacts, Notes, etc.). This means indicating Account means that all Contacts that are attached to an account will also be grabbed

If you want to index any Contacts that aren't attached to any Accounts, (as well as Accounts), you would indicate that like so:

Before using this source with students#

Start with approved course material. Check which documents the connector can retrieve and how it maps source permissions. Test with a student account and a teacher account before widening access. A successful sync does not prove that the intended class boundary is correct.

Use source troubleshooting when a document is missing or visible to the wrong audience.