Generating Narrative Charts

How to: Configure the URL to the WebFOCUS Narrative Charts Server in the WebFOCUS Administration Console

In order to configure WebFOCUS to generate narrative charts, you must install the WebFOCUS Narrative Charts Server and, optionally, configure the URL to the WebFOCUS Narrative Charts Server in the WebFOCUS Administration Console.

Note: If you do not configure the URL to the WebFOCUS Narrative Charts Server in the WebFOCUS Administration Console, the Narrative charts button will not be activated in InfoAssist+. If you do configure the URL in the WebFOCUS Administration Console, you will find the Narrative button on the Format menu under Features when you create an HTML5 (FORMAT JSCHART) bar, line, area, or pie chart.

The WebFOCUS Narrative Charts Server is a separately licensed product that can be installed on Windows or Linux. Once you have licensed this feature, you can install the server using the instructions in the WebFOCUS Narrative Charts Installation and Configuration manual.

In order generate WebFOCUS narrative charts, you must either include the narrative text in your chart procedure or StyleSheet, configure the URL to the WebFOCUS Narrative Charts Server in the WebFOCUS Administration Console, or include the URL in the narrative chart properties in your chart procedure or StyleSheet. The order of precedence is:

1. The URL configured in the WebFOCUS Administration Console. If neither the content nor the url property is specified in your procedure or StyleSheet, the URL configured in the WebFOCUS Administration Console will be used.
2. A URL specified in the procedure or StyleSheet. If your procedure or the StyleSheet included in your procedure has a url property pointing to the WebFOCUS Narrative Charts Server, and the content property is omitted or set to undefined, the last URL found when parsing the procedure or StyleSheet will be used.
3. Your own content. If you supply narrative text in the content property of your procedure or StyleSheet, it will be used.

Failed to retrieve narrative text

The following chart types are supported for narrative text generation when creating an HTML5 (FORMAT JSCHART) chart.

• Bar. Horizontal and vertical bars are supported, including stacked bars, and percent bars.
• Line. Horizontal and vertical lines are supported, including stacked lines and absolute lines.

  Note: Line charts require an ordered axis, such as date.

• Area. Horizontal and vertical area charts are supported, including stacked lines and absolute lines.

  Note: Area charts require an ordered axis, such as date.

• Pie. Both pie and ring pie charts are supported, including percent pies.

Narrative chart requests can include up to two dimensions as long as they are concatenated and if there is only one measure, or up to two measures if there is only one dimension.

Note: For JSON formatting, object names, property names, and string property values should be enclosed in double quotation marks.

For an introduction to JSON syntax for WebFOCUS HTML5 charts and the supported methods for specifying colors, see the Creating HTML5 Charts With WebFOCUS Language manual.

The following properties can be used to add a narrative to a chart, format the narrative, and control features of the generated narrative.

*GRAPH_JS
"narrativeText": 
   {
     "enabled": boolean,
     "hideChart": boolean,  
     "position": "string", 
     "maxSize": "string",  
     "url": "string",
     "content": "string",  
     "label": {
             "font": "string",
             "color": "string",
             "align": "string"   
            },
     "backgroundColor": "string",
     "border": {
              "width": number,
              "color": "string",
              "dash": "string"  
             },
     "dockButton": {  
                  "enabled": boolean,
                  "animationDelay": number,  
                  "size": number,  
                  "color": "string",
                  "hoverColor": "string"
                },
           

 "textGenerationAPI": 
            { 
              "inputChart": 
               {
                "mainDimensionOrdered": boolean,
                "multiSeriesType": "string",
                "disableInterpolation": boolean,
                "singularExceptions": ["string", "string"...],
                "pluralExceptions": ["string", "string"...],
               },
               "outputText": {
                            "levelOfDetail": number,
                            "lang": "string",
                            "useBulletPoints": boolean
                            },
              "measures":   [
                            {
                             "defaultValue": "string", 
                             "meaningOfUp": "string", 
                             "unit": "string"
                            },
                            {
                             "defaultValue": "string", 
                             "meaningOfUp": "string",    
                             "unit": "string"
                            }   
                           ]  
            }
   }
*END       

where:

"narrativeText":

Starts the narrative chart properties section of a *GRAPH_JS block in the StyleSheet.

"enabled": boolean

Enables or disables the narrative text generation. Valid values are true, which generates a narrative on the chart output, and false, which does not generate a narrative on the chart output. The default value is false.

"hideChart": boolean

Controls whether the chart displays along with the narrative. Valid values are true, which displays only the narrative, not the chart, and false, which displays both the narrative and the chart. The default value is false.

"position": "string"

Defines the position of the narrative text in relation to the chart. Valid values are "top", "bottom", "left", or "right". The default value is "top".

"maxSize": "string"

Is a string that includes a percent symbol (%) that defines the maximum percent of the chart draw area that will be dedicated to the narrative text. This value takes position into account. If position is "left" or "right", this defines the maximum width of the text box for the narrative. If position is "top" or "bottom", this value defines the maximum height of the text box for the narrative. The default value is "20%".

"url": "string"

Identifies the URL to the text generation server. Optional if the URL is configured in the WebFOCUS Administration Console. Omit both the property name and value if you want to supply content using the content property.

"content": "string"

Should be undefined, if the text will be generated by the WebFOCUS Charts Narrative Server. If the url property is missing or commented out and the URL is not configured in the WebFOCUS Administration Console, provide a string containing the text of the narrative you want to display. Simple HTML tags such as < br > and < ol > can be used. An amper variable can be used if the Narrative Chart properties are defined in the chart request and not in an external WebFOCUS StyleSheet The default value is undefined.

Note: All of the content string must be entered as a single line in the procedure. Any breaks that you want to appear on the narrative output should be entered as HTML tags.

"label":

These properties define the format and alignment of the generated narrative text.

"font": "string"

Is a string that defines the font of the narrative text. The default value is "11pt Sans-Serif".

"color": "string"

Is a string that defines the color of the narrative text using a color name, an RGB color string, or a hex color string. The default value is "black".

"align": "string"

Is a string that defines the alignment of the narrative text within the text box. Valid values are "left", "middle", "center", and "right". The default value is "left".

"backgroundColor": "string"

Is a string that defines the background color of the text using a color name, an RGB color string, or a hex color string. The default value is undefined.

"border":

These properties define the border of the text box.

"width": number

Is a number that defines the width in pixels of the border around the narrative text box. The value zero (0) does not draw a border around the text box. The default value is 0.

"color": "string"

Is a string that defines the color of the border around the text box using a color name, an RGB color string, or a hex color string. The default color is "black".

"dash": "string"

Is a string that defines the dash style of the border around the text box. The default value is "" (a solid line). Use a string of numbers that defines the width of a dash in pixels followed by the width of the gap between dashes in pixels (for example, dash: "1 1" draws a dotted line).

"dockButton":

These properties define a button that can be drawn pointing to the chart that, when clicked, expands the narrative text box as much as required, up to the size of the entire chart frame. After expansion, the button becomes a collapse button that collapses the text box to its original size.

"enabled": boolean

Controls whether a dock button will be drawn. Valid values are true, which draws a dock button, and false, which does not draw a dock button. The default value is false.

"animationDelay": number

Is a number that defines the length of time (in ms) to animate the sliding transition when expanding and collapsing the text box. The default value is 300.

"size": number

Is a number that defines the diameter of the dock button in pixels. The default value is undefined.

"color": "string"

Is a string that defines the color of the dock button using a color name, an RGB color string, or a hex color string. The default value is "rgb(50, 50, 50)".

"hoverColor": "string"

Is a string that defines the color of the dock button when the mouse hovers over it. the default value is "black".

"textGenerationAPI":

These properties define the parameters sent to the WebFOCUS Narrative Charts Server to be used in generating the narrative text.

"inputChart":

These properties define aspects of the data being sent to the WebFOCUS Narrative Chart Server.

• "mainDimensionOrdered": boolean

  Specifies whether the dimension represents a range of values or a categorical list. To have the type of ordering automatically detected, omit this property. Valid values are:

  • true, which indicates that the dimension values can be expressed as a range of values. This type of ordering is appropriate for time, date, or numeric dimensions. The generated text will describe the dimension values as a from-to range of values. This is the default value for bar, line, and area charts.
  • false, which indicates that the dimension values do not represent a range. This type of ordering is appropriate for alphanumeric dimensions. The generated text will express the dimension values as a categorical list. This is the default value for pie charts.
• "multiSeriesType": "string"

  Indicates if the measures are related to each other. Valid values are:

  • "UNRELATED", which means the measures are not related to each other. This is the default value.
  • "VALUE_VS_REFERENCE", which means that the measures are related. Value refers to the first measure, say, Actual Sales, and the second measure is the Reference (that is, the target or objective). This option requires a date axis, and the format must be YYMD.
• "disableInterpolation": boolean

  Determines whether missing values will be approximated or replaced with a default value. Valid values are:

  • true, which uses a default value for missing values. The default value is specified in the defaultValue property for each measure. This is the default option.
  • false, which computes an approximate value when a data value is missing.
• "singularExceptions": ["string", "string" ...]

  Is an array of strings that identify nouns that seem plural but should be treated as singular. Examples are the nouns mathematics, physics, and ethics. The default value is not to have singular exceptions.

• "pluralExceptions": ["string", "string" ...]

  Is an array of strings that identify nouns that seem singular but should be treated as plural. Examples are the nouns pliers, tongs, and tweezers. The default value is not to have plural exceptions.

"outputText":

These properties control some of the aspects of the returned narrative text.

• "levelOfDetail": number

  Is an integer from 1 to 7 that controls how much text is generated, with 7 generating the most detailed text and 1 generating the simplest text. The default value is 7.

• "lang": "string"

  Defines the language for the generated text. At this time, the supported values are "en" (English) or "fr" (French). You can be licensed to use either English or French, but not both. The default value is "en".

• "useBulletPoints": boolean

  Defines whether key points in the narrative should be displayed as bullets or paragraphs. Valid values are true, which displays key points as bullets, or false, which uses paragraphs. The default value is false.

"measures":

Is an array that defines the properties of up to two measures.

Note: If your chart request has only one measure, do not include properties for a second measure or the chart will not draw.

• "defaultValue": "string"

  Is a string that specifies default value to be used for missing data values if the disableInterpolation property is set to true. The default value is "0".

• "meaningOfUp": "string"

  Identifies whether high values represent positive information (for example, sales or profit) or negative information (for example, expenses). Valid values are:

  • "GOOD", which means higher values represent positive information. This is the default value.
  • "BAD", which means higher values represent negative information.
• "unit": "string"

  Defines the units to be applied to measure values. Valid values are:

  • "$". Should be used for currency values.
  • "%". When "%" is used, an automatic scale is applied to the data (.1 will be displayed as 10%).
  • "". This is the default value.

Note:

• For all examples, the application containing the Master File must be on the APP PATH or be included in the GRAPH FILE command. For example:

  GRAPH FILE app1/wf_retail_lite

• The text generation server purposely creates varying narratives, even for the same chart output. Therefore, the narrative output you get if you run the following examples may differ from the narrative output displayed here.