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.