Embed Oracle Sales Accelerator Into Other Applications
Introduction
Oracle Sales Accelerator can be embedded into other applications, which shows Sales Accelerator content within another application’s user interface.
There are two ways to embed Sales Accelerator into other applications:
- Using the Embed API [preferred method]
- Using URL parameters
Here’s an example of Sales Accelerator embedded into another application:
Embed Sales Accelerator Using the Embed API
The recommended way to embed Oracle Sales Accelerator into other applications is by using the Embed API. The Embed API allows you to show the Sales Accelerator user interface within an iframe inside other applications. It allows users to make selections from search results and pass in the IDs for further processing.
As an alternative, you can also use URL parameters to embed Sales Accelerator, but that can only be used for consumption (read-only) purposes. It’s recommended that you use the Embed API wherever possible.
The Embed API for Oracle Sales Accelerator is accessed through a simple JavaScript file, which can be obtained and referenced using an HTML <script> tag:
<script type="text/javascript" src="https://<server>/sa/sa-embed.js"></script>
This JavaScript API defines the OracleSAUI namespace, which provides access to the embeddable components. Before any component iframe can be created, the API needs to be initialized with the address of the target Oracle Sales Accelerator system. This is done by setting the url property:
OracleSAUI.url = "https://server-instance.example.com";
Once the Sales Accelerator system URL is set, you can use the createFrame() function for the desired component to create an iframe DOM object. The createFrame() function accepts an options object for customizing the features of the embeddable UI and an events object containing callback functions.
var frameElement = OracleSAUI.searchView.createFrame(options, events);
document.body.appendChild(frameElement);Options for Embedding Sales Accelerator
The options parameter to the createFrame() function is a simple JavaScript object containing properties for each of the embeddable components. Currently, the only property that’s supported is searchView, which can have the options shown in the table below.
When passing any names of products, industries, locations, etc., make sure that these are properly encoded using standard HTML URL encoding so they can work as URL parameters. For example, if a product name is “Consulting, Support & Education,” then it needs to be passed as “Consulting%2C%20Support%20%26%20Education” (%2C translates to comma, %20 to space, and %26 to ampersand).
| Property | Type | Values | Description |
|---|---|---|---|
| searchView { | |||
| “contentTypeFilter”: [] | string |
The default for this option is All (that is, show all content types). You can use this to open the view for a particular content type, for example: “Customer Stories” |
|
| “showSelection”: ““ | string | [“true” | “false”] |
Show or hide check boxes in Sales Accelerator table view. Check boxes are shown only if true is passed.
|
| “layout”: ““ | string | [“table” | “grid” | “list”] | Show items in Sales Accelerator in the specified layout: table, grid, or list. The default is table. |
| “selectedStories”: [] | array | [“id-1”, “id-2”, “id-n”] | The IDs of story content items that should be preselected. |
| “theme”: ““ | string | [“light” | “dark”] | Set the Oracle Sales Accelerator UI theme to light or dark. The default is dark. |
| filterValue { | |||
| “advanced”: [] | array | [“advanced-1”, “advanced-2”, “advanced-n”] |
Preselect the advanced filter values, for example: “Only Public Stories” |
| “storyType”: [] | array | [“type-1”, “type-2”, “type-n”] |
Preselect the story type filter values, for example: “Go Live Story” |
| “product”: [] | array | [“product-1”, “pillar;product-line;product-2”, “product-n”] |
Preselect the product filter values. You can specify only the product name, or include other hierarchical levels (for example, “pillar;product-line;product-name”). You can skip hierarchical levels by including “empty” semicolons in your values. For example, to filter at the product level and skip the pillar and product line, use something like “;;Consulting%2C Support %26 Education. Examples Complete hierarchy: “Hardware Engineered Systems;Private Cloud;Engineered Systems” Pillar-based filter: “Hardware Engineered Systems” Product line based filter: “;Private Cloud” Product-based filter: “;;Engineered Systems” You can use the functional product hierarchy or the marketing product hierarchy. For the functional product hierarchy, make sure to set mapProducts to ‘true’ (see below) so that the products are mapped to the marketing taxonomy and then filtered based on that. |
| “productCondition”: ““ | string | [“AND” | “OR”] | Specify whether any selected items should match any (OR) or all (AND) criteria. The default is OR. |
| “salesplay”: [] | array | [“salesplay-1”, “salesplay-2a;salesplay-2b;salesplay-2c”, “salesplay-n”] |
Preselect the sales play filter values. You can use semicolons (;) to separate different hierarchical levels, for example: “Automating Safety with Artificial Intelligence (AI);Artificial Intelligence;Safety” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “industry”: [] | array | [“industry-1”, “industry-2a;industry-2b;industry-2c”, “industry-n”] |
Preselect the industry filter values. You can use semicolons (;) to separate different hierarchical levels, for example: “Insurance;Retail” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “location”: [] | array | [“location-1”, “location-2”,“region;country”, “location-n”] |
Preselect the location filter values. You can use semicolons (;) to separate different hierarchical levels, for example: “EMEA;Western Europe;France” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “assetType”: [] | array | [“assettype-1”, “assettype-2”, “assettype-n”] |
Preselect the asset type filter values, for example: “External Press Release” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “advanced: []” | array | [“advanced-1”, “advanced-2”, “advanced-n”] |
Preselect the advanced filter values, for example: “Only Public Stories” |
| “storyAssetVisibility: []” | array | [“Internal Only”, “Partner and Internal”, “Public”] |
Preselect the visibility filter values. This is applicable only when the selected content type is Assets or Customer Stories. For customer stories, this returns stories with at least one featured asset with the specified visibility level. For assets, this returns assets with the specified visibility level. |
| “storyType: []” | array | [“storytype-1”, “storytype-2”, “storytype-n”] |
Preselect the story type filter values, for example: “Go-Live Story” |
| “usecase”: [] | array | [“usecase-1”, “usecase-2a;usecase-2b;usecase-2c”, “usecase-n”] |
Preselect the use case filter values. You can use semicolons (;) to separate different hierarchical levels, for example: “Industry Conversations;Media and Telecommunications;Employee Engagement” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “competitor”: [] | array | [“competitor-1”, “competitor-2”, “competitor-n”] |
Specify the name of a competitor, for example: “Big Computers” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “vendor”: [] | array | [“vendor-1”, “vendor-2”, “vendor-n”] |
Specify the name of vendor, for example: “Seven Corporation” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “customer”: [] | array | [“customer-1”, “customer-2”, “customer-n”] |
Specify the name of customer, for example: “Blue Semiconductor” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “partner”: [] | array | [“partner-1”, “partner-2”, “partner-n”] |
Specify the name of partner, for example: “Vision Corporation” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| “search”: [] | array | [“search-1”, “search-2”, “search-n”] |
Preselect the search keywords, for example: “big data retail” Make sure that you encode the array values properly, so they can be used as URL parameters. |
| hideFilters { | |||
|
“hideFilters”: { |
object |
“hideFilters”: { |
Under hideFilters, the filterTypes option allows you to specify any filter names that should be hidden. Filters will be hidden from both the filter list and predictive searching. The following filters can currently be hidden:
|
| “contributorView”: ““ | string | [“true” | “false”] | Enable or disable contributor mode. This will override the switch—that is, the switch is shown and set to ‘true’ if this option is set to ‘true’. The default is ‘false’. |
| “enableContributorMode”: ““ | boolean | [“true” | “false”] | Show or hide the contributor switch. The default is ‘true’—that is, the switch is displayed. |
|
“mapProducts”: ““ |
string | [“true” | “false”] |
This option defines whether functional products need to be mapped to marketing products. If this is set to ‘false’, marketing products are assumed. This works only for Customer Stories as the content type. |
|
“srcOrg”: [] |
string | [“org-1”, “org-2”, “org-n”] |
This is used to track embedded UI access sources in Oracle Sales Accelerator. This is supported in all content type options. |
|
“tracking”: [] |
string | [“track-1”, “track-2, track-n”] |
This is used to log tracking IDs passed by embedded UI sources. |
Here’s a sample options object that could be used for an Engineered Selling use case that should filter customer stories based on industry, location, and products.
var options = {
"component": "searchView",
"name": "Sales Accelerator (SA) Embed UI",
"searchView": {
"showSelection": "true",
"layout": "table",
"selectedStories": ["COREBE0ED40DE4F14DEAAC3A0082D1CD79D6"],
"filterValue": {
"product": ["Strategic Marketing and Advertising","Sales and Service;Sales;- Content Management",";;- Field Service"],
"productCondition": "OR",
"salesplay":["Automating Safety with Artificial Intelligence (AI);Artificial Intelligence;Safety"],
"industry": ["Retail","Hospitality"],
"location": ["APAC;India","EMEA"],
"assetType": ["Customer Presentation"],
"competitor": ["Big Computers"],
"usecase":["Industry Language Conversations;Other"],
"vendor": ["Seven Corporation"],
"storyType":["Sales Story"],
"customer": ["Blue Semiconductor"],
"partner": ["Vision Corporation"],
"advanced":["Only Public Stories"],
"storyAssetVisibility":["Public"],
"search": ["Story"]
},
"hideFilters": {
filterTypes: ["advanced"]
},
"mapProducts": "true",
"contentTypeFilter" : "Customer Stories",
"srcOrg" :["DSR"],
"tracking" :["CONT123"],
"theme":"light"
}
}Events
User activity with the embedded web UI will trigger a specific event. You can enable event handler functions for these events by providing them in the events parameter of the createFrame() function. The events in the table below are currently supported for customer stories.
| Event | Argument | Description |
|---|---|---|
| selectionChanged(frameElement, selection) |
frameElement: the frame element triggering the event. selection.selection: the id and name of the current selection. selection.selections: the id, name, and reference object of all selected items in the list. |
Fired when the selection changes within the embedded view. The selection argument contains the current selection and the list of selections in the list view. |
Here’s an example, where the selectionChanged event is handled for the embeddedStories view:
var events = {
selectionChanged: function(frame, selection) {
document.getElementById("ids").innerHTML+= JSON.stringify(selection);
}
};Sample HTML Pages Embedding Sales Accelerator
Below are two sample HTML pages that could be used for an Engineered Selling use case that should filter customer stories based on industry, location, and products.
With a marketing product hierarchy (“mapProducts”: false):
<html>
<head>
<script src="https://<server>/sa/sa-embed.js"></script>
</head>
<body style="height:1000px">
<h1> This is sample page which embeds Sales Accelerator</h1>
<h2> IDs of the items selected:</h2>
<span id='ids'> </span>
<div id="SAFrame" style="width:100%;height:100%"> </div>
<script type="text/javascript">
var options = {
"component": "searchView",
"name": "Sales Accelerator (SA) Embed UI",
"searchView": {
"contentTypeFilter" : "Customer Stories",
"showSelection": "true",
"layout": "table",
"selectedStories": ["COREBE0ED404DFF14DEAAC3A0082D1CD79D6"],
"filterValue": {
"product": ["Strategic Marketing and Advertising","Sales and Service;Sales;- Content Management",";;- Field Service"],
"productCondition": "OR",
"salesplay":["Automating Safety with Artificial Intelligence (AI);Artificial Intelligence;Safety"],
"industry": ["Retail","Hospitality"],
"location": ["APAC;India","EMEA"],
"assetType": ["Customer Presentation"],
"competitor": ["Big Computers"],
"usecase":["Industry Language Conversations;Other"],
"vendor": ["Seven Corporation"],
"storyType":["Sales Story"],
"customer": ["Blue Semiconductor"],
"partner": ["Vision Corporation"],
"advanced":["Only Public Stories"],
"storyAssetVisibility":["Public"],
"search": ["Story"]
},
"hideFilters": {
filterTypes: ["sales play"]
},
"mapProducts": false,
"contentTypeFilter" : "Customer Stories",
"enableContributorMode": true,
"contributorView":false,
"srcOrg" :[""],
"tracking" :[""],
"theme":"light"
}
}
var events = {
selectionChanged: function(frame, selection) {
console.log("In selectionChanged");
document.getElementById("ids").innerHTML+= "</br></br>"+JSON.stringify(selection);
}
};
OracleSAUI.url = "https://server-instance.example.com"
let frameElement = OracleSAUI[options.component].createFrame(options, events);
console.log(frameElement);
document.getElementsByTagName("div")[0].appendChild(frameElement);
</script>
</body>
</html>With a product mapping hierarchy (“mapProducts”: true):
<html>
<head>
<script src="https://<server>/sa/sa-embed.js"></script>
</head>
<body style="height:1000px">
<h1> This is sample page which embeds Sales Accelerator</h1>
<h2> IDs of the items selected:</h2>
<span id='ids'> </span>
<div id="SAFrame" style="width:100%;height:100%"> </div>
<script type="text/javascript">
var options = {
"component": "searchView",
"name": "Sales Accelerator (SA) Embed UI",
"searchView": {
"contentTypeFilter" : "Customer Stories",
"showSelection": false,
"layout": "list",
"selectedStories": ["CORE52E29EC94042710EF78A8D778","CORE9D0B7E22166681B7B587293C1260"],
"filterValue": {
"product": ["Strategic Marketing and Advertising","Sales and Service;Sales;- Content Management",";;- Field Service"],
"productCondition": "OR",
"industry": ["Healthcare","Communications"],
"location": ["EMEA"],
"assetType": ["Customer Presentation"],
"competitor": ["Big Computers"],
"vendor": ["In-House Development"],
"customer": ["Blue Semiconductor"],
"partner": ["Vision Corporation"],
"advanced":[],
"usecase":["Industry Language Conversations;Automotive OEM"],
"storyType":[""],
"storyAssetVisibility":[""],
"salesplay":[""],
"search": ["SA Automation"]
},
"hideFilters": {
filterTypes: []
},
"mapProducts": true,
"contentTypeFilter" : "Customer Stories",
"enableContributorMode": true,
"contributorView":false,
"srcOrg" :[""],
"tracking" :[""],
"theme":"light"
} }
var events = {
selectionChanged: function(frame, selection) {
console.log("In selectionChanged");
document.getElementById("ids").innerHTML+= "</br></br>"+JSON.stringify(selection);
}
};
OracleSAUI.url = "https://server-instance.example.com"
let frameElement = OracleSAUI[options.component].createFrame(options, events);
console.log(frameElement);
document.getElementsByTagName("div")[0].appendChild(frameElement);
</script>
</body>
</html>Embed Sales Accelerator Using URL Parameters
The recommended way to embed Oracle Sales Accelerator into other applications within an iframe is by using the Embed API. As an alternative, you can also use URL parameters to embed Sales Accelerator.
If you embed Sales Accelerator using URL parameters, the content can only be used for consumption (read-only) purposes. It does not allow users to make selections from search results and pass in the IDs for further processing.
It’s recommended that you use the Embed API unless this is not feasible.
Here’s what using URL parameters looks like:
https://<server>/sa?<query-parameters>
URL Parameters
The following table lists the options you can use in the URL parameters.
When passing any names of products, industries, locations, etc., make sure that these are properly encoded using standard HTML URL encoding so they can work as URL parameters. For example, if a product name is “Consulting, Support & Education,” then it needs to be passed as “Consulting%2C%20Support%20%26%20Education” (%2C translates to comma, %20 to space, and %26 to ampersand).
| Parameter | Value | Description |
|---|---|---|
| contentTypeFilter | <contentTypeFilter> |
The default for this option is All (that is, show all content types). You can use this to open the view for a particular content type. For example, to open the view for customer stories, set this to |
| product |
<productName>+ <productName>… |
Preselect the product filter value. You can specify only the product name, or include other hierarchical levels (for example, “pillar;product-line;product-name”). You can skip hierarchical levels by including “empty” semicolons in your values. For example, to filter at the product level and skip the pillar and product line, use something like “;;Consulting%2C Support %26 Education.br> Make sure that you encode the array values properly, so they can be used as URL parameters. Examples Complete hierarchy: <Hardware Engineered Systems;Private Cloud;Engineered Systems> Pillar-based filter: <Hardware Engineered Systems> Product line based filter: <;Private Cloud> Product-based filter: <;;Engineered Systems>
You can use the functional product hierarchy or the marketing product hierarchy. For the functional product hierarchy, make sure to specify |
| productCondition | AND | OR | Specify whether any selected items should match any (OR) or all (AND) criteria. The default is OR. |
| industry |
<industryName>+ <industryName>… |
Preselect the industry filter value. You can use semicolons (;) to separate different hierarchical levels, for example: Insurance;Retail Make sure that you encode the values properly. |
| salesplay |
<salesPlay>+ <salesPlay>… |
Preselect the sales play filter value. You can use semicolons (;) to separate different hierarchical levels, for example: [“Automating Safety with Artificial Intelligence (AI);Artificial Intelligence;Safety”] Make sure that you encode the values properly. |
| storyType |
<storyType>+ <storyType>… |
Preselect the story type filter value, for example: “Go-Live Story” |
| location |
<location>+ <location>… |
Preselect the location filter value. You can use semicolons (;) to separate different hierarchical levels, for example: “EMEA;Western Europe;France” Make sure that you encode the values properly. |
| assetType |
<assetType>+ <assetType>… |
Preselect the asset type filter value, for example: “External Press Release” Make sure that you encode the values properly. |
| search |
<seach-keyword>+ <search-keyword>… |
Preselect the search keywords, for example: big data retail Make sure that you encode the values properly. |
| layout |
grid | table | list |
Shows items in Sales Accelerator in the specified layout: table, grid, or list. The default is table. |
| showSelection | true | false |
Show or hide check boxes in Sales Accelerator table view. Check boxes are shown only if true is passed.
|
| usecase |
<usecase>+ <usecase>… |
Preselect the use case filter value. You can use semicolons (;) to separate different hierarchical levels, for example: Industry Conversations;Media and Telecommunications;Employee Engagement Make sure that you encode the values properly. |
| competitor |
<competitorName>+ <competitorName>… |
Specify the name of a competitor, for example: Big Computers Make sure that you encode the values properly. |
| vendor |
<vendorName>+ <vendorName>… |
Specify the name of a vendor, for example: Seven Corporation Make sure that you encode the values properly. |
| customer |
<customerName>+ <customerName>… |
Specify the name of a customer, for example: Blue Semiconductor Make sure that you encode the values properly. |
| partner |
<partnerName>+ <partnerName>… |
Specify the name of a partner, for example: Vision Corporation Make sure that you encode the values properly. |
| theme | light | dark | Set the Sales Accelerator UI theme to light or dark. The default is ‘dark’. |
| contributorView | true | false | Enable or disable contributor mode. This will override the switch—that is, the switch is shown and set to ‘true’ if this option is set to ‘true’. The default is ‘false’. |
| enableContributorMode | true | false |
Allow or disallow contributors to switch between modes directly in their user profile menu. The default is ‘false’—that is, they can’t directly switch modes. |
| advanced | <advanced> |
Preselect the advanced filter value, for example: Only Public Stories |
| assetVisibility | <visibility> |
Preselect the visibility filter value, for example ‘public’. This is applicable only when the selected content type is Assets or Customer Stories. For customer stories, this returns stories with at least one featured asset with the specified visibility level. For assets, this returns assets with the specified visibility level. |
| language | <language> |
Preselect the visibility filter value, for example ‘English’. This is applicable only when the selected content type is Assets. |
| format | <format> |
Preselect the format filter value, for example ‘PDF’. This is applicable only when the selected content type is Assets. |
| mapProducts | true | false |
This option defines whether functional products need to be mapped to marketing products. If this is set to ‘false’, marketing products are assumed. This works only for customer stories as the content type. Example
|
| srcOrg | <srcOrg> |
This is used to track embedded UI access sources in Oracle Sales Accelerator. This is supported in all content type options. Example org1,org2… |
| tracking | <tracking> |
This is used to log tracking IDs passed by embedded UI sources. Example track1,track2… |
Examples
Here are some examples of URLs with parameters that can be used to embed Sales Accelerator into other applications.
Use case 1: pass one product and one location
https://<server>/sa?product=Oracle%20Cloud%20Infrastructure&location=NAS%3BUnited%20States
Use case 2: provide two parameters in the URL with the same key
Example 1: https://<server>/sa?contentTypeFilter=Customer%20Stories&showSelection=true&layout=table
Example 2: https://<server>/sa?contentTypeFilter=Customer%20Stories&showSelection=true&layout=table&showSelection=false
In example 2, the last instance of the showSelection parameter will be honored, so the value will be set to false.
Use case 3: provide multiple parameters
https://<server>/sa?product=Cloud%20Infrastructure%3BDatabase+Cloud%20Infrastructure+Cloud%20Applications%3BEnterprise%20Resource%20Planning%20%28ERP%29%3BEnterprise%20Performance%20Management&industry=Communications+Financial%20Services&location=APAC+EMEA%3BMiddle%20East%3BBahrain
Use case 4: change the Sales Accelerator UI theme
https://<server>/sa?contentTypeFilter=Customer%20Stories&theme=light
Embed Oracle Sales Accelerator Into Other Applications
F49624-02
July 2023
Copyright © 2021, 2023, Oracle and/or its affiliates.
Primary Author: Oracle Corporation