Configuring SAP Fiori and UI5 for use with Context Sensitive Help

You have licensed a context-sensitive help (CSH) solution for SAP UI5 applications. This solution enables a user to request help from within the UI5 application and return relevant content from your system.

NOTE:

This solution works with SAP Fiori applications since they are based on SAP’s UI5 technology.

NOTE:

This solution requires uPerform version 5.40.6 or later.

The solution provides a help button within your UI5 application. When the user clicks the help button, content related to the user’s current screen is displayed in the system website in a new browser window.

The help button and help panel areis built with UI5 and will inherit the styling of the UI5 application in which they areit is integrated. The styling of the content displayed in the help panelwhen the user clicks the help button is controlled by uPerform®.

The solution is comprised of two deliverable items:

• CSH solution file(s): code that must be added to your UI5 application. The code is delivered as a zip file. Some integration scenarios described later use the .zip file directly, while others require you to extract the .zip file.
• CaptureEngine configuration file: enables the automatic capture of context information when recording. This file is included in CaptureEngine version 6.40.1 which must be downloaded and deployed manuallyin the Auto-Update Client.

There are three steps to implement this solution:

1. Configure the solution with the location of your uPerform system and for your specific UI5 scenario.
2. Add the solution code to the SAP UI5 application.
3. Configure the CaptureEngine by ANCILE Solutions to recognize SAP UI5 context while recording.

NOTE:

All steps should be done before you create uPerform® content for SAP UI5 in order to capture context identifiers automatically while recording. If you already have content created for SAP UI5, you can manually add context identifiers to those files. Manually adding context is described later in this document. Steps 1 and 2 can be done any time relative to content creation but must be complete before your end users will use the CSH solution for SAP UI5.

End-User Perspective

An end user’s use of the CSH solution is intuitive. The user clicks the help button to request relevant help from the uPerform® system. For best results the end user should give focus to (by clicking on) some element in the UI after the screen changes before requesting help. The help content displays either in the help panel inside the UI5 application or in a separate browser window based on the configuration your organization has defined. The help content displays within the uPerform® website user interface so the user can navigate within the website if desired.

 Configuration

After extracting the solution files, you must configure several aspects of the solution for proper operation in your UI5 application and connectivity to uPerform.

NOTE:

The configuration changes can be done using the Integrated Development Environment (IDE) application you use to maintain your UI5 applications, or any text editor.

Connect CSH Solution to uPerform

The single point of connectivity between the solution and the help content is a URL that will be opened when the user requests help.  The help content is either part of an  Express website or is stored within your Server instance.  Steps for both scenarios are listed below; follow the one that matches the variant of uPerform your organization uses.

If you will use an uPerform Server instance to house the SAP UI5 content, you must define a connection profile for use in the solution. Refer to Managing Connection Profiles to the Server to create and edit your connection profile.

NOTE:

When creating your connection profile, the Connector is SAP and the Application is SAP Fiori.

NOTE:

The settings related to the size and location of the browser window do not apply when the help content is displayed inside the UI5 application.

1. From the solution files you extracted, open the …ancilecsh\configuration\configuration.json file.
2. Locate the HelpServer section, then the URL variable.
3. Replace the value of the URL variable with the URL generated when you specified a connection to the Server as described in Managing Connection Profiles to the Server

   NOTE:

   Make sure it is placed between the double-quotation marks. For example: URL=”http://[yourserver]/gm/1.11.XXXX?csh=”

4. Save changes to the configuration.json file.

Configuring the Solution for a UI5 Application

Your organization can modify several characteristics of the CSH solution to work best for your users and UI5 application.  The following settings are located in the …ancilecsh\configuration\configuration.json file.  The configuration file contains many settings, but only the ones listed here are intended for customer modification.

NOTE:

The format of a section in the configuration.json file is as follows: “SettingSection”:{      “SettingName1”: “SettingValue1”,      “SettingName2”: “SettingValue2” } Any values you change when configuring the solution should be the text value of the setting, for example SettingValue1 from above.  It is important to not delete any of the characters specific to the .json formatting such as any quotation, colon, comma or curly brace ({ or }) characters.

NOTE:

The values of the various settings described below are case sensitive and should be entered lower-case.

Help Button

The help button allows an end-user to send a help request to uPerform.  Due to the variety of possible UI5 application layouts, by default the help control renders as a “floating” button that you can position. The settings below are in the “HelpButton” section of the configuration.json file.

Setting	Description	Possible Values
Mode	Defines whether the help button floats “on top” of the UI5 application or is docked in the header area. The default value is “float” and can be used for any UI5-based application including Fiori Launchpad. “dock” should be used only with Fiori Launchpad scenarios. When “dock” is used the rest of the help button settings described in this section do not apply.	dock, float
Width	The width of the help button in pixels.	Any whole number
Height	The height of the help button in pixels	Any whole number
BorderRadius	Defines the radius as a percentage applied to the border of the help button. NOTE: The combination of Width, Height, and BorderRadius control the shape of the help button. Some examples: Circle (default): BorderRadius = 50%, Width = Height Rounded square: BorderRadius = 10%, Width = Height Rectangle: BorderRadius = 0, Height > Width	Any whole number
Direction	Controls the horizontal position of the help button. The button will be aligned on the selected edge of the UI5 application. left: Help button will display on left edge of the UI5 application. right: Help button will display on right edge of the UI5 application.	left, right
Position	Controls the vertical location of the help button as a percentage of the UI5 application height. Review your UI5 application layout and select a default position such that your users will notice the help button but does not interfere with other UI elements.	Any whole number 0 - 100
RememberLastPosition	The help button is draggable by the user. This setting controls whether the dragged position is retained in next browser session, or whether the help button displays at the default position. This setting only applies when the help button mode is set to float. true: Position of the help button is stored locally in browser’s local storage if available else in a cookie if available. false: Position of the help button is not stored locally.	true, false
DisableInOS	Hides the help button for specific device types. The help button is enabled by default for all supported device types. NOTE: Multiple values should be separated by a comma.	android, bb, ios, linux, mac, win, winphone

Help Panel

The help panel provides a container to display the help content returned by uPerform.  You may choose to display the help content panel directly within the UI5 application or in a separate browser window.  These settings define the default state of the panel; however, an individual user can modify the panel’s size and position at run time.  For some settings such as the default “mode,” analysis of your application’s behavior when resized is recommended.

The help panel has minimal user interface and consists of a title bar, a button to close the panel, a menu button to switch between display modes, and a container to display the help content.  The help content is the primary focus for the end user and it comes from and is controlled by the uPerform® system.

If the help panel is opened inside the UI5 application the user can switch between display modes via the Switch Mode menu button in the upper-right corner of the help panel title bar.

The settings below are in the “HelpPanel” section of the configuration.json file.

Setting	Description	Possible Values
Width	The width of the help panel as a percentage of the UI5 application width.  This setting affects the help panel in any mode – dock, float or popout.  The browser window dimensions defined in a uPerform® Server connection profile are not used by this CSH solution.	Any whole number between 1 and 100
Height	The height of the help panel as a percentage of the UI5 application height.  This setting affects the help panel in any mode float or popout mode.  In dock mode the panel height equals the UI5 application height.  The browser window dimensions defined in a uPerform® Server connection profile are not used by this CSH solution.	Any whole number between 1 and 100
Mode	Defines the default state of the help panel when user requests help. dock: The panel displays inside the UI5 application and the main UI5 application container is resized proportionately. float: The panel displays inside the UI5 application but as a non-modal floating element, meaning the user can interact with the main UI5 application while the panel floats on top.  The user can move the help panel within the bounds of the UI5 application.  This setting is recommended for those UI5 applications that do not resize well when the docked help panel renders. popout: The help content displays in a new browser window. If the help panel displays in dock or float mode the user can switch between modes.  Once the help panel is “popped out” it has no connection to the UI5 application and user cannot restore it back into the UI5 application.  The user can only close it and next time they request help, the panel will display based on this Mode setting value.	dock, float, popout
RememberLastPosition	In float mode, the help panel is draggable by the user.  This setting controls whether the dragged-to position is retained in next browser session, or whether the help panel displays at the default position.  This stored position is used only when the help panel is floating. true: Position of the help panel is stored locally in browser’s local storage if available, else in a cookie if available false: Position of the help panel  is not stored locally	true, false
RememberLastSize	The user can change the size of the help panel when it is in dock or float mode.  This setting controls whether the user defined size is retained in next browser session, or whether the help panel displays in the default size.  This stored size is used for all help panel display modes. true: Size of the help panel is stored locally in browser’s local storage if available, else in a cookie if available false: Size of the help panel  is not stored locally Regardless of this setting value, in a given browser session the user can change the current size of the help panel and that changed size will be respected by mode switches during the current browser session.  For example, suppose the default panel width is 30% of browser width.  The user then calls help and panel opens in docked mode.  The user adjusts the width of the panel to 50% by dragging the border edge, then selects the Switch Mode button “Float” menu item.  When the help panel switches to float mode, its width remains at 50%.	true, false

Installation

After configuring the CSH solution, perform the following steps to install or integrate this solution into the SAP UI5 application.  There are several integration scenarios that depend on whether it is single UI5 application, Fiori Launchpad, or an entire UI5 runtime, and also if it is on-premise or part of HANA Cloud Platform.

NOTE:

This section assumes knowledge of the various development environments (IDE) such as Eclipse, SAP Web IDE, or HANA Cloud Cockpit, available for use with SAP systems and UI5 applications.  Since different IDEs are available, this section provides general steps necessary to perform an action and may not define detailed steps that are part of SAP documentation or specific to one IDE.  If necessary refer to the relevant SAP documentation for your scenario or tool.

Fiori Launchpad on HANA Cloud Platform

This scenario applies the CSH solution to the Fiori Launchpad as an application of type “shell plug-in”; therefore, it is available to any Fiori application opened from the Launchpad.

NOTE:

If you allow users to access some Fiori applications directly without going through Fiori Launchpad, the CSH solution will have to be added to those Fiori applications separately from this method.  Refer to one of the non-Fiori sections below.

NOTE:

The steps below assume some knowledge of the HANA Cloud Platform Cockpit and the Fiori Launchpad Configuration Cockpit.  The exact steps may vary if you use another tool. If necessary, refer to the documentation of the tool you are using for more information.

1. In Hana Cloud Platform Cockpit, use the Import from file option to import the CSH solution .zip file as a HTML5 application with name “ancilecsh.”
2. Activate the ancilecsh application.
3. In the Fiori Launchpad Configuration Cockpit, add the ancilecsh application to your Fiori Launchpad with App Type field value of “Shell Plug-in.”
4. Assign the ancilecsh application to the Fiori Catalogs for which you want the CSH solution to apply.
5. Save the application.

Fiori Launchpad in Netweaver ABAP system

This scenario applies the CSH solution to the FioriLaunchpad.html file; therefore, it is available to any Fiori application (tile) opened from the Launchpad.

NOTE:

The steps below assume you are using Eclipse with the SAP UI5 add-ons installed. The specific steps may vary if you are using a different IDE.

NOTE:

FioriLaunchpad.html may be overwritten by SAP when the system is updated, so the changes below may need to be re-applied after an update to the Fiori Launchpad.

NOTE:

If you allow users to access individual Fiori applications directly without going through Fiori Launchpad, the CSH solution will have to be added to those Fiori applications separately from this method. Refer to one of the non-Fiori sections below.

1. Extract the ancile_ui5_csh-masterversion.zip file. This contains the CSH solution files.
2. In Eclipse, ensure the sapui5 repository is added from https://tools.hana.ondemand.com/xxxx where xxxx corresponds to your “version” of Eclipse such as “mars” or “luna.”
3. Create a new SAP UI5 Application Development project named “zancilecsh”.
4. From the extracted CSH solution files, copy the ancilecsh folder to the WebContent folder of the zancilecsh application.
5. Deploy the zancilecsh application as a “BSP Application” into an appropriate package in your ABAP system.
6. In the ABAP system transaction SE80, locate and edit the FioriLaunchpad.html file.
7. Locate the line "<script src='" + sUI5LibraryRootPath + "/sap/fiori/core-min-3.js' " + (isIE ? "defer" : "") + "></script>"; OR "<script src='" + oUi5ResourceRoots[""] + "sap/fiori/core-min-3.js' " + (isIE ? "defer" : "") + "></script>";
8. Choose one of the following options:

   If	Then
   The line of code exists	Replace the trailing “;” character with a “+” character. Add the following line, including the double quotation marks: "<script src='/sap/bc/ui5_ui5/sap/zancilecsh/ancilecsh /ancilecsh.js' " + (isIE ? "defer" : "") + "></script>";
   The line of code does not exist	Add the following line right before the closing "</head>" tag: "<script id="ancile-csh-ui5" type="text/javascript" src="/sap/bc/ui5_ui5/sap/zancilecsh/ancilecsh/ancilecsh.js"></script>"

9. Save changes to FioriLaunchpad.html.
10. Activate the modified FioriLaunchpad.html.

Netweaver ABAP-Based UI5 Application

This scenario deploys the CSH solution to the ABAP system where it can be integrated via reference into any UI5 application that runs from the ABAP system.

NOTE:

The steps below assume you are using Eclipse with the SAP UI5 add-ons installed.  The specific steps may vary if you are using a different IDE.

NOTE:

This scenario applies to a non-Fiori, UI5-based application running from an ABAP system.

1. Create a new UI5 application named “zancilecsh”.
2. Import the CSH solution .zip file into the “zancilecsh” application.
3. Deploy the “zancilecsh” as a “BSP Application” into the appropriate package in your ABAP system.
4. In the ABAP system locate the UI5 application for which you want to provide the CSH solution.
5. Edit the main index.html file of the UI5 application.
6. Add the following line before the closing tag in the index.html file, replacing {relative path} with the actual relative path in your ABAP system from the UI5 application’s index.html file to the ancilecsh folder created when you deployed the zancilecsh BSP application:     <script src="{relative_path}/ancilecsh/ancilecsh.js"></script>
7. Save changes to index.html.
8. If necessary based on your development environment, redeploy or activate the updated UI5 application.

Single Non-ABAP UI5 Application

In this scenario you will add the CSH solution to an individual UI5 application.  This is accomplished by adding a script reference to the CSH solution into the UI5 application source code.

NOTE:

This scenario applies to any single UI5 application that is not Fiori nor running from an ABAP system.

1. Extract the ancile_ui5_csh-masterversion.zip file. This contains the CSH solution files.
2. From the extracted CSH solution files, copy the ancilecsh folder to a location that the target UI5 application can reference at runtime, such as the “webapp” folder of the target UI5 application project. Note the location of the ancilecsh.js file after deployment.
3. Open the UI5 application source code using an IDE appropriate for your application scenario.
4. Add a reference to the CSH solution code to your UI5 application using one of the following methods.

   NOTE:

   Only modify one of the files listed below.  The recommended file to modify is index.html. If your UI5 application does not have an index.html file, you can add the CSH solution code reference to the component.js or controller.js files if necessary.

   UI5 source file	Modification
   index.html	Add the following line before the closing </head> tag.  Replace {path to ancilecsh folder} with the actual path: <script src='/{path to ancilecsh folder}/ancilecsh.js'></script>;
   component.js	Add the following line at the end of the “init: function()” : $.sap.require(this.getManifestEntry("sap.app").id + ".ancilecsh.ancilecsh");
   controller.js	Locate the “controller” JavaScript file associated with the initial view of the UI5 application.  Add the following line at the end of the “onInit:” function. If that function does not exist, create it. $.sap.require(this.getOwnerComponent().getManifestEntry("sap.app").id + ".ancilecsh.ancilecsh");

5. Save the modified file.
6. Take any steps necessary to deploy the updated UI5 application.

Entire UI5 Runtime

In this scenario you will add the CSH solution to the UI5 runtime environment.  Any UI5 applications using this instance of the runtime will run the CSH solution. This is accomplished by adding a script reference to the CSH solution into the UI5 runtime source code.

1. Deploy the CSH solution code to the “resource” folder of the UI5 runtime. Note the location of the ancilecsh.js file after deployment.
2. Open the UI5 runtime source code using an IDE appropriate for your scenario.
3. Edit the sap-ui-core.js file.
4. Add the following line to the end of the file: $.sap.require("ancilecsh.ancilecsh");
5. Save the modified file.

Tagging Content with Context

When your authors create new content files for SAP UI5 they must be “tagged” in order to become part of the CSH solution. Tagging is the process of assigning some information to the .udc file that associates it with a given part of the SAP UI5 application. Tagging can be done automatically during recording or manually. Auto-tagging requires no additional effort by your authors. However auto-tagging works only after the CSH solution is implemented and the CaptureEngine configuration (.cea) file is applied to authors’ computers. Manual tagging is applicable when you have any of the following scenarios related to Fiori or UI5 applications:

• uPerform documents created before implementing the CSH solution
• Managed documents, web links, or uPerform courses that you want the help call to return as results
• You are unable to use Microsoft Internet Explorer when recording the Fiori or UI5 applications after implementing the CSH solution

Configuring CaptureEngine for Auto-Tagging Context

The CaptureEngine is the uPerform application component that captures the author’s actions while recording a .udc file.  The CaptureEngine must be configured to enable it to collect the SAP UI5 context while recording.

NOTE:

The CaptureEngine collects context automatically only when recording SAP UI5 in Microsoft Internet Explorer.

We recommend performing the steps below on a single computer first to confirm proper operation before distributing the configuration update to all of your authors who will record SAP UI5. Once you decide to distribute the CaptureEngine configuration update to your authors, they will only need to do Steps 1 below.

1. Install uPerform which includes CaptureEngine.

   NOTE:

   uPerform version 5.40.5 is required.

   NOTE:

   CaptureEngine 6.40.1 is required and must be downloaded and deployed manually.

2. Ensure the CSH solution is implemented in your UI5 application and the Help button is visible.
3. As a test, start a new recording. As you record, context identifiers should be captured automatically.
4. Record several steps on one or more screens in your SAP UI5 application.
5. Stop recording.
6. In the Editor, double-click the relevant step to display Step Properties.
7. Select the Context Information panel.
8. The Primary: and Secondary: fields should contain values. These are the captured context identifiers for your recorded steps.

Manually Tagging Content

Content can be tagged with context values manually at any time. You will navigate through the UI5 application using the flow defined in a uPerform content file, and collect the context value for each “screen” in that flow. Refer to Recording A Document And Making It Available For Context-Sensitive Help. You must implement the CSH solution into your Fiori or UI5 application before collecting context values.

Continue to the next article Creating A Template.