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.
Sofia Salesforce App Package
Overview
- Install the app package
- Configure Salesforce
- Configure Oracle Intelligent Advisor Hub
- Configure Salesforce (user interface components)
- Troubleshooting
Prerequisites
- Installation password for the app package
- Oracle Intelligent Advisor Hub and Administrator credentials (Username and Password)
- Salesforce 'metadata user' / Admin User credentials (Username and Password+SecurityToken)
- 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
- Provide installation password
- Select install for All Users
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
- Username:
Your Sofia API customer id
- Password:
Your Sofia API password
- Allow Merge Fields in HTTP Header:
checked
- Save
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
- Edit Policies (button)
- Permitted Users:
Admin approved users are pre-authorized
- Press OK if you see a warning "Enabling this option will result in all users currently using this app being denied access. Please reference the Connected Apps OAuth Usage Report if you are unsure who is using the app."
- Save
- Manage Profiles (button)
- Add profiles that are pre-approved to run interviews
- Add Customer Community User profiles, if required
- Add Partner Community User profiles, if required
- Save
- Manage Permission Sets (button)
- If required
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)
- Trusted Site Name:
Oracle Intelligent Advisor Hub
- Trusted Site URL:
<base url of your Oracle Intelligent Advisor Hub>
(eg.https://xxxx.custhelp.com
) - Context:
All
- Allow site for connect-src:
checked
- Allow site for font-src:
checked
- Allow site for img-src:
checked
- Allow site for style-src:
checked
- Save
Add New Connection to the Oracle Intelligent Advisor Hub
- Log in to your Oracle Intelligent Advisor Hub
- eg.
https://xxxx.custhelp.com/opa-hub
- eg.
- Connections page > Create (button)
- Name:
My Sofia Connection
- Type:
Web service (Connector framework)
- Workspace access: At least one Collection checked
- URL:
https://sofiabeta.koltevate.com/sofia/<org domain prefix>
- Your
<org domain prefix>
is the first part of your Salesforce domain name, up to the first '.' - If the URL in your browser in Salesforce is
https://force-power-12345-dev-ed.lightning.force.com/
then your<org domain prefix>
isforce-power-12345-dev-ed
- Your
- Version:
12.2.18
- Present this certificate: Not used in beta
- Provide OAUTH bearer token in HTTP header on Load, Save, GetCheckpoint, SetCheckpoint and ExecuteQuery actions:
checked
- URL parameter:
token
- URL parameter:
- Provide WS-Security username token in SOAP actions:
checked
- Username:
Your Salesforce metadata user name
- Password:
Your Salesforce metadata user password+securitytoken
- Applies To:
All
- Username:
- Apply
- Name:
Allow CORS requests to the Oracle Intelligent Advisor Hub
- Log in to your Oracle Intelligent Advisor Hub
- eg.
https://xxxx.custhelp.com/opa-hub
- eg.
- Permissions page > 'overflow' menu > Access Settings
- Interview access control > Add Host (button)
<yourfullsalesforceorgurl>
eg.https://force-power-12345-dev-ed.lightning.force.com/
- Apply
- Add entries for your Experience Cloud sites here as required
- Builder interface (Live Preview)
- eg.
https://<yourdomainprefix>.livepreview.salesforce-communities.com
- eg.
- Runtime interface
- eg.
https://<yourdomainprefix>.cs<num>.force.com
- eg.
- Builder interface (Live Preview)
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:
- SofiaWrapper.js: the LWC which will be exposed in your Salesforce environment. Its primary function is to gather the parameters required to launch the interview.
- koltevateSofia.js: a compiled and minified library that interfaces with the Apex classes and other objects installed with the main app package.
Overview
- Set up your interview wrapper
- Use your interview wrapper
- Troubleshooting
Set up your interview wrapper
Prerequisites
- SFDX command line client (https://developer.salesforce.com/tools/sfdxcli)
Get the source
During beta the source will be provided as a zip file.
Insert your interviews.js and interviews.css
- Download the interviews.js and interviews.css files from your Oracle Intelligent Advisor Hub
- eg.
https://xxxx.custhelp.com/opa-hub/owda/staticresource/interviews.js
- OR
https://xxxx.custhelp.com/opa-hub/web-determinations/staticresource/interviews.js
- NOTE: The correct interviews.js should be 500KB+, your hub might serve different versions at each URL listed above.
- eg.
https://xxxx.custhelp.com/opa-hub/web-determinations/staticresource/interviews.css
- eg.
- Copy the downloaded files into this project's
/force-app/main/default/staticresources/sofiaincludes
folder
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.
- Copy your own js and css files into the
/force-app/main/default/staticresources/sofiaincludes
folder - You can specify which scripts/css to load for each LWC interview instance
- Extension files: Comma-separated list of js files to load for the interview
- Style files: Comma-separated list of css files to load for the interview
See examples in the /force-app/main/default/staticresources/sofiaincludes
folder for usage details
Deploy your interview wrapper LWC
sfdx force:source:push
into your org- OR
sfdx force:source:deploy -p force-app
- OR add your LWC to a package to distribute to other orgs
Use your interview wrapper
Add your interview wrapper LWC to a Lightning Record Page
- Edit the page (eg Account)
- Drag and drop your interview wrapper LWC (Custom > Sofia Wrapper) onto the page
Configure your wrapper LWC
- Web Determinations Url: the URL of your Oracle Intelligent Advisor web-determinations (eg.
https://xxxx.custhelp.com/opa-hub/web-determinations
) - Deployment Name: the name of the project/deployment (eg.
BusinessLicenseWizard
) - Extension Files (comma separated): a list of js files you need loaded from the
sofiaincludes
folder (eg.extensions.js,loadFunction.js
) - Style Files (comma separated): a list of css files you need loaded from the
sofiaincludes
folder (eg.mycss.css
)
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.
- Anonymous: If
true
, no Salesforce security context will be established. Use of a connector will not be possible. Useful for non-connected interviews only.
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:
${userId}
will pass the Id of the current user's User record,${userContactId}
will pass the Id of the current user's Contact record, which will be populated for Communities users and NULL for internal Salesforce users,<Specific Record Id>
will pass the specified record Id to the connector.
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:
- In this case, the framework will automatically pass the current record's Id to the connector by default. By default the checkpoint will be created as an attachment to the current record, with the name
<Deployment Name>.cpt
.
Communities pages (record detail)
- Similarly, the framework will automatically pass the current record's Id to the connector by default. By default the checkpoint will be created as an attachment to the current record, with the name
<Deployment Name>.cpt
.
Communities pages (non-record detail)
- On pages such as the home page and record lists, the framework can not automatically pass the current record's Id to the connector. You must supply an Id by specifying either the User's Id or the User's Contact Id using the "Record Id Override" property. By default the checkpoint will be created as an attachment to the loaded record, with the name
<Deployment Name>.cpt
. - You can have several in-progress interview checkpoints attached to the loaded record (such as User or Contact). By default one checkpoint will be maintained for each "Deployment Name" but that can be increased using the "Checkpoint Name" property.
Checkpoint Attachment Name
- The default attachment name
<Deployment Name>.cpt
can be overridden using the "Checkpoint Name" (checkpointName) property. This enables you to deploy the same interview multiple times on the same, or different, pages and maintain separate checkpoints for each deployment. - The value specified for "Checkpoint Name" will be used exactly for the attachment name (no extension will be added).
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:
- Params (JSON): A JSON formatted parameters object you want to pass to the connector. eg.
{ "param1": "value", "param2": "value" }
- Note:
token
,id
,deploymentName
andcheckpointName
are reserved so any value you set could be overridden by the Koltevate component.
- Note:
- Seed Data (JSON): JSON formatted seed data you want to pass to the Oracle Intelligent Advisor session. eg.
{ "attribute1": "value", "attribute2": "value" }
- Load Function Name: The name of a function you supply (via the
/sofiaincludes
folder) which will be attached to the interview's onLoad event. The function is expected to be attached towindow['<loadFunctionName>']
. - Navigate Function Name: The name of a function you supply (via the
/sofiaincludes
folder) which will be attached to the interview's onNavigate event. The function is expected to be attached towindow['<navigateFunctionName>']
. - Dirty Change Function Name: The name of a function you supply (via the
/sofiaincludes
folder) which will be attached to the interview's onDirtyChange event. The function is expected to be attached towindow['<dirtyChangeFunctionName>']
. - Can Restart Function Name: The name of a function you supply (via the
/sofiaincludes
folder) which will be attached to the interview's canRestart handler. The function is expected to be attached towindow['<canRestartFunctionName>']
. - Error Style (JSON), Redirector Button Style (JSON): A JSON-formatted style tag as expected by Oracle Intelligent Advisor.
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:
- Check that your
<org domain prefix>
is correct. - Check that your Salesforce Metadata User's user name is correct.
- 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
- Check that the Sofia Connected App is configured as
Admin approved users are pre-authorized
. - 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"
- 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.
- Check that the Salesforce URL you specified in the Hub's Interview access control list is complete and correct, including the https:// part.
- Check that your wrapper's Web Determinations Url setting is complete and correct.
- 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
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
- API Enabled:
checked
- Save
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
- SfoiaController > Security
- Add the required profiles
- Save
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
- Deploy Metadata from Non-Certified Package Versions:
checked
"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
- Check your CSP Trusted Site entry is correct.
- 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.