Overview

A Salesforce Connected App configuration requires setup on the Relay side (the push API) and the Salesforce side (receiver).

Configure a Relay Push API within the CXB Portal
1. A certification will be created and downloaded. This certification will be required when configuring the Connected App in Salesforce
Configure a Connected App in Salesforce
1. Provide Relay the consumer key for the Connected App.
Edit the Push API configuration (from step 1) in the Relay CXB
1. Update the Salesforce Consume Key with the value (from step 2).

1. Relay - Configure the Push API in CX Builder

IMPORTANT
If you do not see the API Management module on the left menu, please check that you have either Client Admin or Client User with Integration Permissions in the System.

Login to the Relay CXB Portal
Click on API Management in the left menu column.
Click on the Push API Integration tab. This is the “home page” of the Push API Integration UI, where you will see a list of existing integrations - if any exist.

Click the “ADD INTEGRATION” button. A modal will pop up with a dropdown menu.
1. If you are installing the managed package from the App exchange, choose Salesforce App Exchange Package. If your Relay {{glossary.CSM}} provided you a link to the undamaged package, select Salesforce Unmanaged Package.
Fill out the configuration dialog:
Name: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as.
Version: Select the version of this integration form with which you wish to integrate your client. The latest version is selected by default
Salesforce Username: This is the Salesforce username that the Client associated with the Connected App. For now, add any value in this box, later on in the setup you will obtain this value and we will update it
Salesforce Subdomain:
- For Salesforce sandboxes, set the value to Test
- For Salesforce production, developer orgs or personal accounts, set the value to Login
Salesforce Consumer Key: This is the Salesforce Consumer Key of the Connected App Configuration. For now, add any value in this box, later on in the setup you will obtain this value and we will update it.
Event Set: This is the standard set of event types that will be inserted as records into the following objects: RelayEvents__c and RelayPowerups__c.
Download the Certificate: The certificate/cert (or public_key) will appear after you click Activate. A modal will appear, click on You can download it here. If you need to access it after this modal is closed, the .crt file can be downloaded at any time when clicking on the edit icon setup, and locating the You can download it here at the bottom of the modal.
1. Provide the downloaded public certificate to the Salesforce admin who is installing the Relay Package.

2. Salesforce - Create the Relay Connected App

The Connected App allows Relay Network to insert event data, occurring within the Relay Network, into your Salesforce org. Based on the Relay event type, a record will be inserted into one of the two following objects: RelayEvents__c or RelayPowerups__c.

IMPORTANT
If a setting is not specifically called out in the the below article, leave it set to the default value.

As an admin, login to your Salesforce org.
Access your org’s Setup page.
Navigate to PLATFORM TOOLS → Apps → App Manager
Click the New Connected App button

Fill out the Managed Connect App as outlined below

Basic Information (1)

Set Connected App Name to Relay Connected App.
Set API Name to Relay_Connected_App.
Set Contact Email to the email address that will receive and errors related to this Connected App.

API (Enable OAuth Settings)

Check Enable OAuth Setting (2)
Uncheck Enable for Device Flow
Because this connected app is for connecting to the Relay system, no login user interface is required. Therefore, you can set the Callback URL to https://localhost
Check Use Digital Signatures (3)
- Click the Choose File button. Select the certificate file that was provided to you by your Relay Implementation Manager.
Move the following to the Selected OAuth Scopes (4)
- Manage User Data via APIs (api)
- Perform requests at any time (refresh token, offline access)
Check the following options (5)
- Require Proof Key for Code Exchanges (PKCE). Extension for Supported Authorizer Flows
- Require Secret for Web Server Flows
- Require Secret for Refresh Token Flows
Click Save
You should receive a message that it can take up to 10 mins for changes to take effect. Click Continue.

STOP
You need to add the Connected App Username and Consumer Key of the Connected App in CX Builder.
Click the Manage Consumer Details button. This should open a new tab in your browser.
In CX Builder, edit the Push API connection you created in the first step on this page, and add in the appropriate details.
Return to the original browser tab with the Managed Connected App settings you just created.

Update the Connected App Policies

You should still be on the Connected App settings page, so click the Manage button. If you are not on the Relay Connected App settings page follow the below steps:
- From setup, navigate back to PLATFORM TOOLS → Apps → App Manager
- Locate the Relay Connected App you just created
- Click the drown down arrow and select Manage
Click the Edit Policies button
Figure 3.

Relay Connected App Policies

rn-sfdc-connected-app-policies — Figure 4.

OAuth Policies

Set Permitted Users to Admin approved users are pre-authorized
Set IP Relaxation to Relax IP Restrictions.
Leave all other settings at their default values.
Click Save to return to the Relay Connected App detail page

Relay Connected App Permission Sets

Locate the Permission Sets section and click the Manage Permission Sets button.
Figure 5.

Application Permission Set Assignment

rn-sfdc-connected_app-permission-set-assignment — Figure 6.

Locate the Relay Network Connected App permission set, you previously created in the Permission Sets article, and check it.
Click the Save button.

You should not have a properly configured Relay Network Connected App.

3. Relay - Update Relay Push API Configuration

Navigate back the Relay CXB Portal
Edit the Push API configuration you created in the first step
Copy the Consumer Key to the Salesforce Consumer Key field of the push API configuration
Save

Locating Common Settings

NOTE
All of the below settings can ebe accessed from the App Manager drop-down menu.
PALTFORM TOOLS → Apps → App Manager → (Locate Relay Connected App) → Drop-down menu (located on the far right)

Setting	Location
Consumer Key	From the drop-down menu select View → Manage Consumer Details
OAuth certificate OAuth Scopes	From the drop-down menu select Edit
Permission Set	From the drop-down menu select Manage → scroll down to the Permission Set section

Troubleshooting

The section covers common errors related to the Connected App configuration and possible root causes.

Error	Error Description	Possible Cause
invalid_client	invalid client credentials	The uploaded OAuth .crt file is incorrect. Please replace the certificate.
invalid_client_id	client identifier invalid	The consumer key is incorrect. Please verify the correct consumer key has been provided to Relay.
invalid_grant	user hasn’t approved this consumer	The provided user name does not have permissions to the connected app. Verify the OAuth Policies configuration. Verify the Permission Set Assignment and that the provided user is in the permission set. Verify the Relay CXB Push API Configuration is using the Salesforce username value and not the email address. Note, the username often looks like an email address but it is not.
invalid_grant	refresh_token scope is required and the connected app should be installed and preauthorized.	Verify your OAuth Scopes are properly configured (Figure 2. #4).

AWS IP Addresses

Relay Staging Environment

Relay Production Environment