9 Tips & Tricks

This chapter contains OGL tips and tricks.

Multiple Widget Display Prevention

On a page containing an iFrame, the iFrame must have its own JS embedded. As such, it will usually display a launch widget, meaning the screen will display two launch widgets. To avoid this, place the following line of code in the embedded JS where you DON’T want the launch widget to appear:

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

Reference below snippet of the JS embedded into the iFrame application:

Advance on Click Fails

Sometimes when you set advance on click on an element, Oracle Guided Learning will not advance to the following step as expected.

When this happens, normally, the application handles the click and blocks any other code from handling the event.

To work around this issue it is recommended to try using Advance when 'user presses mouse button'. The click event occurs when after the user presses and then releases the mouse button. The press event occurs before the click event, as soon as the user presses the mouse button.

As a result, using the press event you can catch the user's interaction before the click event is fired and handled by the application.

Autoload a Closed Guide

Guided Learning marks a guide as closed if the user manually closed it; normally by clicking on the 'x' at the top right corner of the tip.

To create a pleasant user experience Guided Learning will not autoload a guide that was manually closed by the user. To that end Guided Learning remembers the time that the user closed the guide.

By default, Guided Learning will not allow this guide to autoload before 1 hour has passed.

You can configure this timeout by using the following setting in your embed code:

iridize.stateTimeout = 3600; // in seconds.

Can a guide be launched automatically from an email campaign or a knowledge-base article?

Yes, regardless of the use case, you can always create a link that, when opened, automatically launches a guide.

Common use cases

• An e-mail campaign to your customers announcing a new feature. If clicked, you want the reader to be engaged with a Guided Learning tour of the new feature.
• Linking a knowledge-base article to the relevant guide. If the article is providing an overview of a certain procedure, the user can jump directly into doing that procedure with the guide activated.
• Integrating Guided Learning guides with your LMS

Prerequisites

• Guided Learning must be embedded in your application
• Sufficient knowledge of HTML or at least of creating an HTML link.
• Sufficient permissions to add the HTML link to the email campaign, knowledge-base, or LMS

Creating a Permalink

A permalink is composed of 2 parts:

• The link to the desired destination page. For example, if you application is hosted on http://myapp.com, the link to the user profile page could be http://myapp.com/profile.
• A parameter that signals Guided Learning to launch the guide. This is why we need Guided Learning to be embedded.

  stStart=[api name]

For example, to launch a Guided Learning guide with the API name abcdefg that gives an overview of the profile page:

1. Take the base page link http://myapp.com/profile
2. Suffix "?" to indicate a URL parameter to follow
3. AppendstStart=abcdefg
4. End result is http://myapp.com/profile?stStart=abcdefg

IMPORTANT: Permalinks do not work with Oracle Fusion Applications.

Can a guide work across multiple domains?

Well, actually no, but your users will think it does.

Let's explain, Guided Learning guides are running inside the browser. A key security policy that is always enforced by the browser is that no domain can access data from another domain; and hence the no. But what Guided Learning allows you to do is to create 2 guides, one for each domain, and link them with Guide Activation Conditions. Using this technique you can create, what would look to the end use, as a cross domain guide.

Prerequisites

1. Guided Learning is embedded in both domains via javascript or a browser extension
2. The same Guided Learning appId is used in both domains

Let's Do It

1. Split the guide into 2 guides one for each domain. If you already have a guide with all steps, no problem, clone it and delete the relevant steps from each one.
2. Add the following conditions to the second half of the guide:

To make the explanation easier, in the example above, the first half of the guide is called First Domain and the second is called Second Domain

Notice there are two guides referenced in these conditions. The first 2 conditions reference the guide on the first domain and the last condition is referencing the guide on the second domain.

Let's explain the conditions one by one.

1. Autoload this guide second domain if the user has seen the guide first domain less than 60 seconds ago (within the last minute).
2. Autoload this guide if the user has closed the guide more than a minute ago. Or in other words if the user has not just recently closed the first domain.
3. Autoload this guide if the user has closed the second domain guide more than 5 seconds ago or never. This condition is optional if you want the second domain guide to always launch no matter if it was recently closed or not.

Can I change the element selection algorithm?

Yes.

If needed you can hard-code the selection algorithm. By doing so you can force Guided Learning to identify the element based on your criteria.

To do so you will need to add the data-walkthrough attribute to the relevant HTML element and give it a meaningful value.

For example, if this is your HTML element:

<span data-walkthrough="foo">bar</span>

When you select it in the editor the selector will be:

[data-walkthrough="foo"]

Can I start a guide on a particular step using the public API?

Yes.

You will need to know the apiName of the guide and the id of the step.

To launch guide i76g0pfx from step id 2, you would call:

iridize('api.guide.start', {apiName:'i76g0pfx', step: '2'})

Can I use Guided Learning even if a user is not logged in?

Yes.

While you can embed Guided Learning on any web page, this issue is normally raised by our customers when they want to take advantage of the user activation conditions even before a user login. For example, to show an overview video to a user only once.

When you embed Guided Learning you can read/write a random user_id from a cookie or local storage.

To do so, please replace the following line in the embed code:

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

with ths:

    var randomUserId;
    var userId = ""; /* Replace the empty string "" with logged-in customer id as a string if customer is logged-in*/
    if (userId === "") { /* If no userId is supplied, we manage a randomlly generated user id, which is persisted in localStorage if it is available*/
        randomUserId = "Anon" + ((Math.random() + 1) * Math.E / Math.PI).toString(36).slice(2)
        try {
            userId = localStorage.irruid || randomUserId;
            localStorage.irruid = userId;
        } catch (e) {
            userId = document.cookie.replace(/(?:(?:^|.*;\s*)irruid\s*\=\s*([^;]*).*$)|^.*$/, "$1") || randomUserId;
            document.cookie = "irruid=" + userId+"; expires=Fri, 31 Dec 9999 23:59:59 GMT";
        }
    }
    /* Now set the user_id field */
    iridize("api.fields.set", {
        user_id: userId
    });

Can 'show tip on hover' and 'disable element' be used together?

Yes.

But it's not that easy.

The way Guided Learning disables an element is by placing a "transparent" layer on top of it. If for example we disable a button when the end users click on the button they are in fact clicking on that transparent layer and the button never "sees" the click and is hence unusable.

When you set a tip to show on hover, Guided Learning waits for the end-user to put their mouse over the relevant element and show the tip then; but if the element is also disabled, the mouse will never be over the element but only on that "transparent" layer mentioned above.

The solution is to have the tip show when the mouse goes over the layer instead of the element itself.

1. Create the disable layer as you normally would
2. Make it invisible and set it to advance on click

   

3. On the same step, create another sub-step that will 'show on hover'.
4. Set the target element for this tip to .stDisableDiv

   

Conceptually, what is the best way to design a tour guide?

Each guide should have its own purpose. Normally a guide can either instruct a user to perform a specific task or show the user around a specific page or application. Doing both in the same guide may be confusing for your users.

Customization and Personalization 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 user 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 call could be:

iridize("api.fields.set", {
    user_id:"[e-mail]",
    joined_at:629848800,
    role:"admin"
});

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:"[e-mail]",
    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.

Display Groups not Correct in Prod

If you are seeing your Display Group settings properly in Dev but in Prod they do not look the same.

Instructions

When making changes to a published guide in the Display Group Manager that you want to see reflected in the Help Panel you must follow these steps:

1. Be sure to hit the “Save” button in the DG Manager
2. Publish the guides you updated (they will show “Unpublished Version” after a browser refresh)
3. Wait 5 minutes to see the updates in env=prod environment (prod uses caching to improve performance but updates take up to 5 minutes to populate)

Does Guided Learning provide functionality for selecting elements within an iFrame?

Yes.

But, as a javascript library Guided Learning must also adhere to the same origin policy enforced by the browser.

This means that if the iframe is loaded from a different domain than you will not be able to select elements inside it from the outside frame. An exception to that is if both the top frame and the iframe share the same root domain; If so, you can use the document.domain attribute to allow Guided Learning to selects element inside the iframe even if it is loaded from a different sub domain.

Editing Step Branches

One of the strong points of the Guided Learning solution is how simple it is to create and manage guides for the most complex processes. At the heart of this lies the Step Branches editing page the Guide Editor. The Step Branches editing page empowers you to control the flow of the guide based on various page conditions, setting multiple branches all from the a single place.

How Branches Work

You can set one or more branches for each step in the guide. For each branch you can optionally set one or more page conditions to limit when that branch could be chosen. When the guide advances from a step which has branches, the first branch that can be chosen (considering each branch's conditions) is selected and the guide continues along that branch. Thus, the order in which branches are set in the Edit Branches page is important. Additionally, adding a branch after a branch without conditions will have no effect (see Keep Current Guide Open below for an important exception). If no branch is chosen, the guide will continue to the default next step, just as if no branches were set.

NOTE: If you have multiple Tips in parallel within a Step, the branches are set for each Tip separately.

The Edit Branches Page

The Edit Branches page lists the branches for the current step, you can add and archive branches as well as edit branch settings. To open the page click the "Step Branches: Add" setting in the Advanced Settings Panel of the current step in the Guide Editor.

A step with two branches. The first branch is a Jump to Step branch with conditions and the second is a Launch Guide branch.

1. Done/Cancel

Click Done to save the step branches or click Cancel to discard your changes.

2. Action Buttons

The action buttons (Activate/Deactivate/Delete) allow you to perform an action on all selected branches. You can select all branches by checking “Select all branches” box (labeled 3 in the image above) or by manually selecting each branch using the selection checkbox at its top right corner.

• Activate: Click to activate all selected branches. Only active branches are evaluated.
• Deactivate: Click to deactivate all selected branches. Inactive branchesare not evaluated and will not affect the flow of the guide.
• Archive: Delete all selected branches. This action cannot be reversed once Done is clicked.

3. Check to select all Branches

Check this box to select all the branches in the Edit Branches page. Helpful if you would like to perform a mass action.

4. Branch Editing Area

See below for more details on editing branches . The image above displays 2 branches.

5. Edit Branch

Click to edit the branch.

6. Show/Hide Advanced Settings

Click to toggle whether advanced branch settings are visible. This option is visible for Launch a Guide type branches only.

7. Reorder Branches

Drag the up & down arrow to drag and drop a branch and change the order of branches.

8. Add Branch

Click to add a new branch.

Jump to Step Branch Type

Jump to another step within the same guide.

Editing a Jump To Step branch. This branch is set to Jump to Step with step API Id "3" when the set Conditions are fulfilled.

1. Select Branch Type

Branch type select box.

2. Step API id

The API id of the step to jump to. The step API id may be found in the Step Settings Panel of the Guide Editor.

3. Add/Edit Conditions

Click to open the conditions editor, where you can add/edit Conditions to the branch.

4. Done/Cancel

Click on Done to finish editing the branch and keep your changes. Click on Cancel to discard the changes made to the branch.

Launch a Guide Branch Type

Choose the Launch a Guide branch type to launch another guide from within the current guide. When used without branch conditions, this is often used to string together several guides into a unified guide. When branch conditions are used this is often used for forking a guide based on user choices or application state.

Editing a Launch a Guide branch with advanced settings. This branch is set to Launch a Guide with apiName "98j68vyj".

1. Select Branch Type

Branch type select box.

2. Guide apiName

The apiName of the guide to launch. The apiName of a guide can be found in the guide's listing on the Guides page of the Guided Learning dashboard.

3. Step API Id

By default the launched guide is started from its first step. When this textbox is not empty, the launched guide will start from the step with the API id in the textbox. The step API id may be found in the Step Settings Panel of the Guide Editor.

4. Keep Current Guide Open

The Launch a Guide type of branch normally launches the guide and then closes the current guide. When the Keep Current Guide Open checkbox is checked the current guide is kept open. Additionally, the branch choosing process continues on to the following branches (if any) and to the default next step if no other branch is chosen. This is often useful when launching a guide which is run in a popup window (see Popup Window Name setting below), where the current guide stays open waiting for the user to get back from following the launched guide on the popup window.

5. Add/Edit Conditions

Click to open the conditions editor, where you can add/edit Conditions to the branch.

6. Show/Hide Advanced Settings

Click to toggle whether advanced branch settings (items 7-11 below) are visible.

7. Wait for Page to Load

When this checkbox is checked the launched guide will not start until a page load takes place (either a full page load or a SPA route load on a properly integrated SPA). This is almost always necessary when launching a guide in a popup window (see Popup Window Name setting below). Another use for this setting is when combined with the Redirect to Page or Reload Page settings.

8. Redirect to Page

When the textbox is not empty, the user will be redirected to the URL specified in the textbox when launching the guide. Please note that it is almost always a good idea to also set the Wait for Page to Load setting when using Redirect to Page.

9. Reload Page

When this checkbox is checked, the page will be reloaded when launching the guide. Please note that it is almost always a good idea to also set the Wait for Page to Load setting when using Redirect to Page.

10. Popup Window Name

By default the launched guide starts in the current browser tab/window. When this textbox is not empty the guide will be launched in a tab/window with the Javascript window.name property matching the text in the textbox. This is useful for launching guides within a popup window or another tab. For use with a popup window, this setting almost always requires also setting the Wait for Page to Load setting to work properly.

If you don't know the name of the popup window, refer to this video

11. On Close Return-Here/Launch-a-Guide

This setting sets an action to take place when the launched guide is closed (either by the user or by finishing the guide).

• Return Here - with this setting the launcher guide is suspended upon launching the guide. When the launched guide is closed the launcher guide resumes from the same step it was when suspended.
• Launch a Guide - with this setting the launcher guide is closed as usual. When the launched guide is closed, the guide with the apiName set in the textbox is launched.

12. Done/Cancel

Click on Done to finish editing the branch and keep your changes. Click on Cancel to discard the changes made to the branch.

Embedding an iFrame in a Guided Learning Step

One of the cool ways of using Guided Learning is embedding external content into an Guided Learning “bubble.”

You can use this feature to, for example:

• Provide your users with a survey that you’ve created (in SurveyMonkey or in Google Sheets for example) directly over the interface of your product.
• Give you users direct access to relevant information in your FAQ or Knowledgebase while they are using the product
• Sharing information from an external source or website in a contextually relevant

This features utilizes Guided Learning’s ability to embed iframes (or Inline Frame) in our bubbles. These iframe-bubbles can appear as single-step guides or as part of a longer guide (one of the steps), based on your requirements and the process.

And, of course, these guides and bubbles can be made to appear according to pre-set conditions (Only once, only on certain pages, only to certain people, etc.), just as any other guide. In addition, Guided Learning collects all usage data and lets you know that your users have actually seen this content (even though it is outside of your product).

Embedding an iFrame

The mechanism of embedding an iframe into a bubble is similar to embedding a video or an audio link and uses the same process. Guided Learning has a generic algorithm that recognizes the type of content that is provided in the URL and automatically deploys it correctly in the bubble.

Just as with video and audio, there are two ways you can embed iframes into Guided Learning bubbles. In both cases the process is easy and quick.

From the Editor

• Launch the Guided Learning Editor
• In the Expanded Content Editor choose the Embed Media Console Box (see Image)

• In the console box enter the URL for your iframe and click “ok”

• The external website will now appear in your Guided Learning bubble

• You can minimize the Expanded Editor and either continue to the next Step or click “Done” and continue to the Guide Activation Conditions

From the Dashboard

• Click the New button for creating a guide and choose “Video” from the options in the green bar (1).
• In the URL box (2) enter the URL of the page you wish to embed
• Don’t forget to give the new guide a name (3)

• Now click Create
• A new guide has been added to your Video Guide list
• You can now choose the URL you wish this guide to appear on

Please note! Some products do not allow you to embed them inside of an iframe. We suggest you test each page to see that it works before launching it to your users.

Find the "Route" of a Fusion Apps Page

Describe when someone would need this information. For example "when connecting to wi-fi for the first time".

Instructions

1. In a Chrome browser, right click anywhere on the page and select "Inspect"
2. In the Console tab of Dev Tools, enter

   iridize.master.getRoute();

3. The route for that page will be displayed

   

   

   

Guide Appears in Help Widget after Updates

This is most commonly an issue when creating a Smart Tip guide designed to auto launch, but you not intended to show up in the Help Widget. If Activation Settings are done correctly, the guide will not appear in the Help Widget. However, if the guide is updated, the Activation Settings will automatically update to display the guide in the Help Widget. To avoid this issue with existing guides or new guides, follow the steps below.

New Guides

1. After you initially create the guide and select the "Done" button, you are brought to the Activation Settings window. Here you will see something similar to the following settings:

   

2. Assuming you want the smart tip to autoload and NOT show in the Help Widget, adjust the settings as shown below (change the "When page has URL matching..." condition to "Inactive" and the "Your guide will be shown..." Condition to autoload):

   

3. If you go in and make edits to this guide (add a new Smart Tip, for example, or edit the text in the existing Smart Tip), the Guide Activation Settings will not change.

Existing Guides

1. Go to guide that was previously created and examine the Activation Conditions.

   • There should be at least a segmentation condition with "URL matching" and help me checked. The segmentation condition will usually have a fairly long string defining the routes. If it is a small guide, there the URL matching condition may be relatively short.

     

2. Set the segmentation condition to autoload
3. Open the guide, edit it ((add a new Smart Tip, for example, or edit the text in the existing Smart Tip), and select Done
4. Review Activation Conditions
   • You should now see an additional help widget activation condition, like this:

     

5. Set this additional help widget activation condition to inactive
6. Save settings
7. The next time you edit the guide, there should be no changes to the Activation Settings

Guide Does not Scroll

Does your application use internal scrolling? That is, when you scroll the page does the top remain fixed? If so, the answer is yes. As a result you need to tell Guided Learning to use this scroll as opposed to the 'standard' vertical scrollbar of the browser. To do that you need to check the 'scroll parent container' option under the advanced settings.

Within the editor you will see a warning triangle when it is recommended for you to set the step to scroll. You can simply click on set it to scroll text in the warning or tick the scroll parent container box in Advanced settings

Guide Mysteriously Skipping a Step

If the guide you are working on is skipping a step, always check the DevTools Console tab first to see if you can troubleshoot the issue there.

The highlighted line is the one that represents the step being skipped. Based on this log file, it looks like the step was advanced normally, but it is not appearing when the guide is run. If this is what you are seeing in the Console, try the following.

Instructions

1. In the step that is skipping, go to the "Activation Settings/Show tip after line" value
2. Enter 5 seconds
3. Retest
4. If the guide now works properly, experiment with reducing the number of seconds to get a value that is as small as possible while ensuring that the step displays properly

This has been seen when the previous step is a drop down value being chosen. What is happening is that the click on the drop down is "echoing" and getting registered in the following step. The delay allows the click to complete before the next step appears, thereby avoiding the skip.

Guide not Starting on First Step

Problem Description: Guide doesn't start on first step

Steps to reproduce: Start the guide from the Help widget. This is an important detail - if you start the guide from the DevTools console, it will work properly. So, for example, when you choose a guide from the HelpMe widget, instead of starting on the first step, the guide starts on 8th step

Resolution

iridize.adfApp = true;

Add the above to the config.js file in the extension.

Sample:

+++++++++++++

var ir_app_settings = {

"H2KN4GjLSO+zPiyRhWDgKw": [

'iridize.env="dev";',

'iridize.min=""; //this line is only for testing. remove this line in production.',

'iridize.useSessionStorage=true;',

'iridize.contextualMode=false;',

'iridize.autoSegmentation = true;',

'iridize.adfApp = true;'

]

};

var ir_url_mapping =

{ 'https://ucf5-zaxe-fa-ext.oracledemos.com': "H2KN4GjLSO+zPiyRhWDgKw" }

;

++++++++++++++

Guided Learning Does not Respect URL Condition

Detailed Question:

When testing for a Splash message it seems that Guided Learning does not respect the activation URL. When testing in dev environment the message pops up as soon as a person logs in to the dashboard.

Answer:

Try to log in using a new incognito window/tab.

Maybe you already had this guide running in this browser tab. Because Guided Learning stores the state of all guides per tab, if the guide already ran in this tab, even if with a different user, Guided Learning will remember than and retry to launch the guide.

Also, I would recommend to remove the sticky setting because the guide should only appear on this URL and go away if the user navigates to a new page.

Help Widget Explained

What is the help widget?

The Help Widget is intended to be a one-stop-shop for customer self service. Used correctly, it should be the first place your users go to to search for help and assistance on your application. Placing the right content into the Help Widget will reduce the number of support requests and drastically improve the onboarding process of users.

Technically speaking, the Help Widget is an HTML component that sits on top of your application. Normally it contains a list of step-by-step, walkthrough guides and important links (e.g. a link to the product knowledge-base). By default the Help Widget is located on the right hand side of your application (see image below).

Delivering contextual help

The content of the Help Widget is completely dynamic. As the training professional, you have all the power to control what content it holds directly from the Guided Learning dashboard without requiring any IT resources.

As a result the Help Widget is a great way to deliver contextual help to your users. With it you can:

• Show content that is only relevant to the page that the user is currently on, using page conditions
• Show content based on the role of the logged in user, using user fields. For example, you can display two completely different guides to a sales rep and a sales manager.
• Show content based on user activity. For example, only show a link to guide 'update opportunity' if the user has already completed the guide 'create opportunity'.

All of this is possible using guide activation conditions.

Extended features

Customers can further leverage the Help Widget by posting links to training in the corporate LMS, policy documents and videos

Guide search

Allows your users to search for other relevant guides on the Guided Learning platform. That is, guides that are not displayed in the Help Widget but match a certain keyword. Your user will then be able to launch these guides directly from the search results.

How do I make an image a session variable?

Use case:

You want to branch a guide based on user's choice. You have already setup the session variables but instead of the buttons you want to use an image.

To do so you will need to open the extended editor and click on the source button to display the raw HTML source of your tooltip. You should see something like this:

<a class="next-btn--choice" data-iridize-role="choiceBt" 
data-iridize-vars="{&quot;v1&quot;:&quot;yes&quot;}" href="javascript:void(0)">
yes
</a>

to replace the button with an image you will need to replace the yes (on the 3rd line above) with an img (image) html tag.

<a class="next-btn--choice" data-iridize-role="choiceBt" 
data-iridize-vars="{&quot;v1&quot;:&quot;yes&quot;}" href="javascript:void(0)">
<img src="mypicture.png" />
</a>

How to configure Country Segmentation

Add the following code to the custom script:

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

I cannot preview a guide that my colleague created

To preview a guide in the application, Guided Learning needs to be embedded in the application or you need to our browser extension installed locally.

To preview a guide through the OGL console, you need to have been granted the correct user access.

I have made some changes to a guide and saved them accidentally, can this be reverted?

Yes.

When you edit a guide a new revision is created.

I have successfully setup Guided Learning but the Help Widget does not appear

Make sure that at least one guide is set to "always" display in the Help Widget by using the guide activation conditions.

Note: If using Guided Learning in "prod" mode, please give any changes you have made to the activation conditions around 10 minutes to propagate. You may also need to clear your browser's cache.

I need to create a guide on a page with a dynamic URL, what are the best practices?

Let's solidify this with a concrete, real life example:

You offer a document signature service; each time someone creates a document for signature, the URL changes based on random, system generated, document ID. The url looks like this:

www.acme.com/sign/document?id=123456

Before anything, read the URL configuration for a guide FAQ.

Now let's break things down to work flow steps.

Creating/Editing the guide

To create your guide, simply choose a random document and enter the url in the Guided Learning guide creation form:

If you want to edit the guide and the document no longer exists, no problem, you can change the Editing URL. Also, once you click on the guide to edit it you can navigate to the desired page, the Guided Learning editor should stay with you on the left hand side.

Previewing the Guide

Opening the preview of the guide should take you to the same random document you choose when creating the guide. If you want the preview to start on another page you can either change the URL of the guide or navigate to the relevant page as you normally would with the browser until you reach the right page - the guide should start automatically.

Launching the Guide

Assuming you want to automatically launch the guide on all these pages, no matter what the document ID is, you will need to URL Matching condition in the guide activation conditions.

Based on the above example the condition would look like this:

Notice that the we only tell Guided Learning of the part of the URL that matters to us. Since we want the guide to show on all documents we simply omit the id parameter from the URL condition. Alternatively if we want the guide to launch only on a specific document we could say:

/sign/document?id=123456

Furthermore, Guided Learning is configured by default to ignore the domain names. this means that if your application runs on multiple sub domains you will not need to create special guides and conditions for each sub domain.

I receive the message "A tip is waiting for the page to refresh." What does that mean exactly?

This message means that the tooltip on the next step, probably step 3 is waiting for the page to refresh.

To change this behavior, open the 3rd step in the Guided Learning editor and under the activation settings, unset the Show tip after page refresh setting.

When should I use this setting?

Consider the following situation, you have a guide for running a company search on LinkedIn. Your first step will be to enter a company name in the search field and than to click on the magnifying glass in order to run the search. For the third step, you would like a splash screen that will pop up once the search results are loaded.

If you do not set the 'Show tip after page refresh' setting, as soon as you click on the search button the Splash Screen you set up in step 3 will appear, even though the search has not finished running. Then LinkedIn would load the search results, and the Splash Screen will display again. To avoid this behavior the 'Show tip after page refresh' should be set to delay the splash screen from appearing until after the search has completed and the page has refreshed.

I setup Guided Learning and none of my guides are showing, what's missing?

Please verify that at least one of your guides has active activation conditions.

Show me how

1. Click on activation settings in any guide

   

2. Check that at least one activation condition is set to show flows in the widget. This example is 'always show.'

I want a guide to show on 2 different pages with different URLs. How should I set up the conditions?

When you create a URL matching condition you can use a regular expression.

To tell Guided Learning that the string is a regular expression surround it with square brackets [ ].

So, let's say you want your guide to display if either the word “homepage” or “adlist” appear in the URL.

The regular expression for that is homepage|adlist and with brackets [homepage|adlist]

If I want a guide to only show when referenced/linked from another guide but I do not want it to be in the help guide list, how do I set the guide activation?

You will need to delete all activation conditions for the guide.

Click the Trash icon for all of the activation conditions in the guide

After doing so you will see this warning, which is exactly what we want.

"For your guide to be shown it must have at least one active condition."

Then click OK to save your work.

Invisible Steps: React to User Interactions

• Is it possible to start a guide after a user clicks on a certain button?
• Can I launch a guide after a user has started filling out a form?
• Can I wait for a user to click on a button and continue the guide only afterwards?

The answer to all these questions is YES, that's what the 'invisible step' is for.

Normally, any step in a guide/walkthrough will have at least one tooltip that is displayed on the screen and assists the end user. An invisible step has no visual representation. But, it still has all the powers of a normal step; it can still wait for any type of user interaction.

For example, the settings below will wait for the user to click on an element before showing the next tooltip.

Similarly, you can wait for the user to enter text in any form, or to click on the TAB key.

ADVANCED: If you leave the 'Advance when' setting unchecked the player will advance to the next step as soon as the target element is found on the page. An example of this would be skipping navigational steps.

Is it possible to change the font to an option not available within the dropdown list? We would like to add a font called "Proxima Nova" if possible.

Changing the drop down is not currently supported.

But, if your font is supported by all common browsers; or if you already downloaded this font to the end user's browser, you can simply switch to source view in the Guided Learning editor and change it. like so:

<p style="font-family: "Times New Roman", Times, serif;">text in Times New Roman</p>

Text is in Times New Roman.

If you want to globally change the font of all text in your guides download our design kit from the theme page.

Is it possible to change the text on the buttons in the interactive tour? Either by having the same language shown for all users, or making the button text dependent on a user setting?

You can update the default text on the buttons for all guides and all users.

We call this a tiplate (tip + template).

If you want to update the text of the next button on a specific guide for all users you can do that using the setting 'Change Next button text to'. You will find it in the display setting in the Guided Learning editor.

If you want to change the text of the next button on a specific guide based on a certain user setting you can do that too.

First you will need to set an Guided Learning variable like so:

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

than you can set the 'change next button text' setting to:

{{username}}

and the button will then display 007 (instead of next)

Is there a way to search for guides by keyword through the Guided Learning JS API?

Guide searches happen on the client-side in order to avoid extra communication with the servers.

We do not currently have a dedicated API function for searching but we do have an API function that lists all the guides that you can use as described below:

function search(query){
	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];
			if(guide.displayName.indexOf(query) != -1){
				console.log('name matches query: ' + guide.displayName);
			}
			if(guide.description.indexOf(query) != -1){
				console.log('description matches query: ' + guide.description);
			}
		}
	});
};

My application uses popup windows/multiple browser tabs, what is the best way to create guides?

In case you want to instruct your users through a process that spans multiple tabs or windows you will need to create a separate guide for each window and link the guides together.

Often, you will not want to display the help widget in such popup windows. If this is the case use the special API setting to disable the help widget.

iridize.showStartPanel=false;

My guide does not load on the right URL

In order to support running the same set of guides on multiple domains and sub-domains, by default, Guided Learning does not take into account the domain name when evaluating page conditions.

If you'd like to be sure that the domain name is taken into account, either set the exact match flag or use a regular expression.

No checkboxes were selected

Let's quickly explain what the following error message means:

Failed to save conditions: Condition 1: No system tags selected.

Every activation condition must be assigned to at least one 'activation mechanism'.

Currently Guided Learning support 2 such activation mechanisms.

1. Autoload - Launch a guide automatically as soon as the page is loaded.
2. Help Widget - Display the guide in the help widget.

If you don't specify at least one of the activation mechanisms Guided Learning will not know when to apply a given condition.

If you want your guide to have no activation conditions, this can be very handy if you want to create a launcher of an email campaign, you need to delete all conditions by clicking on the trash-can icon.

Our product is internal, behind a firewall, can we still create Guided Learning guides for them?

Yes.

Guided Learning uses a browser extension to create and manage your guides. As long as your computer has access to both the internet and the internal network you will be able to create guides.

Remove Border from Table

When you create a tip with a table in it, say, for formatting purposes, you don't want the border to be visible. In order to have no border, the following must be added to the theme:

div.sttip table, div.sttip tr, div.sttip td {

 border: none;

 padding: 6px 9px;

}

Scroll Parent Container: Handling Internal Scrollbars

Overview of Scrollbars

To understand this setting we must first understand what a scrollbar is.

"A scrollbar is a graphical control element with which continuous text, pictures or anything else can be scrolled including time in video applications, i.e., viewed even if it does not fit into the space in a computer display, window, or viewport."

You would normally see a scrollbar on the right hand side of your browser. It allows you to scroll the text up/down in order to see the whole page. Sometimes, however, a web application would include additional scrollbars.

Gmail is a great example of this (see image below with 2 internal scrollbars highlighted).

Back to Oracle Guided Learning...

Let's say you want to create a guide on a page with an internal scrollbar. And let's say that you need to scroll that internal scrollbar in order to highlight a certain element in your guide.

Notice that in order to view this element (for example a certain email in your gmail inbox) you need to use the internal scroll. Scrolling the standard browser scrollbar on the right will not help at all.

When you run this guide, Guided Learning will try to automatically sense that you element is contained in an internal scroll but sometimes it will not succeed in doing so. For this reason, by setting 'Scroll parent container', you can explicitly tell Guided Learning that it needs to scroll an internal scroll to bring a certain element to view instead of scrolling the default browser scrollbar.

Scroll Screen to See the Section where the Tip is Pointing

This is the default behavior for any tooltip. If it doesn't scroll automatically it normally means that you have an internal scroll.

Try setting the 'scroll parent container' in the advanced settings menu.

Select the First of Multiple Same Elements

Problem

Often encountered in tables, if you have multiple elements with the same name, how do you select a specific one based on position in the list

Solution

If the element you want to select is .subTextCustomer.wordEllipses but there are multiple such elements on the page, and the only one you are interested in is the first one, then use this to select:

.subTextCustomer.wordEllipses:eq(0)

Skip Step not Working

When trying to make a step skip based on the target element not being visible, sometime the guide does not skip the step as expected. When this happens, check to make sure that "Monitor Selector" is not chosen.

Instructions

Add the steps involved:

1. Select "Skip if element no found..." option in the Activation Settings section

   

2. Make sure that Monitor selector option in the Advanced Settings section is NOT checked

   

Unable to Edit Guide Options

Whenever you edit a guide, Oracle Guided Learning locks it so that nobody else could edit it while you are. Moreover, if you edit a guide in one browser tab or window and try to edit that same guide in another tab Guided Learning will block you from doing that and issue the following warning to the screen (as can be seen in the image above):

This scenario is currently opened for editing in another window. You may only view the options at this time.

Normally this could happen if:

1. A colleague is editing the guide: If this is the case there is nothing you can do but ask the colleague to close his editing session.
2. You have the guide open for editing in another window/tab: Go to that tab and either make your change there or close it.
3. Guided Learning thinks that you have the guide open for editing in another window/tab but you don't: This could happen if you indeed opened the guide for editing and closed the browser tab/window without clicking on discard in the Guided Learning editor. To unlock the guide in such a situation, open the guide for editing again:

   

4. Click the Pick up where you left off link. Once the Guided Learning editor is loaded, click on the Discard button. This should unlock your guide and allow you to edit it again.

Use an Image Map to Launch a Guide

An image map is an image with clickable areas.

What if you want that if the user clicks on one of these areas an Oracle Guided Learning guide would launch?

To define an image map you can use online tools like https://www.image-map.net/ or follow this tutorial https://html.com/images/how-to-make-an-image-map/

After you have created your image map, you will need to add a few attributes to each area in the map. These attributes will tell Guided Learning what to do when the area is clicked. The best way to get these attributes is to create a Launch guide button and copy these attributes from it.

For example, your area could look like this

<area alt="Sun" coords="0,0,100,99" shape="rect" />

and you will change it to:

<area alt="Sun" coords="0,0,100,99" data-iridize-nextscenario="{&quot;nextScenario&quot;:&quot;fd0qtw7w&quot;,&quot;dontClose&quot;:false,&quot;next&quot;:&quot;&quot;}" data-iridize-role="nextScenarioBt" href="javascript:void(0)" shape="rect" />

We have clients who use different terminology such as "Intake" instead of "Class". Is there any way to have two different terminologies depending on the viewer?

Yes.

Use our javascript API to set the preferred terminology for the user.

iridize("api.vars.set", {"terminology":"Intake"});

If you have already set this up using api.fields.set, you can skip this.

Then, in any place in your guide you can use {{terminology}} and the Guided Learning player will know to replace it by "Intake".

We use a different subdomain (sub-domain) for each customer; can the same set of guides be used on all domains by all customers?

All of your guides in Guided Learning are grouped into what we call applications. An application is essentially the product that you want to use Guided Learning on, this can be your very own SaaS offering or any other web application. Each application has a unique identifier.

When you embed Guided Learning, as part of our Javascript API you state which set of guides you want to use by providing the application identifier.

You can provide Guided Learning with the same application identifier on multiple domains, sub-domains, or app instances; as a result the same set of guides will be used in all.

What if I want the guide to advance when user clicks on ANY element in a list?

No problem.

Actually you can choose from one of the 2 options below depending on your preference.

Example

Say we want to create a guide for LinkedIn on how to apply for a job @ Google. You explain to the user how to run a Job search and now, when the user is on the search results page you want the guide to continue no matter which job the user selected from the list.

There are 109 google jobs posted on linkedin and we want Guided Learning to grab a click on all 109!

Our guide is not one step #3 and we are instructing the user to "click on any job for the list below".

Option 1 - Multiple Tips

Instead of trying to identify a click on any one of the 109 jobs we will add another tooltip to step #3 that will only display if the user is on a job listing details page (obviously this means s/he clicked on an item from the list)

To do this we need to:

1. Add another tooltip to step #3
2. Add a condition to this tooltip so that it will only show on the details page. It is common to use the URL condition or a visible element condition.

   In the LinkedIn example, I would have used, 'when page has url matching /jobs/view/'.

Option 2 - Manual Selector

To follow this option you must have a good understanding of CSS and specifically CSS selectors.

When you place an Guided Learning tooltip on a page, Guided Learning works hard to find the best suitable identifier for the element you want the tooltip to point it. A crucial part of this is to find a unique identifier that will match only the element that you selected. Here, we want to bypass this mechanism and choose a selector that will match all of the search results.

In our example, all job listing links share a common class "job-title-text". In order to have Guided Learning wait for a click on ANY one of them, we need to check 'Change Advance on Event Target' and manually change it to .job-title-text .The '.' prefix is not a mistake, it denotes a CSS class.

Summary

Each of the above options has its merits. Option 2 is quicker to set up, Option 1 does not require any technical knowledge and creates a much better user experience whereby if the user goes back to the search results page the tooltip to "click on any job for the list below" will display.

What is Advanced Visibility Check?

On some applications, OGL might think that an element is visible while it is not. This can happen if the web application uses multiple layers and an element could be hidden behind another one that was added on top of it. This setting will run some extra checks against the element.

Advanced Visibility Check asks the browser; what is the topmost element given coordinates on the window? If the element whose visibility we test is returned by the browser as the topmost element than we conclude it is indeed visible.

This setting is not used by Guided Learning by default because it is somewhat resource intensive on the browser.

The advanced visibility check can be turned on under the advanced settings of a step or when configuring step conditions.

What is fieldsNotSet error?

When using Oracle Guided Learning in a Single Page Application (SPA), sometime the embed code is executed before the user has logged into the application. In this situation one must call

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

This tells Guided Learning that this is an SPA and to wait for the user to be set before loading any content.

If within 5 seconds after the page loaded the user is still not set Guided Learning will issue the fieldsNotSet error to the browser's console.

This error log was added to assist developers in embedding Guided Learning. The error does not affect the loading of Guided Learning and as soon as 'api.fields.set' is called the content will be loaded correctly.

What is length of Description Field?

The limit is 2,147,483,647 characters.

However please keep in mind the user experience.

What is routeNotSet error?

When using Guided Learning in a Single Page Application (SPA), one must call

iridize('api.route.wait', {}) 

This tells Guided Learning that this is an SPA and to wait for the route to be set before loading any content.

If within 5 seconds after the page loaded the route is still not set Guided Learning will issue the routeNotSet error to the browser's console. This error log was added to assist developers in embedding Guided Learning. The error does not affect the loading of Guided Learning and as soon as 'api.route.update' is called the content will be loaded correctly.

To configure this timeout set iridize.setRouteTimeoutMillis in your embed code.

What is the best way to embed a simple audio file into a step?

Guided Learning does not offer a hosting service for audio files.

Assuming your file is hosted elsewhere you should be able to use the media embed button in the extended editor to embed it.

What is the difference between the two Oracle Guided Learning deployments?

Guided Learning supports two deployment modes: production and development.

You define your deployment mode in the embed code by setting the env variable.

iridize.env=["prod" | "dev"]

When I copy the URL of the page I want the guide to start from, it does not load correctly in the browser

Some web applications are sensitive to pages being accessed directly as opposed to normal site navigation.

If this is the case, when creating the guide, simply copy the homepage or dashboard URL in the OGL editor and once the page is loaded simply navigate to the desired page as you normally would.

Why doesn't my guide show up?

If you have created a guide and it does not show up, look no further, you have come to the right place.

This article outlines a checklist that you can go over in order to get to the bottom of the issue.

Is Guided Learning embedded?

Before we do anything, let's make sure that Guided Learning is embedded on the page where the guide should appear.

The easiest way to verify that is to check if there are other guides displaying on this page. Even if the help widget appears it means Guided Learning is embedded properly.

If Guided Learning is not embedded you will need to update the JS in the Fusion instance.

Is the guide published?

Every Guided Learning guide has multiple revisions. This is important if you want to update a guide that is currently in production with new new content that is only available in your staging/UAT.

If your guide does not have a published revision it will not show in production at all.

[A draft guide is indicated by the orange DRAFT label]

If the latest revision of the guide is a draft you will only see you latest changes in the staging/UAT environment.

Unpublished Revision indicates that the latest revision of the guide is a draft.

In both situations, you will only see the guide in your staging/UAT environment. To see the guide in production click PUBLISH to publish any recent updates.