Skip to main content
Version: 3.2.x

Installation & Configuration

Supported Editions​

This application works with the following Salesforce editions:

  • Enterprise Edition
  • Unlimited Edition
  • Developer Edition
  • Performance Edition

Not Supported​

  • Group Edition
  • Essentials Edition
  • Professional Edition (unless purchased as an add-on)

Note: Please check this link to Salesforce documentation for more details.

Dependencies​

  • Salesforce Messaging for Web Deployment
  • Salesforce CLI
  • Visual Studio Code
  • Visual Studio Code Salesforce extensions, including the Lightning Web Components extension

Installation Options​

Option 1: Installing via Unlocked Package​

1

Log in to your org

Ensure you are logged into your Salesforce organization with the appropriate administrative permissions.

2

Install the package

Click this link to install the unlocked package in your org.

3

Select installation options

Select "Install for All Users" or your preferred installation option.

4

Configure the package

After the package is installed, you must configure the Named Credentials and Custom Metadata settings with the client_id, client_secret, and URLs provided by Optave. Follow the steps in the Prerequisites section below to complete this configuration.

Note: Package installation may take up to 2 hours to complete. You will receive an email from Salesforce when the installation is complete.

Option 2: Manual Installation via Source Code​

Prerequisites​

Before configuring the Salesforce project, ensure you complete these prerequisites:

Setting up Named Credentials and External Credentials​

External Credentials will be used in conjunction with the Named Credential to authenticate and authorize API calls.

To set up External Credentials:​

  1. Navigate to Setup in Salesforce.
  2. In the Quick Find box, enter "Named Credentials" and select it.
  3. Select the External Credentials tab.
  4. Click on New.
  5. Provide a Label and a Name for the Named Credential.
  6. Select Custom for Authentication Protocol.
  7. Create a New Principals.
  8. Provide a Parameter Name and start Add Parameters.
  9. For each Parameter Add provide a Name and the Value of the Parameter (ie. client_id, client_secret)
  10. Click on New for Custom Headers and provide the following information
(Name: Authorization, Value: {!'Basic ' & BASE64ENCODE(BLOB($Credential.{Name_of_External_Credential}.{Name_of_Client_ID_Parameter} & ':' & $Credential.{Name_of_External_Credential}.{Name_of_Client_Secret_Parameter}))}
  1. Click Save

Named Credentials in Salesforce are used to simplify the setup of authenticated callouts to external services. In this project, Named Credentials are used to securely store the API endpoint and secrets required to retrieve the JWT token for authentication.

To set up Named Credentials:​

  1. Navigate to Setup in Salesforce.
  2. In the Quick Find box, enter "Named Credentials" and select it.
  3. Click on New Named Credential.
  4. Provide a Label and a Name for the Named Credential. We recommend using "OCO_Service" as the name. If you choose a different name, be sure to update the reference in the force-app/main/default/classes/NamedCredentials.cls file accordingly.
  5. In the URL field, enter the endpoint URL provided by Optave for the external service.
  6. Check Enabled for Callouts.
  7. Select the External Credential you would like to associate the Named Credentials with.
  8. Ensure Allow Formulas in HTTP Header and Generate Authorization Header is selected.
  9. Click Save.

After saving, you will have a Named Credential set up that can be referenced in your Apex code or REST API integrations to securely retrieve the JWT token and make authenticated calls to the external service.

Setting up Custom Metadata​

Custom Metadata Types in Salesforce allow you to create custom configurations that your applications can use at runtime. In this project, we will create a Custom Metadata Type to store configuration details, including the WebSocket URL.

Creating a Custom Metadata Type​

  1. Navigate to Setup in Salesforce.
  2. In the Quick Find box, enter "Custom Metadata Types" and select it.
  3. Click on New Custom Metadata Type.
  4. Enter a Label for your Custom Metadata Type. This will also auto-populate the Plural Label and Object Name fields. We recommend using "OCO_Metadata". If you choose a different label, be sure to update the reference in the force-app/main/default/classes/OCOSecretController.cls file accordingly and other files.
  5. (Optional) Enter a Description to describe the purpose of this Custom Metadata Type.
  6. Set Deployment Status to "Deployed".
  7. Click Save.

Adding a Field for WebSocket URL​

  1. On the Custom Metadata Type detail page, scroll down to the "Custom Fields" section.
  2. Click on New Field.
  3. Choose Text as the field type and click Next.
  4. Enter a Field Label, for example, "OCOWebsocketURL". This will auto-populate the Field Name.
  5. Set the Length according to your requirements (e.g., 255 characters).
  6. Enter a Description and Help Text if necessary.
  7. Set Field-Level Security and Page Layout settings as required.
  8. Click Save.

Creating a Custom Metadata Record​

  1. Navigate back to Setup.
  2. In the Quick Find box, enter the name of your Custom Metadata Type and select it.
  3. In the "Custom Metadata Records" section, click on Manage Records.
  4. Click on New.
  5. Enter a Label for your record. This will auto-populate the Record Name. We recommend using "Tenant_Record". If you choose a different label, be sure to update the reference in the force-app/main/default/classes/OCOSecretController.cls file accordingly.
  6. In the "WebSocket URL" field, enter the URL of your WebSocket.
  7. Click Save.

After completing these steps, you will have a Custom Metadata Type with a WebSocket URL field and a record containing the WebSocket URL. This setup allows your Salesforce application to dynamically retrieve the WebSocket URL at runtime, providing flexibility and ease of configuration management.

Code Configuration​

Locate NamedCredentials.cls file within the project and ensure it reflects the following​

public with sharing class NamedCredentials {
    @AuraEnabled
    public static string getCred(){
        try {
            HttpRequest req = new HttpRequest();
            req.setEndpoint('callout:Named_Credential_Name?grant_type=client_credentials');
            req.setMethod('POST');
            req.setHeader('Content-Type', 'application/x-www-form-urlencoded');
            Http http = new Http();
            HTTPResponse res = http.send(req);

            return res.getBody();
        } catch (Exception e) {
            throw new AuraHandledException(e.getMessage());
        }
    }
}

Remember to replace Named_Credential_Name with the Named Credentials you have created in Salesforce Setup

Locate the following OCOSecretController.cls file and ensure it reflects the following​

public with sharing class OCOSecretController {
    @AuraEnabled
    public static Custom_Metadata_API_Name getSecret(){
        try {
            Custom_Metadata_API_Name mc = Custom_Metadata_API_Name.getInstance('Record_Name');
            return mc;
        } catch (Exception e) {
            throw new AuraHandledException(e.getMessage());
        }
    }
}

Remember to replace Custom_Metadata_API_Name and Record_Name with the Custom Metadata and Record you have just created in Salesforce Setup

Once you've completed the configuration of the Named Credentials and Custom Metadata, proceed to the steps below to deploy the application to your Salesforce organization.

1

Clone the repository

Clone the repository and navigate to the project directory:

git clone https://github.com/optave/integration-salesforce-oco-PRD.git
cd OCOClient
2

Log in to Salesforce

Authenticate with your Salesforce Organization:

sf auth:web:login -a YourOrgAlias
3

Deploy the application

Run this command in a terminal to deploy the app:

sf project deploy start -d force-app
4

Open your organization

If your org isn't already open, open it now:

sf org open -o YourOrgAlias

Post-Installation Setup​

After installation, add the Optave Assistant to your Salesforce pages to start using its AI capabilities.

Adding the Assistant to Your Salesforce Pages​

To make the Optave Assistant available in your Salesforce environment:

  1. Navigate to Setup > Lightning App Builder
  2. On the left side, locate the agentUI component in the Custom block
  3. Drag and drop the component to your desired location on the page
  4. Save and activate the page

Adding AI Settings to Utility Bar​

To add the AI Settings component to your Utility Bar:

  1. In Salesforce Setup, use the Quick Find box to search for App Manager
  2. Find and select the Service Console application, select Edit
  3. Navigate to the Utility Items section

If you cannot find the "AI Settings" component in Utility Items:

  1. Click Add Utility Item
  2. Search for settings in the Custom list
  3. Select it and click Add
  4. Configure the component properties as needed:
    • Set the label (default is "AI Settings")
    • Adjust panel width and height if necessary
    • Set when the utility item should open (automatically or manually)
  5. Click Save to apply your changes

After adding the utility item, the AI Settings will be available in the utility bar at the bottom of your Service Console, allowing operators to configure their AI assistant preferences.