2 In-Context Help

This chapter describes how to configure In-Context Help for solutions based on RPASCE.

In-Context Help is a resource to access relevant help topics, in the format of HTML and video, within the application. At present, it focuses on help topics related to the dashboard and the workspace. The naming convention is <app-name>HelpConfig.json.

Navigating to Help Topics on RPASCE

You can navigate to the help topics in the following ways:

Dashboard

The help topics for the dashboard are added to the following two levels:

All: The generic topics related to MFP or A&IP are added to this level.
Report: This consists of topics related to dashboards such as the effective usage, how to analyze the metrics, and so on.

Figure 2-1 shows the view of a dashboard.

Figure 2-1 Dashboard Window

Description of ''Figure 2-1 Dashboard Window''

The help topics for the dashboard are visible on the right side panel, as shown in Figure 2-2.

Figure 2-2 Dashboard Help Topics

Description of ''Figure 2-2 Dashboard Help Topics''

Workspace

The workspace contains the actual content related to MFP or A&IP. Here the topics are aligned with respect to the different levels of the Taskflow.

Figure 2-3 illustrates the workspace for the product MFPRCS.

Figure 2-3 MFPRCS Workspace

Description of ''Figure 2-3 MFPRCS Workspace''

Here the Step, Tabs, and View are visible.

Figure 2-4 MFPRCS Workspace with Help

Description of ''Figure 2-4 MFPRCS Workspace with Help''

Creating the Contextual Help Configuration File

The specifications related to Contextual Help for the RPASCE dashboard and workspace are implemented by creating a configuration file. This file is created outside of the RPASCE Configuration Tools and is deployed in the RPASCE Client application. The contents of this configuration file are used by the RPASCE Client to determine how to organize and display the help topics in the dashboard and the workspace.

Although a Contextual help configuration file can be created from scratch, in most cases, it is simpler to modify an existing version of the file to incorporate any desired changes.

Using JSON in the Contextual Help Configuration File

The contents of the Contextual Help Configuration file are formatted as a JSON (JavaScript Object Notation) object. JSON is a common flexible information encoding notation used frequently in cloud applications; it is more compact and, when properly formatted, more readable than the XML format. (Importantly, it is also not subject to some security concerns that are present when using XML for information encoding.)

JSON is a simple and straightforward format; information about the specifics of the format is readily available online.

Structure of Contextual Help Configuration File

The configuration file is divided into three levels: ALL, REPORTS, and WORKBOOKS. All three levels are of type JSON Object. The ALL level is the generic level. REPORTS and WORKBOOKS are children of level ALL.

Table 2-1 Configuration File Levels

Level	Description
ALL	Describes the generic help topics related to the RPASCE solution in use.
REPORTS	Contains the help topics related to the dashboard.
WORKBOOKS	Contains the help topics for the workbook and its sub-categories, such as Task, Step, Tab, and View.

The generic JSON structure for any solution is as follows:

    "helpTopics" : []    "reports" : {"helpTopics" : [] }    "workbooks" : {"helpTopics" : [] }

Help Topic Building Block

The help topics object as a whole is a JSON array of collection of attributes. This help topics object is the building block for all the different levels.

The following JSON snippet explains the generic helpTopics object structure:

"helpTopics" : [{
"name" : "Help Topic 1",
    "description" : "Description 1",
    "url" : "URL 1",
    "type" : "Type 1",
    "imageSrc" : "Image 1",
    "color" : "Color 1" 
},{ 
    "name" : "Help Topic 2",
    "description" : "Description 2",
    "url" : "URL 2",
    "type" : "Type 2",
    "imageSrc" : "Image 2",
    "color" : "Color 2" 
}]

Table 2-2 list the help topic properties.

Table 2-2 Help Topic Properties

Property	Value Type	Description
Name	JSON String	The name of the topic.
Description	JSON String	A short description of the topic.
URL	JSON String	The URL link to the help topic.
Type	JSON String	The type of the resource. Values are: document, image. or video.
ImageSrc	JSON String	The path to the image file to be displayed in the Help topic card, for example, an icon representing a video or an illustrative screenshot.
Color	JSON String	The color in which the help topic tile should be visible. Color is displayed at the top of the Help topic card. It is typically used to visually distinguish between help formats (document or video), but may be used for a variety of purposes. Values are: lightblue, red, lightgreen, purple, blue, grey, orange, turquoise, green.

Key Naming Convention

The naming convention of the key depends upon the level or sub-level of each element. Here is an example of the naming conventions at different levels.

Consider the solution in use is mfprcs.

Table 2-3 MFPRCS Key Naming Example

Level/Sub-Level	Key Example	Description
All	NA	No need of the key as help topics are added to the root of the JSON.
Reports	reports
Reports > Dashboard	reports.dashboard.id	The key must match the name provided for reports in the Taskflow_MultiSolution.xml file.
Workbooks	workbooks
Activity > Task	mfprcs.Activity1.Task1	The task name must match the entry provided in Taskflow_MultiSolution.xml file for the specific task.
Activity > Task > Step	mfprcs.Activity1.Task1.Step1	The step name must match the entry provided in Taskflow_MultiSolution.xml file for the specific step.
Activity > Task > Step > Tab	mfprcs.Activity1.Task1.Step1.Tab1	The tab name must match the entry provided in Taskflow_MultiSolution.xml file for the specific tab.
Activity > Task > Step > Tab > View	MT_TB01_WS01	The view name must match the entry provided in Taskflow_MultiSolution.xml file for the specific view. The view key name is unique, as it can be added anywhere under Task, Step, or Tab from the solution.

JSON Structure of Contextual Help Configuration File

Here is an example of JSON object containing all the three levels and the help topics related to each of them. The maxTopics in the following snippet defines how many topics can be visible on RPASCE. This value must be increased if you want to show more help topics at a given level than the value of maxTopics. If, for a specific level, there are fewer than maxTopics topics, it fetches the remaining topics from its parent. In the following snippet the maxTopics for workbooks is set to 2 and overrides the maxTopics for the root, which is set to 3 for the workbooks level. Also, since no maxTopics is set for reports, the maximum topics for this level is capped to 3, which is fetched from the root level.

{
  "maxTopics" : "3.0",
  "helpTopics" : [ {
    "name" : "MFP Cloud Service Introduction",
    "description" : "Learn the steps for defining the strategic financial targets and creating plans that reconcile to the stated targets.",
    "url" : "http://docs.oracle.com/cd/E75764_01/merchfinplan/pdf/cloud/161/html/retail_implementer_guide/output/introduction.htm#introduction",
    "type" : "document",
    "imageSrc" : "",
    "color" : "turquoise"
  } ],
  "reports" : {
    "helpTopics" : [ ],
    "reports.dashboards.id" : {
      "helpTopics" : [ {
        "name" : "Using the dashboard",
        "description" : "Manipulate the dashboard in order to effectively analyze plan matrics",
        "url" : "http://docs.oracle.com/cd/E75764_01/merchfinplan/pdf/cloud/161/html/retail_implementer_guide/output/dashboard.htm#dashboard",
        "type" : "document",
        "imageSrc" : "",
        "color" : "turquoise"
      } ]
    }
  },
  "workbooks" : {
    "maxTopics" : "2.0",
    "helpTopics" : [ ],
    "mfprcs.Activity1.Task1" : {
      "helpTopics" : [ {
        "name" : "Overview of Merch Plan Targets",
        "description" : "Learn about the steps associated with creating and monitoring targets",
        "url" : "http://docs.oracle.com/cd/E75764_01/merchfinplan/pdf/cloud/161/html/retail_implementer_guide/output/CreateMerchPlanTargets.htm#create_merch_plan_targets_task",
        "type" : "document",
        "imageSrc" : "",
        "color" : "turquoise"
      } ]
   }
}

Editing the Contextual Help Configuration File

Help topics can be edited or added directly under the levels ALL and REPORTS. For level WORKBOOKS, the implementer can add or edit under Task or can add or edit under a specific sub-level (Step, Tab, or View).

The following examples indicate where the implementer can add help topics at different levels.

Adding or editing the help topic for level ALL.

The implementer can add the help topic object directly under the root of the JSON under the property helpTopics. For editing, the implementer must search the name of the help topic in JSON and edit any of the required properties.
Adding or editing the help topic for level REPORTS.

Here the implementer must add the help topic under the reports object of the JSON. The implementer must search for the key reports and then add the help topic under the attribute helpTopics. Similarly, any particular help topic can be edited by searching the name of the help topic.
Adding or editing the help topic for sub-level Step under level WORKBOOKS.

To add a topic under sub-level Step, the implementer must search for the Step key and add the help topic. For editing, the implementer must search for a particular help topic and edit any of the properties as required.
Adding or editing the help topic for sub-level View under level WORKBOOKS.

To add a topic under sub-level View, the implementer must search for the View key and add the help topic. For editing, the implementer must search for a particular help topic and edit any of the properties as required.

Retrieve/Update InContext help JSON file:

The user can update or retrieve the help JSON file through an OAT (Online Admin Tools) task and can easily update the existing JSON file or retrieve it. This provides the flexibility to view the list of available help resources and modify them according to the requirement.

Following are the steps to submit the OAT task.

Open Submit a New Admin Task under Online Admin Tools.
Select Patch Application Task under task group and click Next, as shown in Figure 2-5.

Figure 2-5 List of Task Groups

Description of ''Figure 2-5 List of Task Groups''
Select Manage JSON files from the list of available tasks and click Next, as shown in Figure 2-6.

Figure 2-6 List of Tasks Under Patch Application Task Group

Description of ''Figure 2-6 List of Tasks Under Patch Application Task Group''
Now the user can provide a task label and select the type of operation to be performed.
- Retrieve JSON files to Object Storage: This operation performs the task of fetching the help JSON file from the RPASCE application. When this task is run, the help JSON file (with other JSON files) is bundled as a zip with label as <app_name>_json.zip and is placed in object storage under <SubNamespace>/planning/outgoing. The help JSON file is also prefixed with the app name as <app_name>HelpConfig.json
  
  Example: mfprcsHelpConfig.json
  
  Refer to Chapter 3, "Uploading and Downloading Files" for more details about downloading and uploading files to Object Storage.
- Update JSON files from Object Storage: The user can update the help JSON file as per their requirements. Once updated, the file name must be prefixed with the app name as <app_name>HelpConfig.json. Then, this JSON file must be bundled as <app_name>_json.zip and placed in the <SubNamespace>/planning/incoming/config directory.
  
  When the Update JSON files from Object Storage operation is performed on the RPASCE UI, it fetches the zip bundle from the Object Storage location <SubNamespace>/planning/incoming/config and updates the application with the new changes from the help JSON file. The user must re-login to the application to see the changes.
  
  Refer to Chapter 3, "Uploading and Downloading Files" for more details about downloading and uploading files to Object Storage.

Figure 2-7 Options to Fetch or Update the JSON Files

Description of ''Figure 2-7 Options to Fetch or Update the JSON Files''

Note:

If the user updates the URLs for the help topics in the help JSON file, these URLs must be allowed so that the links are accessible from the RPASCE UI. To allow the URLs, the user must navigate to System Configuration > Config Properties > Images and append the URL host in Valid Image URL Hosts text box.

Figure 2-8 Location to Allow List of the URLs

Description of ''Figure 2-8 Location to Allow List of the URLs''