Follow

Configuring In-Application Context-Sensitive Help

In-application context-sensitive help provides context-sensitive help for web-based applications by displaying uPerform content to users directly within the same browser window as the business application. When a user is in a web-based application configured for in-application context-sensitive help and requests help, there is a new panel that provides in-browser context-sensitive help.

The in-application published output type drives the content in-application context-sensitive help.  When the in-application help control is clicked, content stored in uPerform becomes available to the user.  The "steps panel" output type works with new and existing documents.  The in-application context-sensitive help contains steps and notes, which allows a user to scroll through the steps. Users cannot click on an individual step or screen.  In-application context-sensitive help content is not interactive like a simulation; it is read-only like a work instruction.  If there is only one matching document, and it has been published to the new in-application output type, it is displayed directly within the business application.  If there are no matches or multiple matches, a user can search or select from a list of matching content.  Other published output types such as cue cards, printable work instructions, simulations, and related content such as courses, managed documents, and web documents display in a separate browser.

The in-application context-sensitive help output type applies to .udc files published on the Server. The publication of this output must be enabled and pre-5.40 files re-published to create the content necessary for viewing "in-application."  Refer to Publishing Content For Display On The Website.

Display of search results through the in-application dialog follows the same rules as all searches where results are filtered based on existence of published content and user’s rights to view content from the project(s) containing the documents. The in-application dialog will provide a mechanism for users to log into the Server to view all matching content available to them.

NOTE:

Users only sign in to authenticate once per application. They do not need to reauthenticate if a new browser tab is opened for the same application.

Configuring In-Application Context-Sensitive Help

In-application help uses connection profiles like other context sensitive help solutions; however, there are some key differences. This solution renders a custom help button inside every application that is configured for in-application help and you can control the position and font color of the help button to provide a user experience appropriate for a given application. By selecting one of six button locations you can ensure the help button is prominently visible to users while not interfering with any native user interface elements. Additionally, you define the specific applications for which the help button will be displayed. This supports a couple of use cases: you can choose to provide help functionality only for applications for which you have created content or alternatively you may choose to enable it prior to any content creation and monitor user requests for help to drive your content creation activities.

Adding a Connection Profile

A connection profile must be created on the Server to enable the CSH on web pages.  You may have more than one connection profile of type “in-application” if desired. The decision whether to enable multiple applications via a single connection profile, or have multiple connection profiles should be based on the aspects that may vary from profile to profile: where you want the help button to display in a given application, and what color you want to use for the help button and the banner message bar that may display.

Refer to Managing Connection Profiles to the Server to create and edit your connection profile.

NOTE:

When creating your connection profile, select the Connector/Application combination that matches your application. If there are no matches, the Connector is Web and the Application is General Web App.

Publishing In-Application Context-Sensitive Help Content

Publication of the In-Application output must be enabled on the Server in order for end-users to view help content “in-app.”

  1. Click the Administration cog on the navigation bar of the Management Center.
  2. Select Servers > Publishing in the left navigation menu.
  3. Complete/review the following:

    Field

    Description

    Document area

    Select the In-Application checkbox in the Document area to enable conversion for In-application context-sensitive help.
  4. Click Save.

Security Considerations

Since in-application help works by having resources from the Server run inside browser-based business applications, there are various browser security-related settings to consider.

  • If one or more of the business applications for which you will deliver in-application help use https protocol, then the Server should be configured for https to ensure proper display of in-application help.
  • For Internet Explorer specifically:
    • The Server and the business application domain must share the same Internet "zone" in browser security settings.
    • If Enhanced Protected Mode is enabled, any business application URL or domain for which in-application help is enabled must be added as a “Trusted Site.” If necessary refer to Microsoft Internet Explorer documentation for required steps.
    • Compatibility mode is not supported.

Integrating In-App Help with your Business Application.

In order for the help content to be displayed inside a business application, part of the In-Application Help code must run inside that application. There are two ways to enable In-Application Help for one of your business applications.

  • Integrate the In-Application Help script reference in your business application
  • Deploy the browser extension(s)

Integration

When a Server administrator generates an In-Application Help connection profile, a script reference is created and displayed. The format of this script is as follows:

<script src="https://server.domain.top-level-domain/api/distribution/v1/cshextension/1.11.xxxx"></script>

This script reference must be added to your business application to display the In-Application Help user interface inside the application.

  1. Copy the script from the Snippet field from the connection profile you specified in Managing Connection Profiles to the Server.
  2. Paste the script into the HTML of your business application.

The recommended placement for the script is immediately before the closing </body> element in a given HTML document. The ideal integration scenario involves adding the script reference in a single place within your application's framework that results in the script being added before </body> whenever the HTML document is updated as user navigates within the application.

Installing Browser Extensions

Browser extensions are available for Internet Explorer (IE), Chrome, and Edge.

Each extension must be configured with a URL to connect to the Server. This can be done by individual users if installing the extension manually or as a parameter if installing the extension via some “push” mechanism. Each user will have to manually configure the extension only if the extension is installed manually.

NOTE:

The extension for IE will be replaced with the existing extension, if installed.

NOTE:

The IE add-on includes an Ancile.InAppIEAddOn.Broker.exe process. If your uPerform Server is external to your network, your corporate firewall or network security must allow external access to this process.

NOTE:

Third-party extensions must be enabled within IE for In-Application Help to work using the extension.  Navigate to Internet Options > Advanced and ensure the checkbox Enable third-party browser extensions is checked.

Manually Installing Browser Extensions

  1. Choose from the following options:

    If You Want To

    Then

    manually install the IE browser extension
    1. Go to the Learning Library.

      NOTE: If you are not using Learning Library, download the installation package from http://[Server Name]/AncileHlp/ANCILE_CSH.exe and double-click the .exe file.

    2. Select More... > Support to go to the Support page.
    3. Click GET EXTENSION to access the ANCILE_CSH.exe file.
    4. Click Run to install the browser extension.
    5. Go to Configuring the Extensions section.

    NOTE: The installation requires elevated permissions so a Windows User Access Control (UAC) prompt may occur.

    manually install the Chrome browser extension
    1. Using the Chrome browser, navigate to the Chrome webstore website.
    2. Search for the uPerform In-application Help Chrome extension.
    3. Click the Add to Chrome button.
    4. Click the Add extension button.
    5. Go to Configuring the Extensions section.

    manually install the Edge browser extension
    1. Using the Edge browser, navigate to the Edge Store website
    2. Search for the uPerform in-application Help Chrome Extension
    3. Click the Get button 
    4. Click the Add Extension button
    5. Go to Configuring the Extensions section

Automatic Deployment of Browser Extensions

  1. Choose from the following options:

    If You Want To

    Then

    distribute the IE browser extension

    NOTE: The extension is distributed as a .exe file, rather than an .msi, because it includes the Microsoft .NET prerequisite.

    1. Use a command line to silently install.

      Example: ANCILE_CSH.exe /s /v"/qn ServerURL=https://ACME-admin.ancileuperform.com"

      The ServerURL parameter and value are optional and are used if you want to pre-configure the extension with a Server connection.

    2. Go to Configuring the Extensions section.

    distribute the Chrome browser extension via Windows registry
    1. Refer to Using the Windows registry in the Chrome documentation.

      NOTE: The ID of the extension is aefalnopbcachhkjnihfjgglnjdegicg.

    2. Contact Product Support to get the extension
      configuration installation package.

      NOTE: The configuration package installs files and registry entries that
      allow the extension to automatically configure
      itself on browser startup.

    3.  Install the extension configuration package in per-user or per-machine mode based on your situation. In general the per-machine scenario is recommended as it will support one user workstation, shared workstation, and Citrix-like scenarios. Examples of the configuration package installation command lines are shown below.

    NOTE: Substitute your actual uPerform Management Center URL value.

    Per User
    Batch file / CMD prompt (or similar):
    ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-
    admin.ancileuperform.com/"

    Powershell:
    .\ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-
    admin.ancileuperform.com INSTALLDIR=`\
    `"C:\Program Files (x86)\ANCILE\
    InAppCshExtensionConfigure`\`""

    Per machine
    Batch file / CMD prompt (or similar):
    ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-
    admin.ancileuperform.com ALLUSERS=1
    INSTALLDIR=\"C:\Program Files (x86)\
    ANCILE\InAppCshExtensionConfigure\""

    Powershell:
    .\ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-
    admin.ancileuperform.com ALLUSERS=1
    INSTALLDIR=`\`"C:\Program Files (x86)\
    ANCILE\InAppCshExtensionConfigure`\`""

     

     

    distribute the Chrome browser extension via Group Policy Objects (GPO)

    NOTE: Only Network Administrators with domain administration rights should perform these steps. If the user is not a domain administrator, the steps provided here should not be performed.

    Get the Policy Template for Chrome by performing the following steps:

    1. Log into the Active Directory Server, with Domain Administrator credentials.
    2. Download the Google Chrome adm template from http://dl.google.com/dl/edgedl/chrome/policy/policy_templates.zip.
    3. Extract the contents of the policy_templates.zip file once you have downloaded it to somewhere in the server (e.g., /Downloads/policy_templates/).

      NOTE: The policy templates .zip includes both ADM and ADMX templates. Use whichever is best suited for your network configuration.

    4. Continue to the next step to add the Chrome Policy Template to GPO.

    distribute the Edge browser extension via Window registry 
    1. Refer to Use the Windows registry in the Edge documentation
    2. The ID of the extension is
      hfabndgahaagaoemkgociifnneapjigf.
    3. Contact the Product Support to get the extension configuration installation package.                                                                    Note: The configuration package installs files
      and registry entries that allow the extension to
      automatically configure itself on browser
      startup.
    4. Install the extension configuration package in per-user or per-machine mode based on your situation. In general the per-machine scenario
      is recommended as it will support one user workstation, shared workstation, and Citrix-like scenarios. Examples of the configuration
      package installation command lines are shown below

    NOTE: Substitute your actual uPerform Management Center URL value.

    Per User
    Batch file / CMD prompt (or similar):
    ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-
    admin.ancileuperform.com/"

    Powershell:
    .\ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-
    admin.ancileuperform.com INSTALLDIR=`\
    `"C:\Program Files (x86)\ANCILE\
    InAppCshExtensionConfigure`\`""

    Per machine
    Batch file / CMD prompt (or similar):
    ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-admin.ancileuperform.com ALLUSERS=1
    INSTALLDIR=\"C:\Program Files (x86)\
    ANCILE\InAppCshExtensionConfigure\""

    Powershell:
    .\ANCILE_InAppCshExtCfg.exe /s /v" /qn,
    ServerURL=https://support-prod-
    admin.ancileuperform.com ALLUSERS=1
    INSTALLDIR=`\`"C:\Program Files (x86)\
    ANCILE\InAppCshExtensionConfigure`\

     
  2. Choose from the following options to add the Chrome Policy Template to GPO:

    If You Want To

    Then

    use the ADMX template
    1. Using File Explorer, open the ADMX subfolder in the unzipped policy templates folder: policy_templates\windows\admx\.
    2. In a different File Explorer window, open the PolicyDefinitions folder: %systemroot%\PolicyDefinitions\

      NOTE: In most cases, this will be C:\Windows\PolicyDefinitions\.

    3. From the admx folder, copy chrome.admx to the PolicyDefinitions window.

      NOTE: This will likely ask for administrator permissions.

    4. Back in the unzipped policy_templates’ admx folder, there will be folders named by locale (e.g. en-US). Go to your preferred locale folder (policy_templates\windows\admx\en-US\).
    5. There should be a matching locale folder in %systemroot%\PolicyDefinitions\. Copy chrome.adml to the policy definition’s locale folder (%systemroot%\PolicyDefinitions\en-US\).

      NOTE: This will likely ask for administrator permissions.

    6. Select Start -> Administrative Tools -> Group Policy Management to verify the template has been added.
    7. Right-click the domain policy you plan to update and select Edit to open the Group Policy Management Editor.
    8. Expand Policies, then Administrative Templates.

    NOTE: Under Administrative Templates, there should now be two Google Chrome nodes added: Google Chrome & Google Chrome Default Settings.

    use the ADM template
    1. Select Start -> Adminstrative Tools -> Group Policy Management.
    2. Right-click the domain policy you plan to update and select Edit to open the Group Policy Management Editor.
    3. Under the Group Policy Management Editor, right-click Administrative Templates and select Add/Remove Policy Templates from file….
    4. Navigate to your locale’s ADM template in the unzipped policy_templates folder in policy_templates\windows\adm\ (e.g. policy_templates\windows\adm\en-US\).
    5. Select the chrome.adm file.

    NOTE: A new child node has been added to the Administrative Templates Policy/Classic Administrative Templates (ADM)/Google/Google Chrome node.
  3. Select the Extensions node to configure the Chrome Policy to install the uPerform In-Application CSH Chrome extension.
  4. On the right pane, double-click Configure the list of force-installed apps and extensions.
  5. Select the Enabled radio button option, under the top panel.
  6. In the Options panel, click the Show button.
  7. On the Show Contents pop-up window, complete the first blank row value with the following value:

    aefalnopbcachhkjnihfjgglnjdegicg;http://clients2.google.com/service/update2/crx

    NOTE:

    The extension ID has been added.
  8. Close the Group Policy Management Editor.
  9. Right-click Default Domain Policy in the Group Policy Management window.
  10. Select the Enforced option to ensure the group policy is being distributed.

    NOTE:

    After the group policy changes have propagated, you can verify the policies being applied by navigating to chrome://policy in Google Chrome.
  11. Contact Product Support to get the Windows PowerShell script file.

    NOTE:

    The script file specifies a ServerURL parameter used to pre-configure the extension with a Server connection.

Configuring the Browser Extensions

Automatically deploying the browser extension supports configuring the browser extension with the Server URL specified during installation, so it is the preferred deployment method. For Internet Explorer, the Server URL is indicated in the command line. For Chrome, the Server URL is indicated in the Windows PowerShell script file provided by Product Support. Manually deploying the browser extension for Internet Explorer and Chrome requires the end user to navigate to the Learning Library to configure the browser extension.  Once an extension is configured, the administrator may update the set of connection profiles. The extension will periodically check the Server and collect any changes, such as additions or deletions, to the set of configured connection profiles.

NOTE:

For the Chrome or Edge extensions, make sure the extension is enabled.
  1. Navigate to the Learning Library after the extension is installed.
  2. Select More... > Support to go to the Support page.

    NOTE:

    The extension is configured. The uPerform Browser Extension section displays the applications for which the browser extension is enabled.

User Authentication

The in-application context-sensitive help dialog displays inside your business application(s), but it renders from the uPerform Server. As described previously, content displaying in-application is controlled by the Server’s settings relating to authentication method. The in-application dialog uses the same authentication settings and method as the Server so the user will be presented with a window and authentication prompt just like if they were logging into the end-user website view of the Server.

In-Application Context-Sensitive Help Reports

No new reports have been created specific to in-application help functionality; however, the following existing reports include data related to in-application help: Published Content, Website Usage, and Help Request.

Continue to the next article Creating A Template.

Was this article helpful?
1 out of 1 found this helpful