# Salesforce connector

The Salesforce connector imports user data from Salesforce using the [Salesforce SOQL REST API](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm). This enables you to bring relevant user attributes into Nexthink Adopt, allowing for enhanced targeting and personalization. Use the Salesforce connector to enrich custom fields in the Nexthink interface.

The connector supports OAuth and Basic Auth authentication methods.

## Prerequisites

Before configuring the Salesforce connector, ensure:

* You have required administrator rights to configure a connected application in Salesforce. Refer to the official [Salesforce](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_authenticate.htm\&type=5) documentation for more information.
* Configure the connector credentials using the relevant authentication method. Refer to the [Nexthink connector credentials](https://docs.nexthink.com/platform/latest/administration/connector-credentials) documentation for more information

## Configuring the Salesforce application

{% hint style="warning" %}
You need admin rights to configure the Salesforce connector, ensure you have the necessary admin rights.
{% endhint %}

To use OAuth 2.0 authentication for the connector, you must create a Connected App in Salesforce:

{% hint style="info" %}
The steps and required settings may vary depending on your Salesforce configuration. Refer to the [Salesforce authentication](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_authenticate.htm\&type=5) documentation for more information.
{% endhint %}

1. Go to Setup > **Platform Tools** > **Apps > External Apps.**
2. Click **External App Manager** > **New External App.**
3. Add the required fields under **Basic Information** to create the application:
   * **Connected App Name**: e.g., `Nexthink Adopt Integration`
   * **API Name**: Auto-generated
   * **Contact Email**: Your valid email address
   * **Distribution State**: Select **Local**
4. Click **Create**
5. If you use OAuth authentication, go to the **Settings** tab and click **Edit** to enable OAuth settings.
6. Under **OAuth Settings**, select the **Enable OAuth Settings** checkbox**.**
7. Add required fields under **App Setting**:
   1. **Callback URL**: Use `http://localhost` (placeholder)
   2. **OAuth Scopes**: Select the revelant OAuth scope
8. Under **Flow Enablement**, select the **Client Credentials Flow** checkbox.
9. Under the **Security**, select the:
   * **Require secret for Web Server Flow** checkbox
   * **Require secret for Refresh Token Flow** checkbox
10. Click **Save**
11. Navigate to the **OAuth Settings and** click on the **Consumer Key and Secret t**o retrieve the credentials

* Follow Salesforce's prompts to verify your identity
* Click the copy to copy the **Consumer Key** and **Consumer Secret key.**

{% hint style="warning" %}
Always keep your credentials keys securely to prevent unauthorized access.
{% endhint %}

## Configuring the Connector credentials

Use your Salesforce credentials to create new credentials for the integration between Nexthink and Salesforce. Refer to the [Connector credentials](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/outbound-connectors/connector-credentials#connectorcredentials-creatinganewcredential) for more information.

## Configuring the Salesforce connector

From the Nexthink web interface:

1. Go to **Administration** > **Inbound connectors**.
2. Click the **New connector** button in the top-right corner of the page.
3. Select either **Salesforce: User Attributes**.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-efeec2e5054ba44f194f83152ae95b9382b5ff38%2FSFDC-MP.png?alt=media" alt=""><figcaption></figcaption></figure>

The **General** tab includes:

* **Name**: A meaningful name for the connector. This name appears on the administration page.
* **NQL ID**: A unique identifier for the connector used when referencing the Salesforce connector in NQL queries. You can initially modify the suggested NQL ID, but once you save the workflow, you can no longer change the NQL ID.
* **Description**: A short description of the purpose and behavior of the connector.
* **Scheduling**:
  * **Recurrence**: Set the execution time and recurrence. Executions start at the scheduled time.
* **Connection:**
  * **Credentials**: Select preconfigured credentials from the Connector credentials page. The connector supports Basic and OAuth authentication. Refer to the [Connector credentials](https://docs.nexthink.com/platform/integrations/outbound-connectors/connector-credentials) documentation for more information.
  * **URL**: This URL is automatically populated when you select credentials.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-670287c628e7b5e36e47a014c52e102a773f693a%2FSFDC-MAPPING.png?alt=media" alt=""><figcaption></figcaption></figure>

The **Parameters** tab includes:

* **Query**: Enter the Salesforce Object Query Language (SOQL) query to be executed by the Salesforce API. The query must return a list of **User objects** including:
  * Fields to import (e.g., name, email, department)
  * Use a field to identify the user and map it to the Nexthink identifier (for example, a user name in the form of an email address or UPN).

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-cfd23dedd6fb385ab13b7ba2ceac4112299348cb%2FSFDC.png?alt=media" alt=""><figcaption></figcaption></figure>

The **Data mapping** tab includes:

* **Identification:** Select a field from the API response to be used to identify users.
  * **Source identifier (JSONata)**: Enter the field name returned by the API response that identifies users. Use [JSONata](https://docs.jsonata.org/overview) if needed to transform the value. Field names containing whitespaces or [JSONata](https://docs.jsonata.org/overview) reserved characters (such as `.`, `+`, `-`, `*`, `/`, `{`, and so on) must be enclosed in backticks (`` ` ``).
  * **Nexthink identifier**: Select either **UPN** (requires UPN collection via Collector) or **Email address** (requires the Entra ID connector).
* **Field Mapping**: Click **Add mapping** to define how API response fields are matched to Nexthink custom fields.
  * **Source identifier (JSONata):**\
    Specify the field name in the API response that contains the data to be imported. If you need to transform the data before mapping, use [JSONata](https://docs.jsonata.org/overview).
  * **Nexthink field:** Select the custom field on the User object for data import. Field names containing whitespaces or [JSONata](https://docs.jsonata.org/overview) reserved characters (such as `.`, `+`, `-`, `*`, `/`, `{`, and so on) must be enclosed in backticks (`` ` ``).

## Test results panel

{% hint style="info" %}
The **Test results** panel is available only for supported connectors. Connector availability also depends on your license.
{% endhint %}

Use the **Test results** panel on the right side to run the connector with real data on demand, and inspect responses and errors. The test panel helps with faster debugging and validation during setup, and also with more reliable mappings with less trial and error.

Select the **Run test** button to call the API, and validate the credentials and check connectivity to the targeted endpoint.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FBhemTJqCHlMxxVD7UgDJ%2Fimage.png?alt=media&#x26;token=bacddbe6-fdde-4653-9bb1-25aa238195b1" alt=""><figcaption></figcaption></figure>

Besides basic information, such as the response status code and time, the panel also shows a sample record of the response at the bottom.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FI4IxueEsH60Pl3NQpjF0%2FHwklwWjD3Ud5ZXPC.png?alt=media&#x26;token=85b6123d-b40e-4085-871e-bc17232c8a15" alt="" width="316"><figcaption></figcaption></figure>

In the event of an error, the system displays the API response to aid in diagnosing the issue.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FKwqz92TxPeBl3QWqbKNt%2F9kAwIQi3M5gG7Y0H.png?alt=media&#x26;token=eeb306f0-d2b8-441b-a105-1bcd708a2d7c" alt="" width="309"><figcaption></figcaption></figure>

## Known limitations

* The connector cannot process more than 3 million records per sync.
* If employees share the same UPN, the UPN-based identification only processes the first 1,000 user records.
* User Principal Name (UPN) requires configuration in Collector.
* Email address requires the Entra ID (Azure AD) connector.

## Querying execution logs with NQL

Using NQL, you can retrieve detailed insights into the execution of the Saleforce connector instances by querying the following table:

| Field                              | Type          | Description                                                                                                                                                                                                                 |
| ---------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `time`                             | `datetime`    | Timestamp of the connector execution log entry.                                                                                                                                                                             |
| `status`                           | `enumeration` | <p>Execution status:<br>• <code>success</code>: All rows received and processed.<br>• <code>partial</code>: Some rows ignored due to row limit.<br>• <code>failure</code>: Connector could not receive or process data.</p> |
| `details.name`                     | `string`      | Name of the connector instance.                                                                                                                                                                                             |
| `details.description`              | `string`      | <p>Description of the error(s), if any. Includes descriptions such as:<br>• <em>Too many rows received...</em><br>• <em>Invalid JSONata expression for field</em></p>                                                       |
| `details.connector`                | `string`      | Name of the connector template used.                                                                                                                                                                                        |
| `details.credentials`              | `string`      | Label of the credentials used in the instance.                                                                                                                                                                              |
| `details.credentials_id`           | `string`      | Unique identifier of the credentials.                                                                                                                                                                                       |
| `details.nql_id`                   | `string`      | NQL ID of the connector instance.                                                                                                                                                                                           |
| `details.number_of_received_rows`  | `number`      | Total number of rows received from the source.                                                                                                                                                                              |
| `details.number_of_processed_rows` | `number`      | Total number of rows processed by the connector—may differ from imported rows.                                                                                                                                              |

Run the `platform.inbound_connector_logs` query to retrieve comprehensive logging information about all inbound connector executions.

{% hint style="warning" %}
To access this table, you must have the **Platform logs** permission enabled in the **Data model visibility**.
{% endhint %}

### NQL examples

<details>

<summary>Retrieve failed imports for the last 24h</summary>

{% code overflow="wrap" %}

```
platform.inbound_connector_logs during past 24h | where status == failure | list time, details.connector, details.name, details.error_description | sort time desc
```

{% endcode %}

</details>

<details>

<summary>Retrieve failed imports for the last 24h</summary>

{% code overflow="wrap" %}

```
platform.inbound_connector_logs during past 24h | where status == failure | list time, details.connector, details.name, details.error_description | sort time desc
```

{% endcode %}

</details>