Sofia Documentation

There are two high-level components to install and configure. The app package installs a various components which are used by the wrapper to embed Oracle Intelligent Advisor into Salesforce user interfaces.

  1. Salesforce App Package
  2. Interview Wrapper Lightning Web Component

Troubleshooting


Sofia Salesforce App Package

Overview

Prerequisites

  1. Installation password for the app package
  2. Oracle Intelligent Advisor Hub and Administrator credentials (Username and Password)
  3. Salesforce 'metadata user' / Admin User credentials (Username and Password+SecurityToken)
  4. Sofia API credentials (Customer Id and Password)

Install the app package

The app package contains a Connected App, Named Credential and supporting Apex classes.

Install at https://<yourorgurl>.salesforce.com/packaging/installPackage.apexp?p0=WILL_BE_PROVIDED

On Installation Page

Configure Named Credential

This Named Credential is used to get an oAuth token for the user running the interview.

Security > Named Credentials > Edit 'Koltevate Sofia' item

Configure Connected App Security

The app must be set up to allow pre-approved user access only, self-authorization is not supported.

App Manager > 'Sofia Connect' > Manage

  1. Edit Policies (button)
  1. Manage Profiles (button)
  1. Manage Permission Sets (button)

Configure Content Security Policy

The Oracle Intelligent Advisor Hub needs to be set up as a Trusted Site so the Lightning Web Component can communicate with the Oracle Intelligent Advisor Hub. Note: this can sometimes take a few minutes to take effect and can require a full page refresh to refresh the policies.

Security > CSP Trusted Sites > New Trusted Site (button)

Add New Connection to the Oracle Intelligent Advisor Hub

Allow CORS requests to the Oracle Intelligent Advisor Hub

Set up your Interview Wrapper Lightning Web Component

Due to security restrictions within the Salesforce platform you are required to deploy your own Lightning Web Component to enable the use of Sofia interviews where LWCs are supported.

A sample SFDX wrapper project is supplied. This wrapper enables support for different Oracle Intelligent Advisor Hub versions and allows you to bundle your own interview extensions and other scripts as required.


Interview Wrapper Lightning Web Component

Due to security restrictions within the Salesforce platform you are required to deploy your own Lightning Web Component to enable the use of Sofia interviews where LWCs are supported.

The wrapper project enables support for different Oracle Intelligent Advisor Hub versions and allows you to bundle your own interview extensions and other scripts as required.

The wrapper contains two main Javascript components:

Overview

Set up your interview wrapper

Prerequisites

Get the source

During beta the source will be provided as a zip file.

Insert your interviews.js and interviews.css

Optional: Add your own interview extensions and scripts

NOTE: Your js and css files will NOT be pulled from the Oracle Intelligent Advisor Hub at runtime for security reasons, so even if they are deployed as part of your Oracle Intelligent Advisor project you MUST also include them here.

See examples in the /force-app/main/default/staticresources/sofiaincludes folder for usage details

Deploy your interview wrapper LWC

Use your interview wrapper

Add your interview wrapper LWC to a Lightning Record Page

Configure your wrapper LWC

NOTE: Your js and css files will NOT be pulled from the Oracle Intelligent Advisor Hub at runtime for security reasons, so even if they are deployed as part of your Oracle Intelligent Advisor project you MUST also include them here.

Record Ids

Where possible (on pages with a record context), the framework will automatically pass the current record's Id to the connector by default. If the interview is configured to Load at Start with the record type of the page, it will be loaded automatically.

This behaviour can be overridden by providing one of the following for the "Record Id Override" (recordIdOverride) property:

Checkpoints

Checkpoints are saved as attachments to a main record. This is the record that is loaded at the start of the interview, so you must have the interview configured to "Load at start" in order to use checkpoints.

Internal Salesforce record detail page:

Communities pages (record detail)

Communities pages (non-record detail)

Checkpoint Attachment Name

Interview Wrapper Lightning Web Component Properties

The properties specified on the wrapper LWC are generally simply passed through to the Oracle Intelligent Advisor JS component that runs the interview. Most parameters take simple values, other behaviour is noted here:

NOTE: Please see the Oracle Intelligent Advisor documentation for details on the other parameters.

Troubleshooting

Supported objects

The connector supports the same set of objects as the Salesforce UI API. The set only contains objects that are supported by the User Interface API and accessible to the context user.

If an object you expect to see is missing you need to adjust Salesforce permissions so your Metadata User can see it. You may also wish to hide certain objects by removing your Metadata User's access to them. This way they will not be included in the Data Model available in Oracle Policy Modeling.

Your Metadata User is the user specified in Add New Connection to the Oracle Intelligent Advisor Hub

Errors refreshing Data Model in Oracle Policy Modeling

This is probably due to authentication issues. Please check the following:

  1. Check that your <org domain prefix> is correct.
  2. Check that your Salesforce Metadata User's user name is correct.
  3. Check that your Salesforce Metadata User's password (password+securitytoken) is correct. Did you recently reset their security token?

For the three items above refer to Add New Connection to the Oracle Intelligent Advisor Hub

  1. Check that the Sofia Connected App is configured as Admin approved users are pre-authorized.
  2. Check that your Salesforce Metadata User's Profile or Permission Set is pre-authorised for the Sofia Connected App.

Error message "Unable to load interview"

  1. Check that you have added the Salesforce URL to the Hub's Interview access control list. See Allow CORS requests to the Oracle Intelligent Advisor Hub.
  2. Check that the Salesforce URL you specified in the Hub's Interview access control list is complete and correct, including the https:// part.
  3. Check that your wrapper's Web Determinations Url setting is complete and correct.
  4. Check that your wrapper's Deployment Name setting is complete and correct.

Error in component "Invalid API credentials"

Check username and password for the Named Credential. See Configure Named Credential.

Error in component "user hasn't approved this consumer"

Change the Connected App's Permitted Users setting to "Admin approved users are pre-authorized" and add the required Profiles or Permissions sets. See Configure Connected App Security.

Error in component "user is not admin approved to access this app"

Add the required Profiles or Permissions sets to the Connected App. See Configure Connected App Security.

Salesforce Picklist fields can appear as normal fields in Policy Modeling

Picklist fields in Salesforce can exist with no picklist items. In this case they are shown in Policy Modeling as their underlying type, ie 'Text' rather than 'Value List(Text)'. Once picklist values are added in Salesforce (and the Data Model refreshed) the same field will be shown in Policy Modeling as a Value List type.

Salesforce Reference Fields

Additional attributes are provided for mapping in the name/title of items referenced by reference fields. This can be useful for displaying information such as the Contact's Account Name, rather than its Account Id. These fields can be mapped in using., eg. Account.Name on the Contact object.

NOTE: These fields are available for input only, not output.

Message "API is disabled for this User"

Enable API access for the Profile of the user:

Setup > Profiles Profile Name System Permissions

Message "You do not have access to the Apex class named 'SfoiaController'."

All users (including Experience Cloud external users) must have access to this Apex class in order to request access tokens from the Sofia connector.

Setup > Apex Classes

Oracle Intelligent Advisor Error Banner in Experience Builder

Configuring the LWC to load a Contact based on ${userContactId} will cause an error in the Builder interface. This is because the internal salesforce user you are logged in as while using the Builder interface does not have a linked Contact record as an external user does. The interview will not display this error when accessed by an external user logged in to the Experience Cloud Site.

Can't install the app package

If you have trouble installing the managed package you might need to enable deployment of non-certified packages. This should not be an issue in sandbox environments.

Setup > Apex Settings

"Additionally, for managed packages, if the managed package is not approved by Salesforce via security review, Apex classes in the package cannot access metadata (public or protected) unless the Deploy Metadata from Non-Certified Package Versions via Apex org preference is enabled. This preference, located under Setup | Apex Settings, must be enabled if admins or developers are installing managed packages that haven’t passed security review for app testing or pilot purposes."

Source: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_metadata_security.htm

Interview won't load and CSP errors logged in the browser's inspector

  1. Check your CSP Trusted Site entry is correct.
  2. The interviews.js you downloaded could be the wrong one. It should be 500KB+. Try downloading from /owda/ path on your hub. See Insert your interviews.js and interviews.css

Error in component "Named Credentials Error: Forbidden"

Check username and password for the Named Credential.

Error in component "Invalid API credentials"

Check username and password for the Named Credential.

Error in component "user hasn't approved this consumer"

Change the Connected App's Permitted Users setting to "Admin approved users are pre-authorized" and add the required Profiles or Permissions sets.

Error in component "user is not admin approved to access this app"

Add the required Profiles or Permissions sets to the Connected App.