---
title: "Salesforce Listener"
slug: "salesforce-listener"
updated: 2026-05-06T10:45:37Z
published: 2026-05-06T19:13:33Z
canonical: "help.hyperscience.ai/salesforce-listener"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Listener

> [!WARNING]
> **Accessing this feature**
> 
> Your access to the feature described in this article depends on your license package and pricing plan.
> 
> To learn which features are available to your organization and how to add more, contact your Hyperscience representative.

With the Salesforce Listener Block, you can configure your flow to ingest files stored in Salesforce for processing within the Hyperscience application.

The Salesforce Listener Block is available in both SaaS and on-premise versions of the Hyperscience application.

## Sample use cases

- Clients attach files to the records of specific objects in Salesforce. Hyperscience ingests all of these client files automatically for processing. You can then use these files to update client records using the Salesforce Notifier Block.

## Block settings table

| **Name** | **Required?** | **Description** |
| --- | --- | --- |
| Topic Name | Yes | The name of the topic you configured in Salesforce for the Salesforce Listener |
| Associated Username | Yes | The username associated with the Salesforce Connected App or External Client App |
| Consumer Key | Yes | The Consumer Key from the Salesforce Connected App or External Client App |
| Private Key | Yes | The key generated during the authentication-configuration process. The private key is a long string that begins with *----BEGIN PRIVATE KEY----\* and ends with *\n----END PRIVATE KEY----\n*. Include both of these tags and all characters between them when entering the private key. |
| Sandbox Environment | Yes | Indicates whether the connected Salesforce instance is a sandbox environment |

## Setting up Salesforce Listener

### Setup within Salesforce

#### Install and set up Hyperscience Package

1. Install the Hyperscience package in the desired Salesforce org.
  1. Go to the Salesforce AppExchange’s [Hyperscience Platform](https://appexchange.salesforce.com/listingDetail?listingId=a0N4V00000G6fiBUAR&preview=%222022-09-29T15%3A51%3A35.000Z%22&_ga=2.84305497.1160715746.1664388746-1251261210.1661438262&tab=e) listing.
  2. Click the **Get It Now** button.
  3. Enter your details and click the **Contact Me** button.
    1. A Hyperscience representative will contact you and provide you with the Hyperscience package.
  4. Once you have the Hyperscience package, install it in the desired Salesforce org.
2. Add **Hyperscience Permission Set** to users that should have access to the Hyperscience application.
  1. Go to the **Setup** page.
  2. Search for “Permission Sets” and click the **Permission Sets** link.
  3. Go to **Hyperscience Permission Set**.
  4. Click **Manage Assignments**.
  5. Click **Add Assignments**.
  6. Select the users you want to give permissions to the Hyperscience application by checking the checkbox for each user.
  7. Click **Assign** and then **Done**.
3. Enable the **Query All Files** permission.
  - Option 1 (using **Permission Set**):
    1. Go to the **Setup** page.
    2. Search for **Permission Sets** and click on it.
    3. Click **New**.
    4. Choose the desired Label (e.g., Query All Files).
    5. Click **Save**.
    6. Go back to the Permission Set Page.
    7. Search for the created Permission Set and click on it.
    8. Go to App Permissions.
    9. Click **Edit**.
    10. Activate the **Query All Files** permission.
    11. Click **Save**.
    12. Click **Manage Assignments**.
    13. Click **Add Assignments**.
    14. Add users who should be able to query files.
    15. Click **Assign**.
  - Option 2 (using **Profile**):
    1. Go to the **Setup** Page.
    2. Search for **Profiles** and click on it.
    3. Search for the Profile that you want to enable the Query All Files permission for and click on it.
    4. Click **Edit**.
    5. Enable the **Query All Files** permission.
    6. Click **Save**.

#### Configure authentication

The steps required to configure the authentication for the connection depend on whether you’re using a Salesforce Connected App or an External Client App. The External Client App offers improved security and packaging options compared to Connected Apps.

In your Salesforce account, you may not see an option to create a Connected App. If so, follow the instructions for the External Client App.

****Salesforce Connected App****

#### Generate private key

1. Create the private key (`salesforce.key`) and certificate (`salesforce.crt`) by running the following command:

```bash
openssl req -x509 -sha256 -nodes -days 36500 -newkey rsa:2048 -keyout salesforce.key -out salesforce.crt
```
2. Copy the private key to your clipboard.

```bash
cat [private.key file] | sed 's/$/\\n/' | tr -d '\n' | pbcopy
```
3. Paste the private key into a text file and save it. Later, you will need to paste it into your Salesforce Listener Block within Hyperscience.

#### Create your JWT Connected App

1. Log in to Salesforce and go to **Setup**.
2. In the side navigation, go to **Apps** > **App Manager** and click **New Connected App**.
3. Enter the information in the **Basic Information** section.
4. In **API (Enable OAuth Settings)**, complete the following steps:
  1. Select **Enable OAuth Settings**.
  2. In **Callback URL**, enter “http://localhost”.
  3. Select **Use digital signatures**, and upload the `salesforce.crt` file that was generated when you created your private key.
  4. In **Selected OAuth Scopes**, add the following permissions:
    1. **Manage user data via APIs (api)**
    2. **Perform requests at any time (refresh_token, offline_access)**
  5. Click **Save**. The page should look similar to the following screenshot:

**![SalesforceListener.png](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/24808462708621.png)**
  6. On the resulting page, click **Manage**.
    1. Click **Edit Policies.**
    2. In the **OAuth policies** section, change **Permitted Users** to **Admin approved users are pre-authorized**.
    3. Click **Save.**
  7. On the app page, in the **Profiles** section, click **Manage Profiles**.
    1. On the Application Profile Assignment page, assign the user profiles that will access this app. This is the service account user, which will be configured in the Salesforce Listener Block, and its details will be logged for any object updates.

#### Retrieve your *consumer_key* from the Connected App

1. Within Salesforce, click **App Manager** in the Apps navigation sidebar.
2. Find the connected app created in the previous section.
3. On the app’s row, click on the drop-down menu and select **View**.
4. Copy the **Consumer Key** from the **API (Enable OAuth Settings)** section. You’ll need the Consumer Key when configuring the Salesforce Listener Block.

**Create and link the Salesforce topic**

1. Create a Streaming Channel or choose an existing one that you will use. Note that channel names in Salesforce should start with `/u/`.
  - See Salesforce’s [Create a Streaming Channel](https://developer.salesforce.com/docs/atlas.en-us.api_streaming.meta/api_streaming/create_a_streaming_channel.htm#:~:text=If%20you're%20using%20Salesforce,to%20create%20a%20streaming%20channel.&text=Select%20Save.) for more information.
2. Obtain the ID of the `streamingChannel`. To do so, do one of the following:
  - Click on the channel’s name on the Streaming Channels page, then you can find the channel ID in the URL address bar. For example, if the URL is `https://test.lightning.force.com/lightning/r/StreamingChannel/0M68c0000000HGyCAM/view`, then the channel ID is `0M68c0000000HGyCAM`.
  - Go to the Developer Console and run the following query in the query editor (replace `/u/ChannelName` with the channel name from step 1):

```sql
SELECT ID, NAME FROM StreamingChannel where NAME in ('/u/ChannelName')
```
3. Create a record of `Hyperscience__Channel_Object_Link__c`. To create this record, run the command below in the Developer Console. In this code snippet, `objectApiName` refers to the API name of the object whose records you intend to attach files to. As soon as a file is attached to a record with API name `objectApiName`, a notification will be sent using Streaming Channel with name `/u/channelName`.

Use the `objectApiName` for the Salesforce object the documents are associated with that you want to process in Hyperscience. For example, if you want Hyperscience to process documents attached to Salesforce Cases, use the `objectApiName` for the Salesforce Case object. To find this value, click on **Object Manager** in the Salesforce Setup menu, find the Case object, and retrieve the name in the **API Name** column.

```plaintext
Hyperscience__Channel_Object_Link__c channelObjectLink = new Hyperscience__Channel_Object_Link__c();
channelObjectLink.Hyperscience__Channel_Name__c = '/u/channelName;
channelObjectLink.Hyperscience__Channel_Id__c = 'channelId';
channelObjectLink.Hyperscience__Object_Api_Name__c = 'objectApiName';
insert channelObjectLink;
```

The above script, creates a link between a Salesforce object and a Streaming channel. It should be noted that a single object cannot be linked with more than one channel, but a single channel can be associated with multiple objects.

After completing these steps, every time that a file is attached to a record of an object with API name `objectApiName`, a message will be published into the channel with the name `/u/channelName` and ID `channelId`.

Every such message will be consumed by the Salesforce Listener, which in turn will retrieve the corresponding file and create a submission from it.

**Uploading Files in Salesforce**

In Salesforce, you should use the **Files related** list for attaching files to records of an object. If you don’t see the **Files related** list on a record, just add it to the page layout for that record type. To learn how, see Salesforce’s [Add the Files Related List to Page Layouts](https://help.salesforce.com/s/articleView?id=sf.admin_files_related_list_setup.htm&type=5).

****External Client App****

**Prerequisites**:

- Salesforce System Administrator access
- OpenSSL installed for generating keys and certificates
- `API Enabled` permission granted to profiles

**Notes**:

- The integration is server-to-server, so no user interaction (e.g., browser redirects) is required.

**Generate the private key and certificate**

1. Create a private key (`salesforce.key`) and self-signed certificate (`salesforce.crt`) for JWT signing. In a later step, you will upload this certificate to Salesforce for verification. To create the private key, run the following command in your terminal:

```bash
openssl req -x509 -sha256 -nodes -days 36500 -newkey rsa:2048 -keyout salesforce.key -out salesforce.crt
```
2. Copy the private key to your clipboard:

MacOS

```bash
cat salesforce.key | sed 's/$/\n/' | tr -d '\n' | pbcopy
```

Linux

```bash
xclip -selection clipboard < salesforce.key
```

Windows (Git bash)

```bash
cat salesforce.key | clip
```
3. Paste the private key into a secure text file and save it. You'll paste it into the Salesforce Listener Block in Hyperscience.

**Create the External Client App**

1. Log in to Salesforce and go to **Setup**.
2. In the **Quick Find** box, enter “External Client Apps”, then select **External Client App Manager**.
3. Click **New External Client App**.
4. In the **Basic Information** section:
  1. Enter the app name (e.g., `Hyperscience Integration`).
  2. Enter a contact email and description.
5. In the **API (Enable OAuth Settings)** section:
  1. Check **Enable OAuth Settings**.
  2. In the **Callback URL** field, enter “http://localhost” (placeholder value — not used in the JWT flow but is required).
  3. Select **Use digital signatures** and upload the `salesforce.crt` file generated earlier.
  4. In the **Selected OAuth Scopes** field, add:
    - **Manage user data via APIs (api)**
    - **Perform requests at any time (refresh_token, offline_access)**
6. Click **Save**.

**Configure app policies**

After saving the External Client App, configure its policies to customize its behavior and ensure compatibility with the Salesforce organization and Hyperscience integration.

1. On the resulting page, under **Policies**, click **Edit**.
2. Click **Policies** to access the policy settings.
3. In the **OAuth Policies** section:

A new view to select which profiles / permission sets can access this new app appears.
  - **Permitted Users**: Ensure that **Admin approved users are pre-authorized** is selected.
4. Select the desired user profile / permission set (i.e., the Hyperscience Permission Set created previously).
5. Click **Save**.

**Note:** Salesforce sometimes requires the `openid` scope to be added explicitly if JWT authentication is used for user identity. If authentication fails, add the `openid` scope, as well.

**Retrieve the Consumer Key (Client ID)**

1. On the same page, click **Settings**, then click **OAuth Settings**.
2. Click **Consumer Key and Secret**.
3. Copy the **Consumer Key**, paste it in a secure text file, and save it. You’ll need this key when configuring the Salesforce Listener Block in Hyperscience.

### Configure the Salesforce Listener Block

1. Log in to your Hyperscience instance.
2. Go to **Flows**, and click on the name of the flow you want to add the Salesforce Listener Block to.
3. Click **Edit Flows**.
4. In Flow Studio, click **Inputs**.
5. Click **Add**, and select **Salesforce Listener**.
6. Configure the settings listed in the [Block settings table](/v43/docs/salesforce-listener#block-settings-table) in this article.

### Process existing files

#### Open the Developer Console in Salesforce

1. In the setup menu in the upper-right corner, select **Developer console**.
2. In the Developer Console, from the **Debug** menu, select **Open Execute Anonymous Window**.

#### Run code snippet

Enter the following code in the opened window with title **Enter Apex code** (replace `/u/channelName` with the channel name created in your environment):

```plaintext
Datetime fromDateTime = DateTime.newInstance(YYYY, MM, DD, HH, MM, SS);
Datetime toDateTime = DateTime.newInstance(YYYY, MM, DD, HH, MM, SS);
FilesController.publishFiles('/u/channelName', fromDateTime, toDateTime);
```

This command will publish on the channel with the name `/u/channelName`. Both `fromDateTime` and `toDateTime` parameters are required, but they can be assigned a `null` value. `channelName` is required.

- The `Hyperscience__Channel_Object_Link__c` custom object manages the link between Salesforce Objects and streaming channels. So, if `object1` has an entry in `Hyperscience__Channel_Object_Link__c` and its corresponding `channel_name__c` on `Hyperscience__Channel_Object_Link__c`’s record is `channel1`*,* when you run `FilesController.publishFiles('channel1', fromDateTime, toDateTime)`, Hyperscience receives all documents that were attached to `object1` between `fromDateTime` and `toDateTime` and publishes them to `channel1`.
- Parameters `fromDateTime` and `toDateTime` are used as filters on the dates that the documents were attached to a certain object.

## Known limitations

- If you upload a file and then add it to an object, adding it a second time will *not* cause re-processing due to how Salesforce keeps track of new files. To re-process the file, upload the file again.

## Additional resources

- Salesforce’s [Create a Streaming Channel](https://developer.salesforce.com/docs/atlas.en-us.api_streaming.meta/api_streaming/create_a_streaming_channel.htm)