1. Knowledge Articles
  2. Administration

1 Administration

This chapter contains OGL Administration knowledge articles.

Deployment Best Practices

Guided Learning support two deployment modes out of the box: development mode and production mode.

You can determine whether Guided Learning will work in production mode or in development mode by setting the env variable in the embed code. Refer to our FAQ about setting up Guided Learning below.

Production Mode

Production mode should be used in your live application; this is where your users engage with the guides that you have published.

In production mode Guided Learning:

  • Displays only published versions of your guides. That is, if a guide is not published it will not be available.
  • Uses the our CDN to cache your guides for better latency and high availability.
  • Uses your internal browser cache to store recently used guides.

Development Mode

Development mode is where you create, edit and test your guides before publishing them.

In development mode Guided Learning:

  • Displays the newest versions of your guides even if they are not published yet.
  • Does not use any type of caching so that changes that you make are immediately propagated without any delay.

It is highly recommended to embed Guided Learning in development mode in your staging environment that is the environment where you run all your tests before you release to production. This enables the training professionals to create and test the guides on the newest features and improvements before they are released to production.

Supported Custom Scripts for OGL

What is a Custom Script?

A Custom Script is simply an OGL JavaScript that allows us to control key features of OGL such as Multi-language support, Role Mapping, etc.

Where do I find the Custom Script field?

Open the Configure Guided Learning task in Setup and Maintenance. The Custom Script field is in the Advanced Settings section of the page. Refer to the image below:
image highlighting location of custom script field

IMPORTANT: Always use Paste as Plain Text when pasting into the Custom Script field.

Which OGL features require a Custom Script?

  • Custom Role Mapping
  • Enabling Multi-Language for OGL
  • Cross Domain Support
  • Cross Application Support
  • Country Segmentation Support
  • EMEA Tenancy
  • Third Party URL
  • Adding Varset for customer who has more than 300+ characters

Custom Role Mapping

Use a Custom Script for role mapping only if the method outlined in the Configuring OGL - Setting Roles and Scriptsguideline is not suitable for your application. Add the below lines to the Custom Script field:

var user_role = '';if(#{securityContext.userInRole['REPLACE_WITH_FUSION_ROLE_CODE']}){user_role+='|replace_with_preferred_role_name|';}

window.ir_fields.user_role+=user_role;

IMPORTANT: Ensure these lines precede any existing Custom Script in the field. You can include additional roles by duplicating the entire IF STATEMENT: if(#{securityContext.userInRole['REPLACE_WITH_FUSION_ROLE_CODE']}){user_role+='|replace_with_preferred_role_name|';}

Enable Multi-Language for OGL

By default, OGL is set to support one primary language. For Multi-language deployments of OGL, add the below lines to the Custom Script field:

iridize.supported_langs = ['--','fr', 'nl', 'ja', 'it', 'de', 'es'];

iridize.lang = document.documentElement.lang == "en" ? "--" : document.documentElement.lang.toLowerCase();

iridize.lang = iridize.supported_langs.indexOf(iridize.lang) >= 0 ? iridize.lang : '--';

Note:Update your supported languages with the relevant language codes. This applies only to the languages translated in the OGL account and not the application languages. For instance, if a client provides the Oracle application in English, French, and Spanish, and the OGL account only provides English and Spanish, the user will only be able to see OGL in English or Spanish from the OGL Help Panel.

Cross Domain Support

In cases where OGL is required on a page/work area in the application which is in an iFrame (meaning the iFrame loads content from a different location on the same domain), we need to add the below line in the Custom Script field:

iridize.stateOnly=window != top ? true : undefined;

Cross Application Support

If your Fusion application links to another application (i.e. CPQ) and requires OGL to work seamlessly between the two applications, you need to enable cross application support by adding the below line in the Custom Script field.

iridize.crossAppIframe=true;

Country Segmentation Support

To map guides based on the user's country, add the below line in the Custom Script field:

window.ir_fields["user_country"] = "#{Profile.values.FND_TERRITORY}";

EMEA Tenancy

By default, OGL will point to OCI-NAMER-Production Tenancy (guidedlearning.oracle.com) in all the fusion applications. This should be changed for EMEA customers by adding the below lines in Custom Script. 

iridize.jsPrefix= "https://guidedlearning-emea.oracle.com/player/latest/static";
iridize.reportPrefix= "https://guidedlearning-emea.oracle.com/player/latest";

Note: This is required only for EMEA Tenancy customers.

Third Party URL

To fetch a third party URL from fusion we need to add below line into Custom Script. In the below.

For example ‘3rdPartyPageName’ is the page of the URL we are trying to fetch.

iridize("api.vars.set", {"thirdPartyUrl":"#{EndPointProvider.externalEndpointByModuleShortName[‘<<3rdPartyPageName>>']}"});

Note: Replace the 3rd party page name in the << >> parenthesis.

Adding Varset for customer who has more than 300+ characters

To fetch more than 300+characters from the JS:

iridize("api.vars.set", window.ir_fields);

Below code is not required / redundant

For mobiles guide deployment in Fusion Embed:

var ogl_mobile =
'phone'=='#{requestContext.agent.type}'||('simpleMobile'=='#{
applcoreShellBean.shellType}');
iridize("api.vars.set", { ogl_mobile : ogl_mobile });

How to Enable OGL in CPQ

Because CPQ is a non-Fusion instance, we can use the default JS which is available in setup.

  1. Copy the code
    image of setup menu with JS for copy to clipboard

  2. In CPQ Cloud, from Administration Platform, select Header & Footer from Style and Templates
    image of administration platform menu in CPQ cloud

  3. In Header & Footer page add your JS (which is copied to either Header HTML or Footer HTML) then select Accept
    image of header and footer menu

Possible Errors:

Widget may not appear on any page except the header and footer page.

To fix this, add this line of code just below the iridize.env line:

iridize.loadJQuery=true;

Note: If you are trying to use a cross app functionality please add the below line into JS. 

iridize.crossAppIframe=true;

How to Participate in Oracle Guided Learning UAT

The OGL Console is available at https://guidedlearning-uat.oracle.com.

To access, please use the same login information that is used for the production environment. The UAT environment will have a snapshot of data on Production taken during the week leading up to the UAT. The data set that OGL Analytics pulls from, therefore, will be static throughout the UAT, so any activity during the UAT will not reflect in the Analytics Dashboard. Please note that any work done on UAT will not be saved and will be wiped out when the environment is taken down after 20D is live.

Oracle Guided Learning is integrated with its host application either via a JavaScript snippet or a browser extension. Making the update so that your application connects to UAT is simple, but the steps are a little different depending on how OGL is implemented.

Step-by-step guide

JavaScript

In the JavaScript there will be one line of code that reads as follows:

("https:"==document.location.protocol?"https:":"http:")+"//guidedlearning.oracle.com/player/latest/static/js/iridizeLoader.min.js";e.type="text/javascript";e.async=true;t.parentNode.insertBefore(e,t);})();

Replace

guidedlearning.oracle.com

with

https://guidedlearning-uat.oracle.com/

Extension

Locate the extension.js and chrome.js files in the js/src folder of the OGL extension.

extension.js

In the extension.js file, there will be a line of code that reads as follows:

'(function(){var e=document.createElement("script");var t=document.getElementsByTagName("script")[0];e.src=("https:"==document.location.protocol?"https:":"http:")+"//guidedlearning.oracle.com/player/latest/static/js/iridizeLoader.js";e.type="text/javascript";e.async=true;t.parentNode.insertBefore(e,t);})();'

Replace

guidedlearning.oracle.com

with

https://guidedlearning-uat.oracle.com/

chrome.js

In the chrome.js file, there will be a line of code that reads as follows:

value = details.responseHeaders[i].value.replace(/;/g, "guidedlearning.oracle.com;");

Replace

guidedlearning.oracle.com

with

https://guidedlearning-uat.oracle.com/

Integrating Oracle Guided Learning with your Learning Management System (LMS)

If you are using Guided Learning for employee training and you have a Learning Management System you might want to integrate the two.

There are several ways in which you can integrate Guided Learning with your LMS of choice.

Linking to a Guided Learning guide from the LMS

You can use a permalink to create a link that will launch a Guided Learning guide as soon as you land on it. You can embed this link anywhere from an email campaign to your LMS.

Linking from a Guided Learning guide to your LMS

There are actually several ways to do this.

Each and every Guided Learning tooltip can embed reach media in it. This can be an image, a video, and depending on your LMS an actual course.

Furthermore, you could add a link to the course page in your LMS inside any Guided Learning tooltip. This means that as the user sees the tip he will be able to click on this link and a new browser tab with your LMS will open.

Both of these options are great ways to bring LMS content into context at the exact time of need.

Exporting training data from Guided Learning into your LMS

One of the key features of any LMS is its ability to track the progress of each and every employee in his/her onboarding process. Often you use the LMS to see which employees did not complete a certain training or course so that you could reach out to them.

Guided Learning keeps track of all your employees and how they interact with your guides. And if you stop to think of it a guide is in itself a micro training entity.

To that end, we allow our customers to export all usage information from the Guided Learning database so that you can upload it into an LMS.

For more information, please create a Service Request on My Oracle Support.

Javascript API

Introduction

The Guided Learning Javascript API (JS API) can be used to customize and personalize your end-users experience. The API makes it is possible to set end-user fields that can be used for setting complex activation rules for your guides. Additionally, you may use the API for personalizing and dynamically set the content of Guided Learning guides. The API also extends the support for single-page applications (SPA), ensuring that customers with SPAs can enjoy the full range of Guided Learning features that non SPAs can.

The API can also be used to attain granular control over the activation of Guided Learning guides within your web application. Using the API you can start or stop guides based on your custom business logic, as well as monitor the progress of a specific customer through your guides, by binding to guide-level or step-level events.

Using the API

The API commands are issued by a call to the Guided Learning method, which is defined on the global scope as part of the Guided Learning JS embed scriptlet. As such, API command can be issued from any JS code that is executed after the embed scriptlet is run. The best practice recommended by Guided Learning is to issue the API commands from a script tag embedded directly after the Guided Learning embed scriptlet.

NOTE: While API commands can be issued before the main Guided Learning JS script is loaded and run, they will only be executed when Guided Learning is fully loaded. The order in which commands were issued is preserved, making the loading and scheduling process transparent to the developer. The single exception to this rule is that the first call to api.fields.set in the queue will be executed before all other API commands when the Guided Learning script is loaded.

The Anatomy of Guided Learning Calls

Calls to the Guided Learning API are of the following generic form:

iridize("api.foo.bar", {callData:theData},function optionalCallback(data) {});

The first argument is a string indicating the command to be run. For example, "api.guide.start", is the name of the command for starting a guide.

A second argument is a plain object serving as a dictionary of data passed to the API command. For example, when starting a guide with an API name "foobar" using the API the second argument would be of the form {apiName:"foobar"}.

The third argument is a callback function that is run when asynchronous API calls are done or when an API event occurs. This argument is optional and is only executed for API methods that support it, as indicated in the specific method documentation. If data is to be passed to the callback function it is done in the form of a plain object, with the passed data as properties. The specific properties are specified in the documentation of the individual method.

NOTE: The second argument is optional for commands that do not require passing data, but it cannot be omitted if a callback function is supplied as the third argument. In such a case it is recommended to pass an empty plain object, {}, as the second argument.

Customization and Personalization Methods

End-User Field Methods

With Guided Learning, you can set complex activation rules for your guides, based on individual end-user fields. For example, you may wish to automatically start an introductory guide for every new user once. Or you may want to make a guide available for a user two days after she have viewed a different guide. In order to be able to use such rules, you need to set some fields for your end-users, using the API.

api.fields.set

Set fields for the current end-user. This method expects a dictionary of one or more fields as the second argument. For example, the Guided Learning embed code includes the following call (commented out) by default:

iridize("api.fields.set", {
    user_id:"USER_ID_GOES_HERE",
    joined_at:UNIXEPOCH_TIMESTAMP
});

where we set the reserved-name field "user_id", which can be any string uniquely identifying your end-users, such as a username, user ID, or an email address. Here the field joined_at is a date field, set as a numeric unix epoch timestamp (in seconds) giving the time the user signed-up to the application.

NOTE: You must set the user_id in the very first call to api.fields.set on a page. Subsequent calls may omit this field, but it is considered best practice to always include it.

Setting user group/role: you may want to use this method to customize the experience of users based on group participation or user roles. This information could then be used to set up activation rules, such that members of different groups will have different guides available. An example for such a call could be: 

iridize("api.fields.set", {
    user_id:"simpsons@springfield.us",
    joined_at:629848800,
    role:"admin"
});

Goal Tracking: setting up goal tracking is just a matter of setting a field with the field name prefix "goal_". This information can then be used to track conversions and set up A/B tests for your guides. For example, if we want to track when a user upgrades her plan from a trial account, we could call: 

iridize("api.fields.set", {
    user_id:"simpsons@springfield.us",
    joined_at:629848800,
    goal_upgraded_plan:"silver"
});

on the upgrade confirmation page, where the goal value string is in this cased used to track the type of plan the user converted to.

Field types

There are three basic javascript field types you can use, which are determined by the field value:

  • String
  • Integer
  • Boolean

For example, we could call:

iridize("api.fields.set", {
    user_id:"hpotter",
    joined_at:867618000,
    type:"mage",
    level:3,
    evil:false
});

Additionally, there are two types indicated by a prefix/suffix to the field name, goal fields (which are described above, under Goal Tracking), and time fields.

Time fields: to set a time field, simply name the field with an "_at" suffix. The time value should be provided using a unix epoch timestamp (in seconds). For example, to set the date a user joined the application, we could call: 

iridize("api.fields.set", {
    user_id:"simpsons@springfield.us",
    joined_at:629848800,
});

Personalization and Dynamic Content

api.vars.set

Dynamically set page variables which can be used in guides content.

For example, you may want to address your end-users in your guides using their names. In such a case the call to api.vars.set could be:

iridize("api.vars.set", {"new user":"F. Bar"});

The variable can then be used in any guide that will be running on the page by enclosing the variable name ("new user") within double curly brackets ({{new user}}). When the guide is run and the step is displayed, the part enclosed within curly brackets will be replaced with the value of the page variable if it is set. If it is not set, the variable name will be used instead (without the curly brackets). A default value different than the variable name can be set using the pipe, "|", symbol. For example, the text of a welcoming step could be set to:

Hi {{user_name|there friend}}, thanks for signing up to fooBar. Let us show you around.

With the variable was set as described above, the text of this step will read "Welcome F. Bar, thanks for signing up to fooBar, let us show you around.". If the variable was not set, the text will open with "Hi there friend,..."

Another use case for this API call is for including dynamically generated hyperlinks in your guides text. For example, you may have in your application paths such as "/foo/username/bar/". If you would like to add a hyperlink to such a path within a guide you could simply set the link target to "/foo/{{username}}/bar/", and run "api.vars.set" as follows:

iridize("api.vars.set", {"username":"007"});

This will yield a hyperlink with the target "/foo/007/bar/".

If the var is not set, but a user field with the same name was set in an api.fields.set call, the value from the user field will be used. If both a var and a field with the same name are set the value of the var will be used.

NOTE: The variable must be set when the guide step is run. However, you may use the below documented "api.guide.onStartStep" event for setting this value immediately prior to the execution of a specific step in a specific guide. This makes it possible to dynamically set the content of a guide step based on the actions of the user in previous steps of the guide.

Single Page Applications (SPA) support

The Guided Learning JS API allows customers with SPAs to easily treat route changes as if they were page url changes. This includes controlling and refreshing the contents of the Guided Learning start panel based on the current route, set guide steps to wait for route change (similar to waiting for page refresh), automatically activating a guide when a specific route is loaded etc.

NOTE: You should only run the Guided Learning embed code, including the call to api.fields.set, once, on the initial page load of the SPA. You should then update the route or refresh the guides on route or state changes. See the next sub-sections for further details.

The Guided Learning API provides both low-level and high-level method calls for setting up Guided Learning for your SPA. The high-level methods provide the simplest way to integrate Guided Learning, transparently differentiating between the first-page load of the SPA, and subsequent route changes. The low-level methods are available for SPAs that require more granular control or setting and updating routes, as well as refreshing the running guides.

Setup using high-level calls

The high-level setup of Guided Learning for a SPA is comprised of two parts. First, we need to tell the Guided Learning JS API to defer running the guides for after the initial SPA route is loaded. Then, we need to update the Guided Learning JS API whenever the SPA route is loaded, including the first SPA route load.

Waiting for the initial SPA route load

When using the high-level JS API calls to integrate Guided Learning into a SPA you should add a call to api.route.wait to or immediately after the Guided Learning embed code, such-

iridize("api.route.wait", {});

This call notifies the iridize JS API that it should defer loading the iridize guides for after the first SPA route is loaded and a call to api.route.update is made (see below).

Handling SPA route changes

Whenever a SPA route is loaded (including the initial SPA route load), you should make a call to api.route.update, passing the new route that is loaded as part of the parameter object, such-

iridize("api.route.update", {"route":"/foo/"});

Where "/foo/" is the SPA route that is loaded. That's it. The api.route.update call knows to handle the initial route load differently than route changes transparently and will issue a call to api.guide.refresh (see below) only when the SPA route is actually changed..

Setting user fields when integrating iridize into a SPA

The details of using the api.fields.set calls are provided in the "Customization and Personalization Methods" section above. Please note that if you are not using the api.fields.set call in your iridize implementation you can skip this section. When integrating iridize with a SPA there are two general cases that need to be considered. The simplest case is when the user details are available when the iridize embed code is run. The slightly more involved case is when the user details (such as user_id, joined_at date, account_id etc.) are unavailable when the iridize embed code is run.

User details available when the iridize embed code is run

If the user details are available when the iridize embed code is run, the usage of api.fields.set is identical to that of non-SPA setup, regardless of whether the embed code is embedded directly into the page's HTML or is only run when the SPA is loaded. In this case, the call to api.fields.set should be made as part of or immediately after the iridize embed code, within the same synchronous code flow. An important detail to note is that api.fields.set should only be called once and you should not issue a call for every time the SPA route is changed.

User details only available after the SPA is loaded

It is usual for SPAs that the user details are not available when the iridize embed code is run. This usually is the case when the iridize embed code is embedded as part of the page HTML, but the user details are only fetched at a later time, as the SPA loads. In such a case you should add a call to api.fields.set with an empty fields object as the second parameter as part of or immediately after the iridize embed code (within the same synchronous code flow), such-

iridize("api.fields.set", {});

Then, once the user details are available you should run the api.fields.set call with the user details as usual. With this setup the iridize JS API will know to wait with the guides initiation for after the user details are provided with the second call to api.fields.set. Please note you should only call api.fields.set with the user details once, and not repeat it every time the SPA route is changed. Setup using low-level calls

Initial Page Load - api.route.set

When integrating iridize to a SPA, you should add a call to "api.route.set" to the initial iridize embed code. The call expects a single property, "route", in the second argument. For example, if the initial route for your application is "/foo/" the call will be:

iridize("api.route.set", {"route":"/foo/"});

NOTE: if you use hash-based navigation in your SPA you may include the hash sign in the route or not as you prefer. Leading and trailing "/" are also optional.

DEPRECATED: This API call is no longer needed when embedding in a SPA.

Force a page refresh - api.guide.refresh

Unlike regular web applications, SPA's do not have page loads as natural points for refreshing the state of your guides. With the use of the "api.guide.refresh" API call you can refresh the state on demand, optionally updating the current route.

For example, if the route was changed to "/foo/bar/" the call would be:

iridize("api.guide.refresh", {"route":"/foo/bar/"});

NOTE: This is a low-level API call, in most situations you should use "api.route.update".

The Guide API Methods

API methods that have to do with guides are all namespaced as "api.guide.methodName".

Control Methods:

api.guide.list

Get the list of all available guides for the current domain.

For example, to fetch the guides list and print it to the browser console, you could do:

iridize("api.guide.list",  {}, function(data)  {
    var guidesList,guide,i;
    // get the array of guide information objects
    guidesList = data.guides;
    // print the guides to browser console
    for (i = 0; i < guidesList.length; i++)  {
        guide = guidesList[i];
        console.log(guide.apiName + " | " + guide.displayName);
    }
});

api.guide.start

Starts a specific guide. The method expects the API name of the guide as the "apiName" property of the second argument. For example, to start a guide with an apiName "foobar" the call would be:

iridize("api.guide.start",  {apiName : "foobar"});

or, you can also provide the step id to start from:

iridize("api.guide.start",  {apiName : "foobar", step:"5"});

This method also accepts an additional optional "force" property to the second argument. If this property is set to false, the API method will not force start the guide, as is its default behavior.

NOTE: The apiName of guides can be found and modified under that advanced tab of the Guide options page in the iridize dashboard.

NOTE: The force:false option must be set in order for end-user activation rules to apply for guides started using the API.

api.guide.stop

Stops a specific guide if an apiName is supplied, or all currently running guides if not .

To stop a specific guide if it is running, pass the api name of the guide as the apiName property of the second argument. For example, to stop a guide with an apiName "foobar" the call would be:

iridize("api.guide.stop",  {apiName : "foobar"});

To stop all currently running guides, simply don’t pass an apiName property, so the call would be:

iridize("api.guide.stop", {});

NOTE: The apiName of guides can be found and modified under that advanced tab of the Guide options page in the iridize dashboard.

api.guide.disable

Stops all running guides and disables the execution of any guides. 

iridize("api.guide.disable",  {});

NOTE: You can still run a guide using the api.guide.start API call.

api.guide.enable

Enables Iridize and relaunches all guides as if the page was loaded again. Call this function following a call to api.guide.disable. 

iridize("api.guide.enable",  {});

Events:

api.onReady

This event is fired after Iridize has been fully loaded.

iridize("api.onReady",  {}, function(data)  {    
    console.log("iridize is ready");
});

api.guide.onStartGuide

The startGuide event is triggered every time a guide is started. The callback is passed two properties - the apiName of the guide for which the event was triggered and a parameter indicating the type of guide activation. The main types of activation values of the runType variable are “autoload”,”startPanel” and ”apiStart”.

For example, the following call would log every guide started to the browser console:

iridize("api.guide.onStartGuide",  {}, function(data)  {
    var apiName = data.apiName;
    var runType = data.runType;
    // print the guide’s api name and the activation type
    console.log(apiName + " | "+ runType);
});

api.guide.onStartStep

The startStep event is triggered every time the end-user progresses along with any guide. The callback is passed two properties - the apiName of the guide for which the event was triggered and the id of the step which the user has reached (this id is usually the step number in the guide).

For example, the following call would log every step started to the browser console:

iridize("api.guide.onStartStep",  {}, function(data)  {
    var apiName = data.apiName;
    var step = data.step;
    // print the guide’s api name and the id of the step reached
     console.log(apiName + " | "+ step);
});

api.guide.onStopGuide

The stopGuide event is triggered every time a guide is stopped, either by the user reaching the guide’s end or due to the user clicking the close button (x) on the tip. The callback is passed the apiName of the guide which was stopped.

NOTE: data.userClosed will be true if the user has manually closed the guide. If 'remind me later' was clicked it will be false.

For example, the following call would log every guide when it is stopped:

iridize("api.guide.onStopGuide",  {}, function(data)  {
        var apiName = data.apiName;
    // print the api name of the guide that was stopped

      console.log(apiName);
    });

api.guide.onErrorStep

The errorStep event is triggered every time iridize is unable to display a tooltip (e.g. if the element that the tooltip should point at is not found). The callback is passed as a data object which contains information about the step and the guide that had the error.

For example, the following call would log the guide and the step in error:

iridize("api.guide.onErrorStep", {}, function(data) {
    // print the guide’s api name and the id of the step.
    console.log(data.apiName + " error on step "+ data.stepId);
});

api.guide.onItemsFiltered

The onItemsFiltered event is triggered every time the user interacts with the search inside the Iridize help widget. You can use it to incorporate the list of Iridize guides into another container in your application.

iridize("api.guide.onItemsFiltered", {}, function(data) {
    //your code goes here
});

Your callback function will be called with the following data object

query: the text that the user searched for

step_id: the id of the step in the guide that caused the event

page_items: the list of content items that match the current page as well as the search criteria

filtered_items: the list of content items that match the search criteria. content not for the current page will also be available here.

entire_items: the list of all items available in the help widget, ignoring the search term.

Working with OGL in the Chrome DevTools Console

Oracle Guided Learning Setup Instructions

Setup for Fusion Applications

Setup for Non-Fusion Applications

Compatibility

Guided Learning on-page guidance solution is compatible with any application that can be used with a standard web browser.

Guided Learning technology can offer instructions on any element in the DOM tree.

Guided Learning can be used to provide instructions on embedded objects such as java applets, Flash, and Silverlight. However, Guided Learning cannot inspect elements within these embedded objects.

Setup Oracle Guided Learning in a Single Page Application (SPA)

Before we dive into the steps required to embed Oracle Guided Learning in a SPA, let's explain why a specific setup for the SPA's is needed in the first place.

The thing that's different in a SPA is the fact that even though the browser does not perform any standard navigation the view is still changing. As a result, the application codebase needs to update Oracle Guided Learning that the view has changed so that Oracle Guided Learning could refresh all of the content.

1. Basic embed code

To set up Oracle Guided Learning just as in any other web application by placing the Oracle Guided Learning embed code in the relevant pages. Your specific embed code can be found on your account setup page and should simply be copied before the closing </body> tag.

The code will look something like this:

/* Iridize.com*/window.iridize=window.iridize||function(e,t,n){return iridize.api.call(e,t,n);};iridize.api=iridize.api||{q:[],call:function(e,t,n){iridize.api.q.push({method:e,data:t,callback:n});}};
iridize.appId="XXXXXXXXXXXXXXXXXXX";
iridize.env="prod";
iridize("api.fields.set",{user_id:"USER_ID_GOES_HERE"});
(function(){var e=document.createElement("script");var t=document.getElementsByTagName("script")[0];e.src=("https:"==document.location.protocol?"https:":"http:")+"//d2p93rcsj9dwm5.cloudfront.net/player/latest/static/js/iridizeLoader.min.js";e.type="text/javascript";e.async=true;t.parentNode.insertBefore(e,t)})();

2. Notify Oracle Guided Learning that this is an SPA

iridize("api.route.wait", {});

This call notifies the Oracle Guided Learning JS API that it should defer loading the Oracle Guided Learning guides for after the first SPA route is loaded.

3. User Identification (part 1)

Oracle Guided Learning needs to know which user is currently logged in so that it could provide that user with relevant content.

If you do not know who the logged in user when the code of the basic embed code (step #1) is executed. You can notify Oracle Guided Learning that you will be providing this information later.

To do so, you should call the 'api.fields.set' function with an empty object.

iridize("api.fields.set",{})

NOTE: User conditions will be disabled if you do not make this notification.

Your embed code should now look like this:

/* Iridize.com*/window.iridize=window.iridize||function(e,t,n){return iridize.api.call(e,t,n);};iridize.api=iridize.api||{q:[],call:function(e,t,n){iridize.api.q.push({method:e,data:t,callback:n});}};
iridize.appId="XXXXXXXXXXXXXXXXXXX";
iridize.env="prod";
iridize("api.route.wait", {});
iridize("api.fields.set",{})

--- OR ---

iridize("api.fields.set",{user_id:"USER_ID_GOES_HERE"});
(function(){var e=document.createElement("script");var t=document.getElementsByTagName("script")[0];e.src=("https:"==document.location.protocol?"https:":"http:")+"//d2p93rcsj9dwm5.cloudfront.net/player/latest/static/js/iridizeLoader.min.js";e.type="text/javascript";e.async=true;t.parentNode.insertBefore(e,t)})();

4. User Identification (part 2)

If you have already provided user identification in the basic embed code you can skip this step.

If you used Oracle Guided Learning("api.fields.set",{}) in the previous step, you will need to update Oracle Guided Learning of the logged in users as soon as possible. To do so call:

iridize("api.fields.set",{user_id:"USER_ID_GOES_HERE"});

NOTE: You can provide Oracle Guided Learning other user data (e.g. user_role, location, etc.) by adding more items to the passed javascript dictionary.

5. Update route

Whenever an SPA route is loaded (including the initial SPA route load) you need to notify Oracle Guided Learning of it by calling:

iridize("api.route.update", {"route":"/foo/"});

Where "/foo/" is the SPA route that is loaded. The api.route.update call knows to handle the initial route load differently than route changes transparently. It will also automatically refresh the content based on the new route.

The call to "api.route.update" must be made after the route has successfully changed and not before. This way Oracle Guided Learning will be able to update the content according to the newly loaded route.

When using the AngularJS's $route for view routing you can bind on the $routeChangeSuccess event. When using ui-router you can bind on the analogous $stateChangeSuccess event. Both events provide the new route/state which can be passed to the api.route.update call.

BEST PRACTICE: It is recommended to omit random ID's from the route. For example, if you run a CRM and each contact has a unique (e.g. https://myapp.com/dashboard#contact/169627 ) where 169627 is the ID of the contact in your database. Instead of setting the route to '/contact/169627' it is recommended to make the route more generic. For example: 

iridize("api.route.update", {"route":"/contact/view"});

IMPORTANT: The people who will be writing the content using the Oracle Guided Learning platform need to know what scheme was used to map the urls to routes in Oracle Guided Learning. This is needed when creating guide activation conditions.

Step and Video Guide Enabling/Disabling

Step Guides are an in-app presentation of the guide's pdf, showing the user the entire process in question without having to leave the application. Users can access Step Guides by selecting the Steps steps icon icon next to the guide name. This also provides access to the Video Guide.

Step Guides are ENABLED (The Steps steps iconicon is displayed) Step Guides are DISABLED (The Steps steps iconicon is not displayed)
display when steps are enabled display when steps are not enabled

IMPORTANT: Enabling/Disabling Step and Video guides is set at the account/appID level, not on a per-guide basis.

  1. Select the Content tab in the OGL Console, then select Help Widget Settings
    selecting content tab then help widget settings

  2. Locate the Advanced Settings section
    advanced settings menu

  3. Check or uncheck the 'Step Guide (Show or hide the step guide icon in the help widget)' checkbox (Note: Checked = Enabled; Unchecked = Disabled)
  4. Check or uncheck the 'Show video presentations (video preview of a guide)' checkbox (Note: Checked = Enabled; Unchecked = Disabled)

    IMPORTANT: The 'Show video presentations (video preview of a guide)' setting is automatically unchecked when the 'Step Guide (Show or hide the step guide icon in the help widget)' setting is unchecked.

  5. Select the Save to Dev button to validate in your DEV environment and, when ready, select the Publish to Prod to save the changes to your production environment
    publish to prod and save to dev buttons

What is the difference between Viewer, Editor, and Owner?

Oracle Guided Learning allows you to collaborate when creating content.

To that end we support three user roles: viewer, editor, owner.

Below is a list of permission for each role. note that an editor has all the permission of a viewer and an owner has all the permission of an editor.

Viewer

  1. view user analytics
  2. view guide analytics
  3. preview a guide

Editor

All Viewer permissions and

  1. create/edit/delete guide
  2. publish guide

Owner

All Editor permissions and:

  1. change help widget
  2. change theme
  3. change application settings (e.g. enable guide feedback)
  4. reset user data
  5. add/edit/remove users from account

How to Install, Extract, and Package the OGL Editor Extension from the Chrome Web Store

This article covers the following procedures:

  • Installing the OGL editor extension for Google Chrome.
  • Extracting the OGL Editor Extension.
  • Packing the extension CRX files.

Installing the OGL editor extension for Google Chrome

Prerequisites

  • Google Chrome browser.

Instructions

  1. Go to the Chrome Web Store. The page below opens; select Add to Chrome.
    chrome web store

    A confirmation dialog box opens.

  2. Select Add extension.

    add extension dialog

  3. A confirmation message is displayed once the setup is completed.confirmation message

Extracting the OGL Editor Extension

Prerequisites

  • Google Chrome browser.
  • Oracle Guided Learning (Iridize) extension added to Chrome.

Instructions

  1. Open the Google Chrome browser.
  2. At the top right, select the Extensions icon(jigsaw icon)and then select Manage extensions.manage extensions

    The Manage extensions window appears with the list of extensions installed on the Chrome browser.

  3. On the Oracle Guided Learning Editor extension card, select Details.extensions list

    The details of the OGL Editor extension are displayed now.

  4. Look at the URL. The Extension ID is the long string of characters at the end of the URL.extension id
  5. Identify the Extension ID and copy it.
  6. On your PC's local drive, navigate to the extensions folder, where all the extensions are stored.

    Your default directory may look like this:

    C:\Users\<Your_User_Name>\AppData\Local\Google\Chrome\User Data\Default\Extensions

    directory

    Note:

    You might have to enable visibility for hidden files.
  7. Find the folder matching the OGL Editor's Extension ID. Then copy and paste it to a new directory (i.e., C:\Users\<Your_User_Name>\Documents\OGL Editor extension\).new directory

You have now successfully extracted the OGL Editor extension files. To create a .crx file, please see the next section.

Packaging The Extension CRX Files

Prerequisites

  • Google Chrome browser.
  • An extracted OGL Editor extension.

Instructions

  1. Open the Google Chrome browser.
  2. At the top right, select the Extensions icon(jigsaw icon)and then select Manage extensions
  3. Use the toggle button on the Manage extensions window to enable the Developer mode.

    dev mode
  4. Select Pack extension.

    pack extension

    The Pack extension modal window is displayed.

  5. Browse the Extension root directory and select the folder in which the OGL Editor extension is present.

    Your root directory should be similar to C:\Users\<Your_User_Name>\Documents\OGL Editor extension\gjlnedceigegbbmdnjgeebldeljgmhch\5.13.0_0

    select folder
  6. Select Pack extension.

    pack extension confirmation

    A confirmation message is displayed. Select OK to close the confirmation window.

    confirmation window
  7. On your PC's local drive, navigate to the extension directory to verify.verify the directory

The .crx file has now been successfully created.