Salesforce Listener

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

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 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

Generate private key

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

   openssl req -x509 -sha256 -nodes -days 36500 -newkey rsa:2048 -keyout salesforce.key -out salesforce.crt

2. Copy the private key to your clipboard.

   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 nav, 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:

      

   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 and Notifier Blocks, 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 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):

     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.

   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.

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. Scroll to the beginning of the flow and click the Inputs.

4. Click Add and select Salesforce Listener.

5. Within the Listener, configure the settings listed in the Block settings table of 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):

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

• Create a Streaming Channel (Salesforce Documentation)