Skip to main content
Version Pentaho
Hitachi Vantara Lumada and Pentaho Documentation

Report APIs

  1. Last updated
  2. Save as PDF

Overview

Details methods for api.report class.

api.report Class

Report definition for api class. Contains all report related API calls.

Methods

The following methods are applicable:

addLayoutField (gembarId formula gembarOrdinal)

Adds a single gem to the gembar via its formula. The gembarOrdinal allows one to set the location of the inserted gem.

Parameters:

  • gembarId (String)

    This is the id of the gembar. It depends on the visualization's type. For example, PIVOT allows values such as "rows", "columns", "measures".

  • formula (String)

    This is the String representation of the formula to insert as a gem.

  • gembarOrdinal (Number)

    This is the index at which to insert the gem. A value of -1 appends to the end of the list.

Example:

var gembarId = "rows";
var formula = "[Markets].[City]";
var gembarOrdinal = 1;
api.report.addLayoutField( gembarId, formula, gembarOrdinal );

buildCellActionContext (td)

Returns the context on a specific TD cell. The context will depend on the type of cell clicked. We only support providing context on member, measure, and 'data' cells. Cells are passed as parameters to listeners bound in event calls such as registerTableClickListener, registerTableContextMenuListener, etc., which can be used as the TD parameter for this endpoint.

Parameters:

  • td (Object)

    This is the HTML DOM object defining the TD cell of a table in a report.

Returns:

  • This is the JSON object containing specific TD cell context.

Example:

var ctx =api.report.buildCellActionContext(td);

ReturnValue:

{
  "[Measures].[MeasuresLevel]":"[Measures].[Sales]",
  "[Markets].[Territory]":"[Markets].[APAC]"
}

buildFilterActionContext ( )

Returns the resolved filter context. 'Resolved' means that filters, such as the 'Last 30 Days' filter, will actually return the specified number of members, in this case '30 days', as opposed to the filter definition.

Returns:

  • This is the JSON object containing the filter context.

Example:

var filterCtx =api.report.buildFilterActionContext();

ReturnValue:

{
  "[Markets].[Territory]":{
    "EQUAL":["[Markets].[APAC]"]
  }
}

getChartOption (name) String

Returns the value of the chart option by name.

Parameters:

  • name (String)

    Name of chart option. Supported values include:

    • legendPosition
    • showLegend
    • autoRange
    • valueAxisLowerLimit
    • valueAxisUpperLimit
    • displayUnits
    • autoRangeSecondary
    • valueAxisLowerLimitSecondary
    • valueAxisUpperLimitSecondary
    • displayUnitsSecondary
    • maxValues
    • backgroundColor
    • labelColor
    • labelSize
    • backgroundFill
    • maxChartsPerRow
    • multiChartRangeScope
    • emptyCellMode
    • sizeByNegativesMode
    • backgroundColorEnd
    • labelStyle
    • legendBackgroundColor
    • legendSize
    • legendColor
    • legendStyle
    • labelFontFamily
    • legendFontFamily

Returns:

  • String

    This is the value of the chart option.

Example:

api.report.getChartOption('legendPosition');

getFieldOption (formula name) String

Returns the field option's value by name for a given formula. For additional information, see APIs for Get/Set Field Options.

Parameters:

  • formula (String)

    This is the string representation of the formula.

  • name (String)

    This is the name of field's option.

    • label
    • sortOrderEnum
    • showAggregate
    • showSum
    • showAverage
    • showMin
    • showMax
    • showSubtotal
    • formatShortcut
    • formatCategory
    • formatScale
    • formatExpression
    • currencySymbol

Returns:

  • String

    This is the option's value.

Example:

api.report.getFieldOption("[Markets].[Territory]", "showSubtotal");

getFilters ( )

Returns all non-numeric filters on the report. For additional information, see Analyzer Filters.

Returns:

  • JSON filters

         This is a JSON object containing all non-numeric filters.

Example:

 api.report.getFilters();

Return Value:

{"filters": {"[Time].[Years]": [
  {"operator": "EQUAL", "members": [
    {"formula": "[Time].[2003]", "caption": "2003"},
    {"formula": "[Time].[2004]", "caption": "2004"},
    {"formula": "[Time].[2005]", "caption": "2005"}
  ]}
]}}

getLayoutFields (gembarId) Array

Returns the array of formulas for the layout fields by gembarId.

Parameters:

  • gembarId (String)

    This is the id of the field. It depends on the visualization's type. For example, PIVOT allows values such as "rows", "columns", "measures".

Returns:

  • Array

    This is the array of formulas.

Example:

var gembarId = "rows";
api.report.getLayoutFields(gembarId);

Return Value:
["[Markets].[Territory]"]

getName ( ) String

Returns the name of the current report. New reports will return a null value.

Returns:

  • Name of the current report.

Example:

api.report.getName();

Return Value:
"Country Performance (heat grid)"

getNumericFilters ( )

Gets the numeric filters for the report. Note that a report may only have a single level with a numeric filter and that level must be displayed on the report. For additional information, see Analyzer Filters.

Returns:

  • All filters in a JSON object.

Example:

api.report.getNumericFilters();

Return Value:
{"filters": {"[Markets].[Territory]": [
  {"count": "10", "formula": "[Measures].[Sales]", "operator": "TOP"},
  {"operator": "GREATER_THAN", "formula": "[Measures].[Sales]", "op1": "0.0"},
  {"operator": "LESS_THAN", "formula": "[Measures].[Sales]", "op1": "100000000000"},
  {"operator": "IS_NOT_EMPTY", "formula": "[Measures].[Sales]"}
]}}

getPath ( ) String

Returns the path of the current saved report. New reports will return a null value.

Returns:

The report's path.

Example:

api.report.getPath();

Return Value:
"/public/Steel Wheels/Country Performance (heat grid).xanalyzer"

getReportOption (name) String

Returns the value of the report option by name.

Parameters:

  • name (String)

    The name of the report option. Supported values include:

    • showRowGrandTotal
    • showColumnGrandTotal
    • useNonVisualTotals
    • showEmptyCells
    • showDrillLinks
    • autoRefresh
    • freezeColumns
    • freezeRows

Returns:

  • String

    This is the value of the report option.

Example:

api.report.getReportOption('showRowGrandTotal');

getVizId ( ) String

Returns the current visualization id.

Returns:

The id of the visualization.

Example:

api.report.getVizId();

Return Value:
"ccc_bar"

isDirty ( ) Boolean

Returns as true if the report has pending changes which need to be saved.

Returns:

  • Boolean

    True if report has pending changes and false if no pending changes are present.

Example:

api.report.isDirty();

isNew ( ) Boolean

Returns as true if the report is new.

Returns:

  • Boolean

    True if report is new and false if the report is not new.

Example:

api.report.isNew();

removeFilters (level)

Removes all non-numeric filters for a given level.

Parameters:

  • level (Object)

    This is the level on which the filter is being removed.

Example:

api.report.removeFilters("[Markets].[Territory]");

removeLayoutField (gembarId formula)

Removes a single gem from the gembar using its formula as the key.

Parameters:

  • gembarId (String)

    This is the id of the field. It depends on the visualization's type. For example, PIVOT allows values such as "rows", "columns", "measures".

  • formula (String)

    This is the string representation of the formula to insert as a gem.

Example:

var gembarId = "rows";
var formula = "[Markets].[City]";
api.report.removeLayoutField(gembarId, formula);

removeNumericFilters ( )

Removes all numeric filters on the report.

Example:

api.report.removeNumericFilters();

setChartOption (name value)

Sets the value in the chart option of the current report. This API function is additionally available via URL parameters for each chart option name.

Parameters:

  • name (String)

    The name of the chart's option. Supported values include:

    • legendPosition
    • showLegend
    • autoRange
    • valueAxisLowerLimit
    • valueAxisUpperLimit
    • displayUnits
    • autoRangeSecondary
    • valueAxisLowerLimitSecondary
    • valueAxisUpperLimitSecondary
    • displayUnitsSecondary
    • maxValues
    • backgroundColor
    • labelColor
    • labelSize
    • backgroundFill
    • maxChartsPerRow
    • multiChartRangeScope
    • emptyCellMode
    • sizeByNegativesMode
    • backgroundColorEnd
    • labelStyle
    • legendBackgroundColor
    • legendSize
    • legendColor
    • legendStyle
    • labelFontFamily
    • legendFontFamily
  • value (String)

    This is the value of the chart's option.

Example:

api.report.setChartOption('legendPosition', 'TOP');

http://sample.url.com?showLegend=true&legendPosition=LEFT&legendBackgroundColor=%23EEAADD&legendSize=12&legendColor=%23AA11AA&legendStyle=BOLD&legendFontFamily=Times%20New%20Roman&backgroundFill=SOLID&backgroundColor=%23DDBBCC&labelColor=%23FF2322&labelSize=14&backgroundColorEnd=%23EEAADD&labelStyle=BOLD&labelFontFamily=Times%20New%20Roman&autoRange=false&autoRangeSecondary=false&displayUnits=UNITS_2&displayUnitsSecondary=UNITS_2&valueAxisLowerLimit=500&valueAxisUpperLimit=9000&valueAxisLowerLimitSecondary=4&valueAxisUpperLimitSecondary=55.5&maxValues=3&maxChartsPerRow=2&multiChartRangeScope=GLOBAL&emptyCellMode=GAP&sizeByNegativesMode=USE_ABS

setDatasource (catalog cube)

Sets a data source by its catalog name and cube name. Upon success, the report options are set on the report. After changing data sources, if invalid layout fields are present, they will be automatically removed.

Parameters:

  • catalog (String)

    The name of the catalog.

  • cube (String)

    The name of the cube.

Example:

api.report.setDatasource("SteelWheels", "SteelWheelsSales")

setFieldOption (formula name value)

Sets the field option's value by name for a given formula. For additional information, see APIs for Get/Set Field Options.

Parameters:

  • formula (String)

    This is the string representation of the formula.

  • name (String)

    This is the name of the field's option.

    • label
    • sortOrderEnum
    • showAggregate
    • showSum
    • showAverage
    • showMin
    • showMax
    • showSubtotal
    • formatShortcut
    • formatCategory
    • formatScale
    • formatExpression
    • currencySymbol
  • value (String)

    This is the value of the field's option.

Example:

api.report.setFieldOption("[Markets].[Territory]", "label", "My Territory");

setFilters (level filterItems)

Sets non-numeric filters on a level removing all previous non-numeric filters. For additional information, see Analyzer Filters.

Parameters:

  • level (Object)

    This is the level on which the filter is being set.

  • filterItems (Object)

    The JSON representation of the filter items. Supported Operators: EQUAL, NOT_EQUAL, CONTAIN, NOT_CONTAIN, BEFORE, AFTER, BETWEEN, TIME_AGO, TIME_AHEAD, TIME_YAGO, TIME_RANGE_PREV, TIME_RANGE_NEXT

Example:

api.report.setFilters("[Time].[Years]" : [
  { // Builds a relative equal filter for Previous, Current, and Next on Years
    "operator": "EQUAL",
    "members": [-1, 0, 1]
  },
  { // Builds an exact equal filter on Years
    "operator": "EQUAL",
    "members": [
      { "formula": "[Time].[2003]", "caption": "2003" },
      { "formula": "[Time].[2004]", "caption": "2004" },
      { "formula": "[Time].[2005]", "caption": "2005" }]
  }, {
    "operator": "TIME_RANGE_PREV",
    "members": [10]
  }, {
    "operator": "TIME_RANGE_NEXT",
    "members": [10]
  }, {
    "operator": "TIME_AGO",
    "members": [10]
  }, {
    "operator": "TIME_AHEAD",
    "members": [10]
  }, {
    "operator": "BETWEEN",
    "members": [
      {"formula": "[Time].[2003]", "caption": "2003"},
      {"formula": "[Time].[2005]","caption": "2005"}]
  }],

"[Markets].[Territory]" : [{
  "operator": "CONTAIN",
  "members": ["APAC"]
}]);

setLayoutFields (gembarId formulas)

Sets the array of formulas for the layout fields by gembarId. It overwrites the existing fields in the current gembar. Each formula is validated. If the formula is invalid, then it will not be set.

Parameters:

  • gembarId (String)

    This is the id of the gembar. It depends on the visualization's type. For example, PIVOT allows values such as "rows", "columns", "measures".

  • formulas (Array)

    This is the array of strings of formulas.

Example:

var gembarId = "rows";
var formulas = [ "[Markets].[Territory]", "[Markets].[Country]" ];
api.report.setLayoutFields(gembarId, formulas);

setNumericFilters (level filter)

Sets a numeric filter on a level. There can only be one numeric filter per report. This method will remove any pre-existing numeric filter on the report. For additional information, see Analyzer Filters.

Parameters:

  • level (Object)

    This is the level on which the filter is being set.

  • filter (Object)

    A JSON filter representation. Supported Operators: LESS_THAN, GREATER_THAN, LESS_THAN_EQUAL, GREATER_THAN_EQUAL, EQUAL, NOT_EQUAL, BETWEEN, IS_NOT_EMPTY, TOP, BOTTOM, TOP_BOTTOM

Example:

api.report.setNumericFilters("[Markets].[Territory]", [{"count": "10", "formula": "[Measures].[Sales]", "operator": "TOP"}, {"operator": "GREATER_THAN", "formula": "[Measures].[Sales]", "op1": "0.0"}, {"operator": "LESS_THAN", "formula": "[Measures].[Sales]", "op1": "100000000000"}, {"operator": "IS_NOT_EMPTY", "formula": "[Measures].[Sales]"}]);

setReportOption (name value)

Sets the value of the report option. This API function is additionally available via URL parameters for each report option name.

Parameters:

  • name (String)

    The name of the report's option. Supported values include:

    • showRowGrandTotal
    • showColumnGrandTotal
    • useNonVisualTotals
    • showEmptyCells (Deprecated by ShowEmptyEnum)
    • showEmptyEnum
    • showDrillLinks
    • autoRefresh
    • freezeColumns
    • freezeRows
  • value (String)

    This is the value of the report's option.

Example:

api.report.setReportOption('showRowGrandTotal', 'true');

http://sample.url.com?showRowGrandTotal=true&showColumnGrandTotal=true&useNonVisualTotals=true&showEmptyEnum="SHOW_MEASURE"&showDrillLinks=true&autoRefresh=true&freezeColumns=true&freezeRows

setVizId (vizId)

Sets the report's visualization using the visualization ID.

Parameters:

  • vizId (String)

    This is the id of the visualization.

    • pivot
    • ccc_bar
    • ccc_barstacked
    • ccc_barnormalized
    • ccc_barline
    • ccc_horzbar
    • ccc_horzbarstacked
    • ccc_horzbarnormalized
    • ccc_line
    • ccc_area
    • ccc_pie
    • ccc_sunburst
    • ccc_scatter
    • ccc_heatgrid
    • open_layers

Example:

api.report.setVizId("ccc_bar");