Skip to main content

Pentaho+ documentation has moved!

The new product documentation portal is here. Check it out now at docs.hitachivantara.com

 

Hitachi Vantara Lumada and Pentaho Documentation

Moving to Visualization API 3.0 in Analyzer

Parent article

Pentaho Analyzer displays visualizations that are based on the Pentaho Visualization API.

Pentaho 8.3 and later ship with Visualization API 3.0 along with the previous 2.0 version. Analyzer supports visualizations of both API versions, allowing you to convert any custom visualizations made with Visualization API 2.0 to Visualization API 3.0 at your own pace. All stock visualizations, with the exception of the Geo Map, are available in Visualization API 3.0.

  • New Pentaho installations are configured to use the stock visualizations for Visualization API 3.0
  • Upgrade installations are configured to keep using the previous Visualization API 2.0 stock visualizations.

You can choose which stock visualizations Analyzer uses by configuring an Analyzer setting as described in Changing the Visualization API version in Analyzer. This setting does not affect Analyzer reports that use a custom (non-stock) visualization. Your custom visualizations will continue to use their related API version.

Once you move to Visualization API 3.0 for stock visualizations, viewing a previously saved Analyzer report with a visualization from Visualization API 2.0 will change the way the visualization is displayed but not the saved report file. However, if you save it, it will be irreversibly upgraded to use the stock visualizations of Visualization API 3.0. If you later decide to switch back to using the stock visualizations of the previous Visualization API 2.0 in Analyzer, the visualization of your report will not be available. The report will display in the Pivot table view.

When you choose to try the stock visualizations of Visualization API 3.0:

  • As a precaution, create a backup of your existing Analyzer reports.
  • Ensure you are satisfied with the new experience by testing all of your existing Analyzer reports before saving.

Difference between Visualization API 2.0 and 3.0 in Analyzer

The stock visualizations for Visualization API 3.0 are not completely identical to the corresponding visualizations in Visualization API 2.0. Consider the differences listed in each of these categories.

  • Usability and style

    • Visualizations scroll horizontally and vertically when too many axis categories exist instead of shrinking to available space.
    • Selection is either enabled or disabled, depending on whether gems are present in the Pivot “Column” gem bar. An intermediate selection state no longer exists where partial selections are possible when one gem was in the Pivot “Column” gem bar.
    • General styling of visualizations now aligns across the Pentaho platform.
    • Standard color palettes now align across the Pentaho platform.
  • Cautions

    • Moving to 3.0, custom visualizations must be manually converted.
    • Visualization configuration in 3.0 is a different process. Existing Analyzer visualization configurations must be migrated. See Migrating visualization settings in Analyzer.
    • Custom translations for properties of stock visualizations may no longer work in 3.0.
  • Printing

    • Printing of scrolled charts shrinks to fit while preserving their aspect-ratio.
    • Printing only reflects custom configurations that are located in the Global Configuration File.

Changing the Visualization API version in Analyzer

Perform the following steps to change the API version of your stock visualizations:

Procedure

  1. Go to the Analyzer plugin folder, located at pentaho-server/pentaho-solutions/system/analyzer and open the settings.xml file.

  2. Find the <viz-api-version> setting and change its value according to the following desired API version:

    • To use Visualization API 2.0, set <viz-api-version> to 2.0, as shown below:
      <viz-api-version>2.0</viz-api-version>
    • To use Visualization API 3.0, set <viz-api-version> to 3.0, as shown below:
      <viz-api-version>3.0</viz-api-version>
  3. Save the file and restart the Pentaho Server.

Migrating visualization settings in Analyzer

Visualizations created in Visualization API 2.0 can be configured in Analyzer. You will need to update the analyzer.properties file located in the pentaho-server/pentaho-solutions/system/analyzer directory.

Visualizations created in Visualization API 3.0 are configured using the platform-wide JavaScript configuration system.

You must migrate the following Analyzer visualization settings in Visualizatio API 2.0 to work with Visualization API 3.0:

  • General visualization property example

    The following example changes the default value of the Line width property in Line chart visualizations.

    • Visualization API 2.0

      in analyzer.properties,

      viz.ccc_line.args.lineWidth=1
    • Visualization API 3.0

      in a platform configuration file,

      ddefine(function() {
         return [
           {
             select: {
               application: "pentaho/analyzer",
               module: "pentaho/visual/models/Line"
             },
             apply: {
               props: {
                 "lineWidth": {defaultValue: 1}
               }
             }
           }
         ];
       });
  • Maximum values property example

    The following example changes the maximum number of results possible in the Bar chart visualizations.

    • Visualization API 2.0

      in analyzer.properties,

      viz.ccc_bar.maxValues=250,500,1000,5000
    • Visualization API 3.0

      in a platform configuration file,

      define(function() {
         return [
           {
             select: {
               application: "pentaho/analyzer",
               module: "pentaho/visual/models/BarHorizontal",
               annotation: "pentaho/analyzer/visual/Options"
             },
             apply: {
               maxValues: [250, 500, 1000, 5000]
             }
           }
         ];
       });
  • Chart series colors property example

    The following example changes the default discrete color palette.

    • Visualization API 2.0

      in analyzer.properties,

      chart.series.colors=#0045a1,#5f9e00,#ffc20f,#ff6600,#3c008f
      
    • Visualization API 3.0

      in a platform configuration file,

      define(function() {
         return [
           {
             select: {
               application: "pentaho/analyzer",
               module: "pentaho/visual/color/palettes/nominalPrimary"
             },
             apply: {
               colors: [
                 "#0045a1","#5f9e00","#ffc20f","#ff6600","#3c008f"
               ]
             }
           }
         ];
       });

To perform this migration, you need to know the API version correspondence between visualization identifiers and property values.

Differences between Visualization API 2.0 and 3.0

The following tables map the differences between the visualization identifiers and property values from Visualization API 2.0 and Visualization API 3.0.

Visualization identifiers in Visualization API 2.0 and 3.0

The following table contains differences between the visualization identifiers of Visualization API 2.0 as compared to the identifiers in Visualization API 3.0:

Visualization ID in API 2.0Visualization ID in API 3.0Description
ccc_areapentaho/visual/models/AreaStackedArea Stacked
ccc_linepentaho/visual/models/LineLine
ccc_barpentaho/visual/models/BarColumn
ccc_barstackedpentaho/visual/models/BarStackedColumn Stacked
ccc_barnormalizedpentaho/visual/models/BarNormalizedColumn Stacked 100%
ccc_horzbarpentaho/visual/models/BarHorizontalBar
ccc_horzbarstackedpentaho/visual/models/BarStackedHorizontalBar Stacked
ccc_horzbarnormalizedpentaho/visual/models/BarNormalizedHorizontalBar Stacked 100%
ccc_barlinepentaho/visual/models/BarLineColumn/Line Combo
ccc_scatterpentaho/visual/models/BubbleX/Y Scatter/Bubble
ccc_heatgridpentaho/visual/models/HeatGridHeat-Grid
ccc_piepentaho/visual/models/PiePie
ccc_sunburstpentaho/visual/models/SunburstSunburst

Visualization property values in Visualization API 2.0 and 3.0

The following table contains differences between the visualization property values of Visualization API 2.0 as compared to the property avlues in Visualization API 3.0:

Property nameExample value in API 2.0Example value in API 3.0
labelsOptioninside_end"insideEnd"
inside_base"insideBase"
outside_end"outsideEnd"
patternryg_3"ryg-3"
ryg_5"ryg-5"
blue_3"blue-3"
blue_5"blue-5"
lineWidthIn both 2.0 and 3.0, the number in the properties file passes verbatim to a JSON number value.
trendLineWidth
emptySlicesHiddenIn both 2.0 and 3.0, the value of true or false in the properties file passes verbatim to a JSON boolean value.
reverseColors
colorSetIn both 2.0 and 3.0, textual values in the properties file are wrapped in quotation marks to form a JSON string value. For example, circle becomes "circle".
lineLabelsOption
shape
sliceOrder
trendName
trendType