11 Troubleshooting

This chapter describes problems that you may encounter when using Oracle Guided Learning and provides you with information about how to diagnose and overcome such problems.

Diagnostic Tool

Diagnostic Tool allows content developers to diagnose different types of guide issues they may encounter and efficiently troubleshoot them from within the application. This feature adds an additional option for content developers to independently troubleshoot and remediate common types of guide issues without the need to contact support. Content developers can enable the diagnostic tool on any page of the host application to quickly identify and resolve common guide issues.

Some common questions that this tool can help to answer include:
  • What user fields are set for this user? (maybe the guides are not launching because the field you are expecting is not set.)
  • Is OGL embedded with env = dev or prod?
  • How do I identify the page I am on?
  • What guides are currently running on this page? (this can be used to identify which guide is displaying an unwanted tooltip)
Launching the Diagnostic Tool

To invoke the Diagnostic Tool from any page on the host application, right-click anywhere on the page, then select Inspect.

Inspect

In the Inspect panel, select Console, then enter the following text string into the command line: iridize.diagnose();Then press the Enter key

Iridize Diagnostic

The Diagnostic Tool will open. Select an issue that best matches the issue that you are experiencing.

Note:

You may close the Inspect panel to expand the browser back to normal size.

Guide break

The Diagnostic Tool will display any errors it identifies with a description of the error that includes relevant information about the guide error, including: AppID, Environment, OGL Server, Page ID, User Information (if applicable), Guide Name, ApiName, and Error Description.

Condition Test

Select Resolve the issue to be guided to the relevant OGL user documentation where you can find information on how to resolve this issue.If this does not resolve the issue, you can also select Log a service request to be directed to the appropriate OU Support page to submit a request for support.Select Save if you wish to download a text file containing all relevant information about this issue, which can be provided to the Support team to help facilitate a resolution more quickly.

Known Issues / Expected Behavior

The Diagnostic Tool will only work with OGL 24A Player Package and is not backward compatible to applications relying on an older version of OGL’s Player Package (prior to 24A).

OGL Slowing Down Host Machine

If you determine that OGL is slowing down the performance of the host machine, this is probably due to an OGL item containing a selector that matches the tooltip text.

A selected element could be span:contains("Name") and the guide tooltip could contain the word "Name" but wrapped in span:contains("Name"), this creates an infinite loop between an element that is in on the host application and the OGL tooltip.

  1. Open the suspect guide in the full editor and verify the selector under Advanced Settings or the Selector Dialog.

    Selector Dialog

  2. Expand the Text Editor.

    Text editor

  3. Select Source to view the source code.

    Full editor

  4. Scan through the code to find the text wrapped in the <span></span> tag and containing the matching text i.e. Sign In.

    Source

  5. Next, we recommend you update this a tagother than <span>, this can be <p>,<label>, or any other suitable HTML Element.

    Source with p tag

  6. Once updated, you can save your changes and the issue should be resolved.

Guide Activation Condition Troubleshooting

When Page Has Element / Visible Element

Depending on the version of JavaScript used to enable OGL on the application, activation conditions may not work as expected. This affects the 'when page has/has not element' and 'when page has/ has not visible element' conditions.

Review the OGL JavaScript and verify if it contains the following line:

window.addEventListener('load', function(){var e=document.createElement("script");var t=document.body;e.src=("https:"==document.location.protocol?"https:":"http:")+"//guidedlearning.oracle.com/player/latest/static/js/iridizeLoader.min.js";e.type="text/javascript";e.async=true;t.appendChild(e); });

Why does this happen?

The window.addEventListener line ensures that OGL loads after the application page has loaded. Therefore, it is not possible for OGL to determine whether or not the element is on the page.

Why should I do next?

DO NOT use the When Page Has Element/Visible Element conditions. Doing so will create inconsistent user experiences. Instead, set alternative conditions which suit the requirement.

Tip Flickering

How to Fix Flickering

Flickering occurs when you land on a page, and the tip appears, disappears, and reappears, often rapidly and continuously.

With just a few changes in the Advanced Settings of the tip, you can easily resolve any flickering issues.

To resolve the flickering of the tip:

  1. On the faulty Guide, select the Editor icon to open the OGL editor.

    edit_icon

  2. Locate the faulty step in the guide.

  3. On the faulty step, go to Step Settings > Advanced Settings.

    advanced_settings

  4. Under Advanced Settings,
    1. Turn on the Fixed Position.
    2. Turn on the Track Target Position.
    3. Turn off the Monitor Selector.

      Advanced_settings_options

    This combination of settings should resolve the flickering issue.

Tip:

If the issue persists, turn the Monitor Selector off and attempt the following steps:

Turn on the Fixed Position, turn off the Track Target Position, and switch them around if needed.

Is Your Smart-Tip Masked by the HTML Element? It Could Be a Z-Index Issue

Are you experiencing difficulty seeing your Smart-Tip (smart tip) or Beacon due to the HTML elements of the host application masking it? Or is the disabled-element icon (disabled element icon) invisible due to being masked by the HTML elements? If so, you may be facing a Z-Index issue.

What is a Z-Index Issue

A Z-Index is a CSS property that defines the order of overlapping HTML elements. Elements with a higher index value are placed on top of those with a lower index value.

Sometimes, OGL Items (Smart-Tips/Tooltips/Beacons/Disabled-element icon) are not visible as an HTML element with a higher Z-Index value is masking them. To resolve this, we must set a higher Z-Index value for the OGL elements like Smart-Tips, Beacons, etc.

hidden smart tip screenshot

Disabled element screenshot

Note:

Z-Index only works on elements with the following attribute (position: absolute, position: relative, or position: fixed), and where a Z-Index is not defined, it will have a default value of "auto."

Steps to Reproduce

Note:

Prerequisites

  • An OGL account with a Design Kit that has a lower Z-Index code for Smart Tip or Beacon.
  • A host application with a dropdown or pop-up menu in its UI.

Follow the below procedure to reproduce the Z-Index issue.

  1. On the OGL homepage, select Smart-Tip.

    Smart Tip

    The New Content modal window is displayed.

  2. Enter the Display Name.
  3. Enter the Location URL of the host application (that has a dropdown or pop-up menu in its UI).
  4. Select the Create button to create the Smart Tip.

    Create smart tip

    The OGL Editor now appears as an overlay to the host application.

    create index

  5. Select Add a Step.

    Add a step

  6. On your host application, navigate to any UI that has a dropdown or pop-up menu.
  7. Expand the dropdown menu and choose any one option from the menu to add a Smart-Tip.
  8. Hover over the option of your choice and select the Add Tip button.

    Select

    The Smart Tip now appears but is positioned further away from the dropdown option.

    drop down

  9. To bring the Smart Tip right next to the dropdown option, select Step Settings (step setting)to go to Display Settings.

    Display Setting

  10. Lower the Help icon offset: (left)value to bring the Smart-Tip closer to the dropdown option.

    help icon

    As you lower the value, you can observe the Smart-Tip moving toward the dropdown HTML element.

    Once the Smart-Tip and Dropdown HTML elements intersect, the Smart-Tip hides behind the Dropdown element instead of overlapping it.

    The Z-Index issue is now recreated.

    Issue created

Set a Higher Z-Index for OGL Elements

Suppose you recently enabled OGL in your host application and are experiencing the issue mentioned above. In that case, it could be caused by the Z-Index issue.

The HTML element on which the Smart-Tip or the Beacon is not showing up is probably using a higher Z-Index value than the one OGL uses. Hence, the OGL elements are active in the background and not on top of those HTML elements.

The workaround here is to add new codes for the Smart-Tip/Beacon and the disabled-element icon with a higher Z-Index value. This allows the elements to appear and not be hidden in the background.

Note:

  • For Smart-Tip and Beacon, always set a Z-Index value at least one digit higher than the Z-Index of HTML elements. This is the recommended setting.
  • The value of "2147483647" is the highest limit allowed for Z-Index on any element. However, using a value higher than or equal to the Z-Index value of the OGL widget is not a good idea as this could cause the Smart Tip or Beacon to appear over the widget in applicable situations.

OGL Widget

The workaround includes the following steps:

  • Downloading the Design Kit.
  • Updating the Design Kit (Adding the new codes with a higher Z-Index value).
  • Uploading the updated Design Kit.

Download the Design Kit

The existing Design Kit can be downloaded from the OGL Console.

To download the Design Kit:

  1. On the OGL Console homepage, select Settings>Theme.

    Theme

    The Theme modal window appears now.

  2. Go to the Upload/Download Theme tab.

    Upload and Download Theme

  3. Select the Download Design Kit HTML link.

    Download Design Kit

    The browser now downloads the OGL_Theme_Design_Kit_XXXXXXX.html file.

  4. Save the HTML file to a local directory.

Note:

Rename the file accordingly. We highly recommend you rename it using the following convention: Design_Kit_ORGNAME_DD_MMM_YYYY.

Update the Design Kit

The Design Kit provides the ability to update the theme however you want. But this article only gives some basic guidelines on updating/adding the Z-Index code for Smart Tips and Beacons.

Note:

Please note that modifying the Theme (Design Kit) might impact accessibility. For more information about Oracle's commitment to accessibility, see https://oracle.com/accessibility.

Note:

You need an HTML Editor to update the Design Kit.

To add the new codes with a higher Z-Index value:

  1. Open the Design Kit with the HTML/text editor.
  2. Copy the below lines and paste them into the Design Kit. (Before pasting it to the design kit, make sure to update the Z-Index value as necessary.)

    Note:

    • Set a Z-Index value at least one digit higher than the Z-Index of HTML elements.
    • Only if the host application's HTML elements are using the highest limit allowed, i.e., "2147483647" then set the Z-Index for Smart Tip as "2147483647 !important". This will override the higher value set by the HTML elements and gives priority to OGL elements. 
    Increasing Z Index*/

.ir-marker {
 z-index: 99999999999 !important;
}

div.ir-showBeacon {
    z-index: 99999999999 !important;
}

div.ir-showMarker {
    z-index: 99999999999 !important;
}

div.sttip .tooltip {
    z-index: 99999999999 !important:
}

div.stDisableDiv {
  z-index: 99999999999 !important;
}
  3. Save the changes, then upload the Design Kit to the OGL Console.

Upload the Design Kit

To upload the Design Kit

  1. On the OGL Console homepage, select Settings>Theme.
  2. Go to the Upload/Download Theme tab.
  3. Select the Choose a file button and choose the updated Design Kit from the local drive.

    Choose a file

  4. After selecting the updated theme, choose between creating a new theme or updating the current one according to your preferences.

    Create new theme

  5. Select the Upload button.
  6. Once the Design Kit is uploaded, a confirmation message appears.

    Confirmation

Verify the Issue

Verify the Smart-Tip or the Beacon is now visible and no longer hidden behind the dropdown or popup menu HTML elements.

Let's compare the screenshots before and after the workaround.

Before the workaround:

hidden smart tip screenshot

After the workaround:

After workaround

Content Security Policy (CSP) Error Correction

What is a CSP Error?

In simple terms, the OGL Help Widget will not load/display in the application due to a security policy.

Instead of blindly trusting everything that a server delivers, CSP defines the Content-Security-Policy HTTP header, which allows you to create an allowlist of trusted content sources and instructs the browser to only execute or render resources from those sources. The web's security model is rooted in the same-origin policy. For example, code from https://mybank.com should only have access to https://mybank.com's data, and https://evil.example.com should certainly never be allowed access. With this policy defined, the browser throws an error instead of loading scripts from outside sources (Source: Content Security Policy). This includes data from Oracle Guided Learning.

How to Troubleshoot

  1. Right-click (Control-click on a Mac) on the application Homepage, then select Inspect from the menu.
  2. Switch to the Console tab. Note the error in the Console relating to the Content Security Policy. It will read "Refused to load the script..." followed by the OGL URLs.


    error in browser console

How to Correct a CSP Error

  1. On the Fusion application Homepage, select the Settings and Actions icon (SI icon) and then select Setup and Maintenance.

    settings and actions

    Alternatively, select the Navigator icon (navigator icon) → Others → Setup and Maintenance.

  2. Select the Tasks icon (task icon) on the Setup and Maintenance screen to view the slide menu. Then select Search from the options in the slide menu.

    slide menu
  3. In the search field, enter "Manage Administrator Profile Values" and then select the Search icon (search icon).
  4. From the search result, select Manage Administrator Profile Values.

    A new window opens now, where you can manage Administrator Profile Values.

  5. Enter ORACLE.ADF.VIEW.ALLOWED_ORIGINS in the Profile Option Code field and then select Search.

    profile option

    Note:

    More information on this profile option can be found on Cross-Origin Resource Sharing.
  6. Scroll down to view the Profile Value results displayed.

    The field value may appear as "‘self’" or "‘self’ https://xyz.com" (with your organization-specific domain).Profile options results

  7. Depending on your data centre region, enter the Profile Value as provided below:
    • NA Tenancy: 'self' https://guidedlearning.oracle.com
    • EMEA Tenancy: 'self' https://guidedlearning.oracle.com https://guidedlearning-emea.oracle.com
    • APAC Tenancy: ‘self’ https://guidedlearning.oracle.com https://guidedlearning-apac.oracle.com

    Note:

    • You may find the field value appears as ‘self’ <third party URL> or ‘self’ with your organization-specific URLs. Do NOT overwrite any URLs that are already defined, add the OGL URLs to the existing URLs.
    • Use the whitespace separator (single space) between the URLs (i.e. 'self'<white_space><url_1><white_space><url_2><white_space><url_3>).
    • You can find more details on this profile value in this Oracle article.
    • This applies for Fusion version 21.04.0 or later.
  8. Select Save and Close to save your changes and exit the Manage Administrator Profile Values task.
  9. Log out of the application and log in again.
  10. Go to the Homepage to verify that the OGL Help Widget is visible.
    widget appears when error is corrected

    You have now successfully resolved the CSP error.

    CSP Error in Non-Fusion Applications

    If you experience a CSP error in your non-Fusion application, contact your IT support team to ensure that OGL-related servers and services are whitelisted.

Oracle Transportation Management (OTM) – Oracle Guided Learning Integration: CSP Error Analysis and Resolution

Problem Summary:

The Content Security Policy (CSP) error in the Oracle Transportation Management (OTM) application occurs when the browser blocks specific resources (such as scripts or stylesheets) from loading due to OTM’s strict security configuration.

CSP is a browser-level protection mechanism that defines which domains are permitted to load or embed application resources, helping to prevent security risks such as cross-site scripting and data injection.

In this case, the browser refused to load the stylesheet

https://guidedlearning-apac.oracle.com/fe/edge/static/css/stTip_2.min.css because the domain guidedlearning-apac.oracle.com was not included in OTM’s CSP style-src directive. As a result, Guided Learning features may fail to load or function correctly.

Depending on your data center region, include the domain in OTM CSP Headers:

Additionally, when an external application, such as Oracle Guided Learning (OGL), attempts to integrate with or embed OTM content through an iFrame or cross-domain request, the browser identifies CSP violations and blocks the content, resulting in integration failure.

To resolve this issue, the OTM CSP configuration should be reviewed and updated to include the trusted domain (guidedlearning-apac.oracle.com) under the allowed sources. Alternatively, Oracle Cloud Support should be engaged to whitelist the required domain and securely adjust the CSP settings.

How to Troubleshoot:

  1. Check the browser console: Open the Developer Tools (Console) and look for error messages such as “Refused to load...”.
  2. Identify the blocked resource: which file or domain (e.g., guidedlearning-apac.oracle.com) is being blocked.
  3. Review the CSP settings: In the Network tab, locate the Content-Security-Policy header.
  4. Compare and identify missing domains: If the blocked domain is not listed in the CSP directives, it indicates the source of the issue.

Root Cause Analysis:

The CSP (Content Security Policy) error occurred because the OTM application’s security policy did not allow loading resources from the domain guidedlearning-apac.oracle.com. The OTM instance is configured with a strict CSP rule that only permits styles and scripts from specific domains (like guidedlearning.oracle.com), but not from its regional variant (guidedlearning-apac.oracle.com). When the browser attempted to load guided learning stylesheets from this domain, it blocked them for security reasons. This restriction caused the guided learning or smart tip features to fail to load properly.

Resolution / Fix:

To resolve the CSP (Content Security Policy) error in the OTM application, the missing domain needs to be added to the list of allowed sources in the CSP configuration. Specifically, the domain guidedlearning-apac.oracle.com should be included under the style-src and script-src directives so that the browser can load the required guided learning resources without being blocked.

If the OTM environment is managed by Oracle Cloud, raise a Service Request (SR) with Oracle Support to update or whitelist the required domain in the CSP policy.

After the configuration is updated:

  1. Update the OTM environment’s CSP configuration to include trusted OGL domains under the frame-src and connect-src directives, allowing secure communication between OGL and OTM.
  2. Verify the integration using browser developer tools to ensure there were no CSP violations or blocked requests.
  3. Clear the browser cache and restarted the OTM application to ensure the updated CSP policies were applied successfully.
  4. Retest the end-to-end integration flow and confirmed that OGL and OTM communication functioned as expected without any CSP-related errors.

    This ensures the guided learning integration works smoothly without compromising OTM’s security controls.