Oracle® Retail Predictive Application Server Cloud Service Implementation Guide Release 23.1.101.0 F76553-01 |
|
Previous |
Next |
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.
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.
The help topics for the dashboard are visible on the right side panel, as shown in Figure 2-2.
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.
Here the Step, Tabs, and View are visible.
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.
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.
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" : [] }
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. |
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. |
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" } ] } }
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.
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.
Select Manage JSON files from the list of available tasks and click Next, as shown in Figure 2-6.
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.
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. |