Set up a Cross Domain/Cross App Guide

Cross-Domain

An application can have IFRAMES which are can be serviced from the same domain as the main page (also known as the top) or from a different domain. For security reasons, if an IFRAME is serviced from a different domain, the browser does not allow the OGL player to access it from the top window.

To create OGL solutions that can start from the top window and continue in the IFRAME, we need to create a communication channel for OGL between the top frame and the IFRAME.

To make this happen, the following prerequisite steps have to be carried out:

  1. Request the correct script for the main application (if applicable)
  2. Request the OGL script for the IFRAME (Ensure iridize.stateOnly=window != top ? true : undefined; is included in the JavaScript for the IFRAME and the main application)
  3. Embed/enable OGL in the top frame (the main application i.e. Fusion)
  4. Embed OGL in the IFRAME (Note: if there are several IFRAMEs being serviced from different domains, each of these IFRAMES need to have the OGL script embedded)

How to Set-up a Cross-Domain Guide

Let's say we have a process guide with 10 steps as an end-to-end process, with the first five steps being executed in the top frame, and the last five being executed in the IFRAME as illustrated below:

Cross Domain Guide Connection

From the illustration, we see that we need to set up a Cross-Domain Guide Connection between steps 5 and 6 in the E2E Process. To enable this, we build the E2E process guide in parts:

  1. First, build part of the process to run on the 1st application as one guide (Steps 1-5).

    Steps 1-5

    End to end process guide draft

  2. Then build the part of the process to run on the 2nd application (Steps 6-10).

    Steps 6-10

    Note:

    Take a note of the apiName.

    E2E Process guide draft1

  3. Open the top frame part of the guide in the OGL Full Editor
  4. Select the last step in the guide (i.e. step 5 in our example)
  5. Select Step Settings
  6. Expand the Advanced Settings section
  7. Select Add next to Step Branches
  8. Select Add Branch

    Add a Branch

  9. Select Launch a Cross-Domain Guide from the dropdown.
  10. Enter the apiName of the iframe part of the guide
  11. Enter the Start from step
  12. Enter the selector for the IFRAME (See IFRAME Selector Guideline below)
  13. Select Done to save the branch.
  14. Save and close the guide

    Once these steps have been completed, the user executes the guide (top frame part of the guide), the iframe part of the guide will be executed when the user moves past the step with the branch.

    Key considerations

    • Determine if the iframe part of the guide should be in the OGL Help Widget or not)
    • Determine when and how the step with the branch advances (i.e. advance on click etc.)
    • Determine how to track these guides in analytics
    • Determine a clear documentation strategy for maintenance
    IFRAME Selector Guideline for Cross-Domain BranchesBasic Idea on Selectors
    • attr^=val : gets an attribute starting (^) with val.
    • attr*=val : gets an attribute containing (*) val.
    • attr$=val : gets an attribute ending ($) with val.

    For example:

    • iframe[src*="/servlet"] returns an iframe with src containing “/servlet” in any part of the string.
    • iframe[src^="/5001"] returns an iframe with src starting with “/5001”
    How to get the proper selector

    1. Do an inspect element on the iframe.

    2. Find the iframe src attribute.

    3. Use a subset of its value. For instance: The iframe “File Attachment” has the src“ /5001 F000002jdbq ?isdtp =vw&isWsVw=true&nonce=2014e000ccc4c41384944ea28a38fe591b2b936d9b48d5d99f2bdffda916bfd5&sfdcIFrameOrigin=https%3A%2F%2Fkphr--trn1.cs90.my. salesforce.com”

    • The following three selectors can be use for the iframe above.
      1. iframe[src*="?isdtp"]
      2. iframe[src^="/5001"]
      3. iframe[src$="my.salesforce.com"]

    Always pick the selector that looks more likely to identify a single iframe. For instance, by choosing 2 or 3 there is a higher chance of referring to more than one iframe, therefore the cross-domain call could fail.

  • code sample

In case of nested IFRAMES (iframe inside another iframe)

use '>>' as a separator eg: iframe[src*="AdfLoader"] >> iframe[src*="PageLoader"]

Cross-Application

An application can start in one application (i.e. Fusion) and continue in another application (i.e. CPQ). Normally, this means a new browser tab will be opened when moving from the first application to the second. Similarly, we need to create a communication channel for OGL, we achieve this by embedding OGL in both applications.

The following prerequisite steps have to be carried out:

  1. Request the correct script for the main application (if applicable)
  2. Request a new appID and the OGL JavaScript for the 2nd application (Ensure iridize.crossAppIframe=true is included in the JavaScript)
  3. Embed/enable OGL in the first application ( i.e. Fusion)
  4. Embed OGL in the 2nd application
How to Set-up a Cross-Application Guide

Similar to a cross-domain guide, a cross-application guide has to be built in parts. the key difference is that for cross-application, the parts cannot be in the same OGL APPID.

Let's say we have a process guide with 10 steps as an end-to-end process, with the first five steps being executed in the main (1st) application, and the last five being executed in the 2nd application as illustrated below:

Cross App Guide

From the illustration, we see that we need to set up a Cross-Application Guide Connection between steps 5 and 6 in the E2E Process. To enable this, we build the E2E process guide in parts:

  1. First, build the top-frame part of the process as one guide (Steps 1-5) in one appID.

    Steps 1 to 5

    E2E_A

  2. Then build the iframe part of the process (Steps 6-10) in the second appID.

    Steps 6-10

    E2E Process guide draft1
  3. Go to the first part of the process guide
  4. Open the guide in the OGL Full Editor
  5. Select the last step in the guide (i.e. step 5 in our example)
  6. Select Step Settings
  7. Expand the Advanced Settingssection.
  8. Select Add next to Step Branches.
  9. Select Add Branch

    Launch a cross app guide

  1. Select Launch a Cross App Guide from the dropdown
  2. Enter the appID of the 2nd application
  3. Enter the apiName of the guide in the 2nd application (this is the second part of the process guide)
  4. Enter the Start from step
  5. Select Done to save the branch
  6. Save and close the guide

Once these steps have been completed, the user executes the guide (in the first application), the second part of the guide will be executed when the user moves past the step with the branch.

Key considerations

  • Determine if the iframe part of the guide should be in the OGL Help Widget or not)
  • Determine when and how the step with the branch advances (i.e. advance on click etc.)
  • Determine how to track these guides in analytics
  • Determine a clear documentation strategy for maintenance