Skip to main content
Pentaho Documentation

Report APIs

cv.api. report

Constructor

Name Description
new report()

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

Methods

Name Description
addLayoutField(gembarId, formula, gembarOrdinal)

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

addSelectionFilter(selectionFilter)

Adds a selection filter.

addSelectionFilters(selectionFilters)

Adds a list of selection filters.

buildCellActionContext(td) : JSON

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.

buildFilterActionContext() : JSON

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.

getChartOption(name) : string

Returns the value of the chart option by name.

getFieldOption(formula, name) : string

Returns the field option's value by name for a given formula.

getFilters() : JSON

Returns all level filters on the report.

getLayoutFields(gembarId) : Array

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

getName() : string

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

getNumericFilters() : JSON

Gets the measure filters for the report. Note that a report may only have a single level with a measure filter and that level must be displayed on the report.

getPath() : string

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

getReportOption(name) : string

Returns the value of the report option by name.

getSelectionFilters() : JSON

Gets the selection filters for the report.

getVizId() : string

Returns the current visualization type id.

isDirty() : boolean

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

isNew() : boolean

Returns as true if the report is new.

removeFilters(level)

Removes all non-numeric filters for a given level.

removeLayoutField(gembarId, formula)

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

removeNumericFilters()

Removes all numeric filters on the report.

removeSelectionFilters(noRefresh)

Removes all selection filters.

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.

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.

setFieldLink(formula, callback)

Renders a hyperlink on all members/cells under the given level/measure. The input formula can either be a level or measure formula. If level formula, then all members under the level will have this link. If a level already specifies a content link, this API will override that link. If measure formula, then all table cells that contain this measure will have this link. If a measure already has a hyperlink such as if drilldown was enabled, this API will override that link. You do not need to refresh the report in order for the links to appear. They appear immediately after calling this API.

setFieldOption(formula, name, value)

Sets option's value for formula by name.

setFilters(level, filterItems, forceAnd)

Sets filters on a level removing all previous filters.

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.

setNumericFilters(level, filterItems)

Sets a measure filter on a level. There can only be one measure filter per report. This method will remove any pre-existing measure filter on the report.

setReportOption(name, value)

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

setVizId(vizId)

Sets the report visualization using the visualization id. This api function is additionally available via the URL parameter 'vizId'

Constructor Details

new report()

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

Source: javascript/scripts/cv_api_report.js, line 32

Methods Details

addLayoutField(gembarId, formula, gembarOrdinal)

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

Source: javascript/scripts/cv_api_report.js, line 275

Parameters:
Name Default Value Summary
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.

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;

 cv.api.report.addLayoutField( gembarId, formula, gembarOrdinal );
addSelectionFilter(selectionFilter)

Adds a selection filter.

Source: javascript/scripts/cv_api_report.js, line 632

Parameters:
Name Default Value Summary
selectionFilter : JSON

The JSON representation of the selection filter item.

Example

cv.api.report.addSelectionFilter({
 operator: "EXCLUDE",
 members: [{
 formula: "[Geography].[TERRITORY]",
 member: "[Geography].[EMEA]"
 }]
 });
addSelectionFilters(selectionFilters)

Adds a list of selection filters.

Source: javascript/scripts/cv_api_report.js, line 686

Parameters:
Name Default Value Summary
selectionFilters : JSON

The JSON representation of the selection filters item list.

Example

cv.api.report.addSelectionFilters([{
 operator: "EXCLUDE",
 members: [{
 formula: "[Geography].[TERRITORY]",
 member: "[Geography].[EMEA]"
 }]
 }, {
 operator: "INCLUDE",
 members: [{
 formula: "[Geography].[TERRITORY]",
 member: "[Geography].[APAC]"
 }]
 }]);
Since:
  • 5.4
buildCellActionContext(td) : JSON

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.

Source: javascript/scripts/cv_api_report.js, line 1470

Parameters:
Name Default Value Summary
td : object

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

Returns:
Name Description
JSON

This is the JSON object containing specific TD cell context.

Example

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

 // Return Value: {
 // "[Measures].[MeasuresLevel]" : "[Measures].[Sales]",
 // "[Markets].[Territory]" : "[Markets].[APAC]"
 // }
Since:
  • 5.4
buildFilterActionContext() : JSON

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.

Source: javascript/scripts/cv_api_report.js, line 1440

Returns:
Name Description
JSON

This is the JSON object containing the filter context.

Example

var filterCtx = cv.api.report.buildFilterActionContext();

 // Return Value: {
 // "[Markets].[Territory]" : {
 // "EQUAL" : ["[Markets].[APAC]"]
 // }
 // }
getChartOption(name) : string

Returns the value of the chart option by name.

Source: javascript/scripts/cv_api_report.js, line 1241

Parameters:
Name Default Value Summary
name : string

name of chart's option. Supported values: 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:
Name Description
string

This is the value of the chart option.

Example

cv.api.report.getChartOption('legendPosition');
getFieldOption(formula, name) : string

Returns the field option's value by name for a given formula.

Source: javascript/scripts/cv_api_report.js, line 1051

Parameters:
Name Default Value Summary
formula : string

string representation of the formula

name : string

name of field's option. Supported values: label, sortOrderEnum, showAggregate, showSum, showAverage, showMin, showMax, formatShortcut, formatCategory, formatScale, formatExpression, currencySymbol, showSubtotal

Returns:
Name Description
string

option's value

Example

cv.api.report.getFieldOption("[Markets].[Territory]", "showSubtotal");
getFilters() : JSON

Returns all level filters on the report.

Source: javascript/scripts/cv_api_report.js, line 747

Returns:
Name Description
JSON

JSON filters This is a JSON object containing all level filters.

Example

cv.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.

Source: javascript/scripts/cv_api_report.js, line 197

Parameters:
Name Default Value Summary
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:
Name Description
Array

This is the array of formulas.

Example

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

 // Return Value: ["[Markets].[Territory]", "[Markets].[Country]"]
getName() : string

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

Source: javascript/scripts/cv_api_report.js, line 355

Returns:
Name Description
string

Name of the current report.

Example

cv.api.report.getName();

 // Return Value: "Country Performance (heat grid)"
getNumericFilters() : JSON

Gets the measure filters for the report. Note that a report may only have a single level with a measure filter and that level must be displayed on the report.

Source: javascript/scripts/cv_api_report.js, line 405

Returns:
Name Description
JSON

All filters in a JSON object.

Example

cv.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.

Source: javascript/scripts/cv_api_report.js, line 380

Returns:
Name Description
string

The report's path.

Example

cv.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.

Source: javascript/scripts/cv_api_report.js, line 1179

Parameters:
Name Default Value Summary
name : string

name of report's option. Supported values: showRowGrandTotal, showColumnGrandTotal, useNonVisualTotals, showEmptyCells, showDrillLinks, autoRefresh, freezeColumns, freezeRows

Returns:
Name Description
string

This is the value of the report option.

Example

cv.api.report.getReportOption('showRowGrandTotal');
getSelectionFilters() : JSON

Gets the selection filters for the report.

Source: javascript/scripts/cv_api_report.js, line 557

Returns:
Name Description
JSON

All selection filters in a JSON object.

Example

cv.api.report.getSelectionFilters();

 // Return Value: {
 // "selectionFilters": [{
 // "operator": "EXCLUDE",
 // "members": [{
 // "formula": "[Geography].[TERRITORY]",
 // "member": "[Geography].[EMEA]"
 // }]
 // }]
 // }
getVizId() : string

Returns the current visualization type id.

Source: javascript/scripts/cv_api_report.js, line 995

Returns:
Name Description
string

The id of the visualization type.

Example

cv.api.report.getVizId();

 // Return Value: "ccc_bar"
isDirty() : boolean

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

Source: javascript/scripts/cv_api_report.js, line 1139

Returns:
Name Description
boolean

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

Example

cv.api.report.isDirty();
isNew() : boolean

Returns as true if the report is new.

Source: javascript/scripts/cv_api_report.js, line 1159

Returns:
Name Description
boolean

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

Example

cv.api.report.isNew();
removeFilters(level)

Removes all non-numeric filters for a given level.

Source: javascript/scripts/cv_api_report.js, line 957

Parameters:
Name Default Value Summary
level : string

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

Example

cv.api.report.removeFilters("[Markets].[Territory]");
removeLayoutField(gembarId, formula)

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

Source: javascript/scripts/cv_api_report.js, line 322

Parameters:
Name Default Value Summary
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]";

 cv.api.report.removeLayoutField(gembarId, formula);
removeNumericFilters()

Removes all numeric filters on the report.

Source: javascript/scripts/cv_api_report.js, line 977

Example

cv.api.report.removeNumericFilters();
removeSelectionFilters(noRefresh)

Removes all selection filters.

Source: javascript/scripts/cv_api_report.js, line 727

Parameters:
Name Default Value Summary
noRefresh : boolean

Controls report refresh when removing selection filters

Example

cv.api.report.removeSelectionFilters();
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.

Source: javascript/scripts/cv_api_report.js, line 1269

Parameters:
Name Default Value Summary
name : string

name of chart's option. Supported values: 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

cv.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.

Source: javascript/scripts/cv_api_report.js, line 1303

Parameters:
Name Default Value Summary
catalog : string

The name of the catalog.

cube : string

The name of the cube.

Example

cv.api.report.setDatasource("SteelWheels", "SteelWheelsSales")
setFieldOption(formula, name, value)

Sets option's value for formula by name.

Source: javascript/scripts/cv_api_report.js, line 1099

Parameters:
Name Default Value Summary
formula : string

string representation of the formula

name : string

name of field's option. Supported values: label, sortOrderEnum, showAggregate, showSum, showAverage, showMin, showMax, formatShortcut, formatCategory, formatScale, formatExpression, currencySymbol, showSubtotal

value : string

value of field's option

Example

cv.api.report.setFieldOption("[Markets].[Territory]", "label", "My Territory");
setFilters(level, filterItems, forceAnd)

Sets filters on a level removing all previous filters.

Source: javascript/scripts/cv_api_report.js, line 840

Parameters:
Name Default Value Summary
level : string

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

filterItems : JSON

A JSON filter representation. Supported Operators: EQUAL, NOT_EQUAL, CONTAIN, NOT_CONTAIN, BEFORE, AFTER, BETWEEN, TIME_AGO, TIME_AHEAD, TIME_YAGO, TIME_RANGE_PREV, TIME_RANGE_NEXT, NUMERIC_BETWEEN, NUMERIC_GREATER_THAN, NUMERIC_GREATER_THAN_EQUAL, NUMERIC_LESS_THAN, NUMERIC_LESS_THAN_EQUAL

forceAnd : boolean

Example

cv.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"}]
 }, {
 "operator": "NUMERIC_GREATER_THAN",
 "op1": 500
 }, {
 "operator": "NUMERIC_BETWEEN",
 "op1" : 10,
 "op2" : 20
 }
 ]);

 cv.api.report.setFilters("[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.

Source: javascript/scripts/cv_api_report.js, line 226

Parameters:
Name Default Value Summary
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".

formulas : Array

This is the array of strings of formulas.

Example

var gembarId = "rows";
 var formulas = [ "[Markets].[Territory]", "[Markets].[Country]" ];

 cv.api.report.setLayoutFields(gembarId, formulas);
setNumericFilters(level, filterItems)

Sets a measure filter on a level. There can only be one measure filter per report. This method will remove any pre-existing measure filter on the report.

Source: javascript/scripts/cv_api_report.js, line 477

Parameters:
Name Default Value Summary
level : string

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

filterItems : JSON

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

var filterItems = [
 {"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]"}
 ];

 cv.api.report.setNumericFilters("[Markets].[Territory]", filterItems);
setReportOption(name, value)

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

Source: javascript/scripts/cv_api_report.js, line 1202

Parameters:
Name Default Value Summary
name : string

name of report's option. Supported values: showRowGrandTotal, showColumnGrandTotal, useNonVisualTotals, showEmptyCells, showDrillLinks, autoRefresh, freezeColumns, freezeRows

value : string

this is the value of the report's option.

Example

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

 http://sample.url.com?showRowGrandTotal=true&showColumnGrandTotal=true&useNonVisualTotals=true&showEmptyCells=true&showDrillLinks=true&autoRefresh=true&freezeColumns=true&freezeRows
setVizId(vizId)

Sets the report visualization using the visualization id. This api function is additionally available via the URL parameter 'vizId'

Source: javascript/scripts/cv_api_report.js, line 1020

Parameters:
Name Default Value Summary
vizId : string

This is the id of the visualization. Possible values are pivot, ccc_bar, ccc_barstacked, ccc_barnormalized, ccc_horzbar, ccc_horzbarstacked, ccc_horzbarnormalized, ccc_pie, ccc_line, ccc_area, ccc_scatter, ccc_barline, ccc_heatgrid, ccc_sunburst, open_layers.

Example

cv.api.report.setVizId("ccc_bar");

 http://sample.url.com?vizId=ccc_bar