Connected App – one for all
Before you start using BRYTER Salesforce Integrations (handling Objects or Quotes) you will need to set up a Connected App within the Salesforce Sandbox or Admin Console. This Connected App provides the required parameters for both currently available SF integrations.
These parameters are used in the configuration steps within the BRYTER Admin console to set up a new integration.
Each Integration is configured in a step-by-step process, that requires Admin and Developer level access to the 3rd party tool, in this case – Salesforce.
- Creation of the Connected app. Aims to grant access to BRYTER, and support the authentication process between the tools – should be done by the customer’s SF Admin in the SF Console. The right to give permission to new users/ allow new apps to read and write is required.
- Collecting the required parameters to configure the Integration within the BRYTER admin console. This step might take longer hours to finish and requires Admin level access to SF.
- Configuring the integration within BRYTER using the parameters. This step requires BRYTER Admin access rights.
- Adding the Integration in the module via action nodes and setting up the module according to your use case.
Required parameters and secrets
The Connected App for this integration (if it has been correctly created in Salesforce), provides the set of the configuration parameters and secrets. Note that all secrets and parameters must have values. However, when using the password flow the values of private-key, key-password and alias are unused and can be filled with arbitrary values. In case that you are using the certificate flow the values of password and username are unused and can be filled with arbitrary values.
Required Secrets
- keystore-password: Password for the key used while creating the certificate
- client-secret: OAuth Client Secret, it is called Consumer Secret in Salesforce
- password: The password of the user that is used for the connected app
Required Parameters
- object-name: Name of the Salesforce Object that will be accessed (Account, Contact, etc.)
- host: Salesforce Host, for BRYTER (sandbox) it is https://bryter--bryterapp.my.salesforce.com/
- aud: Audience of the Bearer Token request, in a test environment it should be https://test.salesforce.com, else https://login.salesforce.com or https://site.force.com/customers if implementing for an Experience Cloud site.
- sub: Salesforce user id associated (used while creating) with the app in Salesforce
- object-name: Name of the SObject to operate on
- client-id: OAuth Client ID, it is called *Consumer Key* in Salesforce
- keystore-base64: Keystore with Private Key converted to Base64 format
- username: The username of the account that is used for the connected app
- grant-type: Grant type used to obtain an access token. It should be either password or certificate
- private-key-name: the Unique Name of the certificate given during the certificate generation
How to get the required secrets – Implementation Guide
Overview
This implementation guide is for customers who intend to use BRYTER modules inside Salesforce.
This guide is aimed at the basic steps that should generally apply across customers; however, because Salesforce is complicated and heavily customizable, every customer’s situation will be slightly different. Please expect some degree of troubleshooting throughout the configuration process.
Basic Steps
Below is a brief outline of the basic steps of the process. Detailed instructions and tutorial videos for each step can be found in the sections that follow this Overview.
- Generate secure keys that will be shared between Salesforce and BRYTER to ensure the systems can exchange data successfully.
- Create a Connected App inside Salesforce, which will be used to authorize the exchange of data between Salesforce and your BRYTER module(s).
- Create an integration configuration inside BRYTER, for Salesforce, which will give you access insider your BRYTER module(s) to the various action nodes that BRYTER Salesforce integration makes available.
- Create a page and/or component within Salesforce, which will allow you to embed and run your BRYTER module(s) inside the Salesforce environment.
Basic Requirements
- Admin access to your BRYTER tenant
- Sys Admin access to your Salesforce organization
Step 1 – Generate Secure Keys
In order for your BRYTER module(s) to exchange information with Salesforce, you must set up a secure connection between them. To do this you must first generate a set of keys that you will use to configure Salesforce and BRYTER. Note that you will only need to do this once at the point of initial implementation.
This step requires you to execute a key-generation script from the Command Line, which also requires a particular configuration file. You can find these files in the attachment.
Once you have the files, open your preferred Command Line tool and execute the keygen.sh script, with a mandatory password argument. For example, if you wanted your password to be testpassword you would use a command like this:
Make sure you store your password, because you will need it later in Step 3.
When the script runs it will create two new files in your local directory, named bryter_cert.crt and bryter_keystore.base64. The bryter_cert.crt file will be used in the next step for configuration within Salesforce. The bryter_keystore.base64 file will be used in a later step for configuration within BRYTER.
This step is complete when the script runs successfully and you see both of these files in your local directory.
Step 2 – Create a Connected App in Salesforce
The next step is to create a Connected App in Salesforce that will allow your BRYTER module(s) to connect and exchange data with Salesforce.
- In Salesforce, go to Setup and use the Quick Find tool to search for and then click on “App Manager”.
- Click the button in the upper right of the screen labeled New Connected App.
- Complete the Basic Information section of the form for a New Connected App:
-
- Required Fields
- Connected App Name - enter the name, for example “BRYTER”
- API Name - this will automatically populate but you can change if desired
- Contact Email - the email of the person creating the connected app
- The remaining fields are optional
- Required Fields
-
- Select the checkbox in the API (Enable OAuth Settings) section, next to the label Enable OAuth Settings. When you do so, additional fields will be revealed.
- Complete the API (Enable OAuth Settings) section
-
- Required Fields
-
Callback URL
- For Salesforce production org, enter “https://login.salesforce.com/service/oauth2/success”
- For Salesforce sandbox org, enter “https://test.salesforce.com/service/oauth2/success”
- Use digital signatures - Check this box, and then upload the file named bryter_cert.crt that you generated in Step 1 of this guide.
- Selected OAuth Scopes - Add “Manage user data with APIs (api)” and “Perform requests at any time (refresh_token, offline_access)”
-
Callback URL
- The remaining fields are optional
- Required Fields
-
- Select Save button to save the Connected App.
- Select the Manage Consumer Details button to access the “Consumer Key” and “Consumer Secret.” You will need these in the next step of this guide.
-
- Copy and save the Consumer Key in a place you can access it. You will need this key.
- Copy and save the Consumer Secret in a place you can access it. You will need this secret.
-
- From Setup, use the Quick Find tool to search for and then click on “Manage Connected Apps”
- Select Edit next to your new Connected App.
- In the section titled OAuth Policies, in the field labeled “Permitted Users,” select Admin approved users are pre-authorized. Click the Save button again.
- Select the link for your new Connected App.
- Scroll down to the section titled Profiles. Click the Manage Profiles button and then select whichever Profiles you want to be able to access the Connected App. Click the Save button again.
This step is complete when you have created a Connected App with the appropriate profile, and you have copied and stored both the Consumer Key and Consumer Secret.
Step 3 – Create an Integration Configuration in BRYTER
The next step is to configure the Salesforce integration inside BRYTER so that it will be available to BRYTER authors who want to use the Salesforce integration actions within their modules.
Note that the integration must be configured separately for each type of Object. So, for example, you will have to separately configure the integration for Opportunity, Task, User, and any other object type.
- Go to your BRYTER tenant
- In the Account menu in the upper right corner of the screen, select Admin Console. If you do not see this option, then you are not a BRYTER admin and you will not be able to proceed.
- Once you have accessed the Admin Console, click the Integrations tab.
- Click the blue + New configuration button
- Name your integration (e.g. “Salesforce - Opportunity”). Then use the Type drop-down menu to select Salesforce and make sure you have selected the most current Version of the integration. Click Next to proceed.
- Complete all of the Parameter and Secret fields.
-
- sub - This is the Salesforce user ID for the user associated with the connected app created in Step 2. It is available clicking your avatar in the top right corner and click settings where the username parameter is visible.
- aud - This is the audience of the Bearer token. In a test environment, it will be https://test.salesforce.com. In a production environment, it should be https://login.salesforce.com.
- host - This is the Salesforce host for your organization. To get it, go to 'Setup', then using the Quick find tool get to 'my domain'. The host is visible for example, https://bryter.my.salesforce.com/ for a production host or https://bryter--bryterapp.sandbox.my.salesforce.com/ for a sandbox host. Make sure you keep a '/' at the end of the URL.
- object-name - This is the official name of the object type for which you are configuring this integration. Remember that the integration must be configured separately for each object type. For example, this could be Opportunity, Account, Task, User or any other object types.
- client-id - This is the value of the consumer key you created inside Salesforce and stored in Step 2 above.
- keystore-base64 - This is the value of the file named bryter_keystore.base64 which you created in Step 1 above when you ran the provided script.
- grant-type - This should be certificate.
- username - This can be whatever you want. It is a required value, but has no significance, and you do not need to keep track of it. If your imagination fails you, feel free to use wizard as your username.
- keystore-password - This is the password you used in Step 1 above when running the key generation script.
- client-secret - This is the value of the consumer secret you created inside Salesforce and stored in Step 2 above.
- password - This, like username, can be whatever you want. It is a required value but has no significance, and you do need to keep track of it. If your imagination fails you, feel free to use wizardwand as your password.
-
- Click Create configuration. If successful, you will receive a positive message. If unsuccessful you will receive a negative message.
- Once you have created the configuration, it is highly recommended (but not strictly necessary) that you find your configuration, click the Edit link, and then carefully re-label all of the provided Integration Actions and datasources to ensure they are easily identifiable by your authors within your BRYTER tenant.
Step 4 – Create a Page or Component for Embedding BRYTER within Salesforce
The final step of this process is to make your BRYTER module available to your Salesforce users by embedding it in some fashion within Salesforce.
There are different ways to do this, and it is up to you and your Salesforce admins and other colleagues to decide what approach best meets your needs.
We can discuss with you how BRYTER modules are designed to make this embedding possible in Salesforce or other environments.
In the future, we will provide a Salesforce package that can be installed into your Salesforce environment, which will simplify the embedding process for those who are looking for a default approach.