Overview of Report API
The Report API controls the state of the report. It contains information about the current state of the report, including the current drill state, sort criteria, filter values and other report interactions that may have been applied.
The Report API also controls the actual running of the report and will submit any of the interactions to the Yellowfin server when the report is run. The API also triggers a number of events when actions on the report are taken, either by a user action or an automated developer action.
Default Chart ID & Chart IDs
A report can have a number of charts; each of those charts will have a chartId and chartUUID. The chartId will change when a report is edited and published again, whereas the chartUUID will always remain the same. All functions that require a chartId can accept a chartUUID as well, however it is preferred to use chartUUID on any function that requires a chartId to be passed as it will never change.
There is also a “Default Chart” which will be the first usable chart on the report. A usable chart is one that has fields assigned to it. When a function requiring a chartId has no chartId passed to it, the default chart would be used.
You can access all the charts on a report using the charts property.
Field IDs
A report will have a number of fields; each of these fields will have a unique ID within the context of that report. This ID will never change, even when the report is edited. There is a function that allows you to retrieve the fieldId based on the field’s name, getFieldId(fieldName). Most functions that accept a fieldId will also be able to accept a field name and will attempt to find the fieldId based on the passed name.
You can access all of the fields on a report using the fields property.
Drill
When Drill Anywhere or Drill Down is applied to a field the process is as follows:
- Apply the drill value as a hidden filter.
- Replace the field we were drilling down on with the field we are drilling to.
- Run the query with the new field and filter.
Using a very simple drill example, consider a report that just has one column: “Agency Type”. In the Ski Team view (bundled with the Tutorial content in Yellowfin); “Agency Type” has a Drill Hierarchy setup with “Agency Name” as its child. When drill down is applied to the “Agency Type” field the report logic knows to drill down to the ‘Agency Name” field.
When the report is first run the SQL will look like this:
SELECT DISTINCT |
After drill down is applied on ‘Agency’ value you can see that Agency Type has been replaced in the SQL and the Agency Type filter has also been added.
SELECT DISTINCT |
Drill Anywhere works the same way, except it doesn’t have a predefined “drill to” field and the user (or developer if using an API call) defines which field they need to drill to.
Property Reference
name
Returns
String
Description
Returns the report’s name. This will be translated into the user's language if translations are enabled and a translation has been provided for that language.
reportUUID
Returns
String
Description
Returns the UUID of the report.
entityUUID
Returns
String
Description
The Unique Identifier for this instance of the report. This will be defined when the report is included on a Dashboard. Otherwise this will be null.
filters
Returns
Description
Returns the FiltersAPI for the Report. If this report is included on a dashboard, the FiltersAPI will be the same as the Dashboard’s FiltersAPI.
fields
Returns
Array[ReportField]
Description
Returns an ordered Array of the report’s fields.
charts
Returns
Object{String, ReportChart}
Description
Returns an Object containing all of the ReportCharts on the Report, keyed by chart UUID.
reportKey
Returns
String
Description
A unique identifier for the report that is used to identify exactly which instance of a report object should be used. A number of events will contain this as part of the information.
ReportAPI Parameters
These parameters should be set individually for every report that requires them. For example, Assisted Insights is usually triggered from a chart, so these parameters would need to be set on the parent report's API.
useDefaultAssistedInsightsPanel
Default is true.
This indicates to the system that the default Assisted Insights display panel should be rendered. Must be false if displayAssistedInsightsData is being overwritten with a custom panel.
Example
In Code Mode:
let reportElement = this.apis.canvas.select('Performance by Region'); reportElement.onReportLoad.then(() => { let reportAPI = reportElement.reportAPI; reportAPI.useDefaultAssistedInsightsPanel = true; }); |
preventDefaultAssistedInsights
Default is false.
Stops the usual default Assisted Insights flow so you can call runAssistedInsights when required.
This is particularly useful if you wish to customise the UI elements of the Assisted Insights process (loader, etc.) but still require the process to be triggered from a chart tooltip.
Example
let reportElement = this.apis.canvas.select('Performance by Region'); reportElement.onReportLoad.then(() => { let reportAPI = reportElement.reportAPI; reportAPI.preventDefaultAssistedInsights = true; }); |
Function Reference
getFieldId(fieldName)
Returns
Number
Description
Returns the field ID for the passed fieldName. Returns null if no matching field is found.
Example
Get the fieldId of the field “Invoiced”:
let fieldId = report.getFieldId('Invoiced'); |
getFieldName(fieldId)
Returns
String
Description
Returns the field name for the passed fieldId. If no matching field is found null will be returned.
Example
Log that a particular field was drill down on:
report.addListener('drilldown', function(event) { |
getChartId(chartId)
Returns
Number
Description
Returns the internal chartId for the passed chart name or chart UUID. If chartId is passed, the report’s default chart ID will be returned. If no matching chart is found, null will be returned.
applySeriesSelection(series, chartId)
Returns
Nothing
Description
Applies series selection to the passed chartId. Series Selection works by either replacing the series field on a chart with another field or adding multiple series fields to the chart to be rendered together.
The option Visible Series Selection is required to be turned on at the chart level for this function to have any effect on the report. See Image below:
If the option Series Selection Style is set to “Top Panel” or “Left Panel” (as shown below), the chart’s series selection becomes a single selection type. Meaning only a single series can be selected at a time. When this option is enabled, the chart will only take the first value out of the passed array.
If the property is set to “Visible Series Selection”, the type of chart will determine whether all of the values are used or not.
If a fieldId that is not present on the chart or report is passed to the applySeriesSelection function, that fieldId will be ignored and the chart will be set back its default series value.
Parameters
Series - Array[Number]
Array of FieldId’s that you wish to apply to the report.
chartId - String, Number
The chartId that you want to apply the series selection to. If no chartId is passed the default chart ID will be used.
Example
Add a number of fields to the default charts series selection:
let fieldsToAdd = ['Invoiced', 'Cost', 'Profit']; |
Apply using a field ID:
report.applySeriesSelection(5); |
Apply using a field name:
report.applySeriesSelection('Invoiced'); |
createReportElement(elementOptions)
Returns
HTML Element
This method only exists within the Embedded API. It will not be available for use within Dashboard Code Mode.
It creates and returns an element which will render the visualization of a report. If an element is passed as part of elementOptions, the new report element will be appended to that as soon as it is created.
There are a number of options that can be passed along with the request to create the exact experience you want.
Note
Examples
Example 1: Load a report with multiple charts and then render them all into separate elements rather than having a canvas display.
HTML:
<div id=”reportContainer”></div> |
CSS:
div.reportContainer app-report { width:500px; height:500px; } |
JS:
let reportUUID = ‘a-report-uuid’; yellowfin.loadReport({ reportId: reportUUID }).then(report => { let charts = report.charts; Object.values(charts).forEach(chart => { report.createReportElement({ element: document.querySelector(‘#reportContainer’), displayType: ‘CHART’, //Tell the report to render as a chart chartUUID: chart.uuid, //Tell the report which chart you wish to render displayToolbar: false //Tell the report not to render any toolbar }); }); }); |
This will then create a 500x500 render for each chart within the container.
Example 2: Load a report and then render its canvas and table
HTML:
<div id=”reportContainer”></div> |
CSS:
div.reportContainer app-report { width:500px; height:500px; } |
JS:
let reportUUID = ‘a-report-uuid’; yellowfin.loadReport({ reportId: reportUUID }).then(report => { report.createReportElement({ element: document.querySelector(‘#reportContainer’), displayType: ‘CANVAS’, //Tell the report to render as a chart displayToolbar: false //Tell the report not to render any toolbar }); report.createReportElement({ element: document.querySelector(‘#reportContainer’), displayType: ‘REPORT’, //Tell the report to render as a chart displayToolbar: false //Tell the report not to render any toolbar }); }); |
Interactions
The interactions object enables you to define which interactions should be available on a particular visualization of a report. This lets you tell the Yellowfin renderer which functionality you want the user to be able to use within that visualization.
If there are multiple elements representing the same report and you wish to disable an interaction, you must disable it on all the elements you are displaying. For example, if you disabled drill down on the first element and then did not on the second, the user would still be able to drill down on the second element.
By default, any interaction that is not explicitly set to false is treated as enabled and will display if the report allows it.
animation
Allows chart animations to be disabled.
annotations
Allows annotations to be disabled.
brushing
Allows brushing functionality to be disabled.
drillAnywhere
Allows drill anywhere functionality to be disabled.
drillBreadcrumbs
Allows drill breadcrumb functionality to be disabled
drillDown
Allows drill down functionality to be disabled.
drillThrough
Allows drill through functionality to be disabled.
seriesSelection
Allows seriesSelection functionality to be disabled
timeSlider
Allows the timeSlider functionality to be disabled.
unitSelection
Allows unit selection functionality to be disabled.
Example
To disable all user interactivity on the report using the createReportElement function:
report.createReportElement({ interactions: { animation: false, annotations: false, brushing: false, drillBreadcrumbs: false, drillDown: false, drillAnywhere: false, drillThrough: false, seriesSelection: false, timeSlider: false, unitSelection: false, } }); |
sortAscending(fieldId)
Returns
Nothing
Description
Applies ascending sorting to the passed field. If the passed fieldId doesn’t match a field on the report, no sorting will be applied.
Parameters
fieldId: Number, String
FieldId or Name of the field that we wish to sort.
sortDescending(fieldId)
Returns
Nothing
Description
Applies a descending sort to the passed field. If the passed fieldId doesn’t match a field on the report, no sorting will be applied.
Parameters
fieldId: Number, String
FieldId or Name of the field that we wish to sort.
runReport()
Returns
Nothing
Description
Runs the report with the current state of the report applied. If the runReport function is triggered multiple times in a short period of time, the run report request will only be sent to the server once.
Example
Re-run the report every 5 seconds after the report finishes running.
//Add a listener for the reportComplete event |
runAssistedInsights
Returns
Promise
Description
Begins the Assisted Insights process. This will generate a temporary Assisted Insights report and resolve the promise with the report data once it has completed. The assistedInsightsCompleted event will also be triggered with the same data.
Note
The easiest way to generate data in the required format for this function is by triggering the Assisted Insights process on an existing chart and using the eventData from the assistedInsightsRequestedByChart
event.
Parameters
Options {object}
- loader {DOM element} (Optional). A custom loader that will render while the Assisted Insights process is in progress. This will automatically be added to the page when required and removed once the Assisted Insights data is returned. The default loader will be rendered if this is not provided.
- reportTitle {String} (Optional). The report title for the temporary Assisted Insights report. A default report title will be generated if this is not provided.
The options object also requires the following data for the Assisted Insights process. Aside from the required data, the variables will change depending on the type of charrt and analysis.
Required:
- type {String} - Indicates the type of Assisted Insights analysis. Either ‘compare’ or ‘explain’ (see below)
- metricField
- metricDescription
- categoryField
- value1 {String or Number}: The actual value used in the analysis
'explain' string type
Optional:
- dateValue
- timeSeries
- discreteTimeSeries
- granularity
'compare' string type
Additional required values
- categoryFieldId
- categoryKey
- value2 {String or Number}: The second value used in an Assisted Insights comparison
- valueOneFormatted (Only if using the default loader): Readable description of value one that will be displayed to the user (e.g. “Australia”)
- valueTwoFormatted (Only required if using the default loader): Readable description of value two that will be displayed to the user
Optional:
- timeSeries
- discreteTimeSeries
- timeGranularity
Example
See the assistedInsightsRequestedByChart event reference for how to call runAssistedInsights using data from the chart .
Calling it manually:
let assistedInsightsData = { categoryField: 60629, categoryFieldId: 1, categoryKey: "61039", dashboardName: "Sales Performance", dashboardUUID: "e7409ff2-f846-44e1-a603-b78ec51b20b9", metricDescription: "KPI", metricField: 60686, reportTitle: "Comparing KPI for Europe to Asia", parentReportId: 61035, sourceId: 54700, type: "compare", value1: "Europe", value2: "Asia", valueOneFormatted: "Europe", valueTwoFormatted: "Asia", viewId: 60543 }; reportAPI.runAssistedInsights(assistedInsightsData); |
openComparePanel(value, comparableValues, metricDescription)
Returns
Nothing
Description
Renders a panel where the user can select a second value for use in the Assisted Insights comparison.
Users can implement their own compare panel by overwriting this function; otherwise, the default panel will be rendered. In both cases, the compareValuesSelected event should be triggered once the second value has been selected. See the compareValuesSelected event reference for information on what data should be passed with the event.
Calling openComparePanel is handled automatically by the default Assisted Insights flow if one value only is selected when the comparison is triggered from a chart tooltip. If preventDefaultAssistedInsights is true and you are calling runAssistedInsights yourself, openComparePanel will also need to be called manually
Parameters
- value {Object}: valueObject containing the first value in the comparison
These can be in either of the following forms, where value/rawValue refer to the value that will be used in the analysis and description/formattedValue refer to the value description that will be displayed to the user
{
value: “EU”,
description: “Europe”
}
{
rawValue: "EU",
formattedValue: "Europe"
}
If you are extracting Assisted Insights data from the assistedInsightsRequestedByChart event, value corresponds to value1 in the eventData and comparableValues corresponds to possibleValues
- comparableValues {Array}: Array of valueObjects containing the possible values that can be used as the second value in the comparison analysis
Must be in the form:
[{
value: “AUS”,
description: “Australia”
},
{
value: “NA”,
description: “North America”
}]
- metricDescription {String} (Optional): Description of the metric being used (eg, KPI). This is for UI purposes and is used only to add more information to the default compare panel.
Example
reportAPI.addListener('assistedInsightsRequestedByChart', event => { let runAssistedInsightsData = event.eventData; if (runAssistedInsightsData.type === 'compare' && runAssistedInsightsData.value2 == null) { reportAPI.openComparePanel(runAssistedInsightsData.value1, runAssistedInsightsData.possibleValues, runAssistedInsightsData.metricDescription); } }); |
displayAssistedInsightsData(assistedInsightsData)
Returns
Nothing
Description
Renders the Assisted Insights data on the page.
Users can customize the way the data is rendered by overwriting this function. In order to do this, set useDefaultAssistedInsightsPanel to false on the Report API.
If you do render your own display panel, we recommend that you call deleteTemporaryAssistedInsightsReport once the data is no longer required (usually when the display panel is closed). This will remove any data related to the temporary assisted insights report. The default display panel already handles this automatically.
Example
let runAssistedInsightsPromise = reportAPI.runAssistedInsights(data); runAssistedInsightsPromise.then(assistedInsightsData => { // Display the report results reportAPI.displayAssistedInsightsData(assistedInsightsData); }); |
cancelAssistedInsights(assistedInsightsUUID)
Returns
Nothing
Description
Cancels the Assisted Insights process before it has completed and the data has been returned.
This can be useful when rendering a custom loader so users have the option to cancel the process if it is taking too long.
This requires the UUID of the Assisted Insights job. This is passed as eventData when the assistedInsightsInProgress event is triggered.
Example
reportAPI.addListener(‘assistedInsightsInProgress’, event => { let assistedInsightsTaskUUID = event.eventData; reportAPI.cancelAssistedInsights(assistedInsightsTaskUUID); }); |
deleteTemporaryAssistedInsightsReport(assistedInsightReportId)
Returns
Nothing
Description
Deletes the temporary report that is generated for Assisted Insights. This is automatically called when the default Yellowfin display panel is closed, but if you're rendering a custom display panel, we recommend calling it once the data is no longer required.
Parameter
- assistedInsightReportId {Number}: ID for the temporary Assisted Insights report. Returned in the data that is passed when the runAssistedInsights promise is resolved or when the assistedInsightsCompleted event is triggered.
Example
let runAssistedInsightsPromise = reportAPI.runAssistedInsights(data); runAssistedInsightsPromise.then(assistedInsightsData => { let reportId = assistedInsightsData.assistedInsightsReportId; reportAPI.deleteTemporaryAssistedInsightsReport(reportId); }); |
registerOutputType(outputOptions, callback)
Returns
Number
Description
Registers a report output type to the report, which allows developers to get extra information from a report. Returns a unique identifier for the output you have just registered, this can be used to remove the outputType request from the report when you no longer need it.
The callback function for the output type will be called whenever the report has returned its data from the server, but before the reportComplete event is triggered.
From Yellowfin version 9.2 onwards, you can request the reports dataset as an output type.
dataset
Returns the dataset for the report.
Options
No options can be defined for this output type
Callback Parameters
dataset
A two dimensional array. Each item in the array will be an Object containing the following values:
- rawValue: The value as it would be when retrieving it from the database.
- formattedValue: The value after having any Ref Code or formatters applied to it.
- htmlFormattedValue: The value ready to be inserted into an HTML page.
For the field “Gender” which by default is formatted as a Ref Code, the data object would look like the following.
{ |
Differences between formattedValue and htmlFormattedValue
In a lot of cases you might not see any difference between the htmlFormattedValue and the formattedValue. There are some formatters which will output HTML tags which means that you can see differences there. In the following report example, the “Gender As Link” field is formatted using a “Link To URL” formatter which generates an anchor tag to be inserted into the table.
The dataset for the above row looks like this:
[{ |
Where the htmlFormattedValue contains the actual anchor tag and the formattedValue is what is displayed to the user.
Parameters
outputOptions: String, Object
Object or String with the information about the output type you wish to register. If a string is passed, default options will be used for that particular output type.
callback: Function
Function to call when the output type has completed. The parameters objects passed to this callback will vary depending on the output type that has been registered.
Example
Register a dataset output type and output the dataset:
report.registerOutputType('dataset', function(reportDataset) { |
Or register the dataset using the outputInformation object, these will achieve the same result:
report.registerOutputType({ resultType: 'dataset' }, function(reportDataset) { |
removeOutputType(outputKey)
Returns
Nothing
Description
De-registers the report output type and callback associated with the passed outputKey. This will stop the Yellowfin server from returning the information for that output request.
Parameters
outputKey: Number
The outputKey that you wish to de-register.
Example
Register a dataset type and then remove the output type from the report after it has completed once.
let outputId = report.registerOutputType('dataset', function(data) { |
reset()
Returns
Nothing
Description
Clears all of the report interactions (drill, sorting, time sliders, etc.) from a report and then runs the report. This will not reset the filters associated with the report as it is possible that the filters object will be linked to multiple reports, so resetting a filter specifically for this report can have an unintentional effect on another report. If you want to completely reset the report use this function together with filters.resetFiltersToDefault() or filters.clear().
Example
Add a reset button that can reset the reports interactions, but not filters:
let resetButton = document.querySelector('div#resetReportButton'); |
isDrillAnywhere()
Returns
Boolean
Description
Returns whether or not the report has been defined as a 'Drill Anywhere' type report. This will be true if the “Analysis Style” option is set to “Drill Anywhere” during report creation.
isDrillDown()
Returns
Boolean
Description
Returns whether or not the report has been defined as a 'Drill Down' type report. This will be true if the “Analysis Style” option is set to “Drill Down” during report creation.
isDrillDownApplied()
Returns
Boolean
Description
Returns whether or not the report has been drilled down. This will be true if any of the drill down fields on the report has been drilled down.
Example
console.log(report.isDrillDownApplied()); //Will return "false" as no drilling has been applied |
isDrillAnywhereApplied()
Returns
Boolean
Description
Returns whether or not the report has had drill anywhere applied to it.
drill(fieldId, value, toField)
Returns
Nothing
Description
Applies drilling to the passed fieldId, with the passed value.
For 'Drill Anywhere' reports toField will be used to determine the field to replace the fieldId field with. For a 'Drill Down' report the toField will be ignored as there is an internal hierarchy of drilling already defined at the view level.
If the drill is successful a “drilldown” or “drillanywhere” event will be triggered.
Parameters
fieldId: Number, String
The field that you wish to drill on.
value: Number, String
The value you wish to apply as the drill value.
toField: Number
View Field Template ID of the field that you wish to drill to. Will only be used on Drill Anywhere reports.
Examples
Drill down on the value “Agency” on the “Agency Type” field using a fieldId:
report.drill(1, 'Agency'); |
Or we can also use the field name as the fieldId parameter:
report.drill('Agency Type', 'Agency'); |
drillUpLevels(fieldId, levels)
Returns
Nothing
Description
Drills up levels for the passed fieldId. If the field you are drilling is at the top of its hierarchy already, no further action will be taken.
Using fields Camp Region -> Camp Country -> Camp Name as an example. If we are drilled down to the Camp Name level and call report.drillUpLevels(fieldId, 1); it will be returned to the Camp Country level.
If we called report.drillUpLevels(fieldId, 5); which is greater than the total drill hierarchy length (which is 3), this call would effectively reset the drilling on that field and return the fields drill to the Camp Region level.
Parameters
fieldId: Number, String
The field that you wish to drill up on.
levels: Number
The number of levels to drill up.
Example
Drill up a single level on a fieldId 1:
report.drillUpLevels(1, 1); |
drillUpOneLevel()
Returns
Nothing
Description
Drills up one level on all of the fields that are drillable in the report.
Example
Create a drill up button which drills the entire report up a level.
let drillUpButton = document.querySelector('div#drillUp'); |
drillReset(fieldId)
Returns
Nothing
Description
Resets the drill on the passed fieldId. If no fieldId is passed, the entire report's drill state will be reset.
Parameters
fieldId: Number, String
The field that you wish to reset drill on.
Example
Reset the drill of the entire report:
report.drillReset(); |
Reset the drill of field 'Agency Region' by name:
report.drillReset('Agency Region'); |
Reset the drill of the field 'Agency Region' by fieldId:
report.drillReset(1); |
timeslider(from, to, chartId)
Returns
Nothing
Description
Applies the from and to values to the passed chart’s time slider. If no chartId is passed, then the report's default chart will be used. This will run the report to re-generate the chart with the applied time series values.
Parameters
from: Number
The time in milliseconds of the lower bound time slider value.
to: Number
The time in milliseconds of the upper bound time slider value.
chartId: Number, String
ChartId that you wish to apply the time slider values to.
Example
Set the time slider to show dates between 'August 2014' and 'November 2014':
//Create the date objects for the days we care about and get their time values |
unitSelection(unit, chartId)
Returns
Nothing
Description
Applies time unit selection to the passed chart. If no chartId is passed, the report’s default chart will be used instead. The chart needs to have visible unit selection turned on for the option to have any effect.
Parameters
unit: String
The time granularity you wish to apply to the chart. The possible values are:
- MILLISECOND
- SECOND
- MINUTE
- HOUR
- DAY
- WEEK
- MONTH
- YEAR
Example
Apply unit selection of MONTH to the reports default chart
report.unitSelection(‘MONTH’); //No chart Id passed so the default chart will be used let chartUUID = ‘b779c293-a8ac-44cb-82f5-0c64da385333’; report.unitSelection(‘MONTH’, chartUUID ); //Apply with a specific chart uuid let chartName = ‘Chart One’; report.unitSelection(‘MONTH’, chartName); //Pass the chart name to determine which chart to use |
convertDrillDownToArray() & converDrillAnywhereToArray()
Returns
Array[Object]
Description
Returns an Array of the currently applied drill state on the report.
Each object in the Array will contain the following information:
- fieldId: Number indicating which drill hierarchy we have drilled on.
- reportId: The ID of the current report.
- reportKey: The report’s unique key.
- reportUUID: The report’s Publish UUID.
- templateId: The view level TemplateId of the field we are currently on.
- value: The value applied to this stage of the drill.
When iterating through the array, all drill objects on a field will be drilled in sequential order. This means that if you have two fields that you can drill down on and they are both drilled, the first N values in the Array will be related to the first field, where N is how far that field has been drilled. The rest of the array would be made up of drill values for the second field.
On a report with the following drill structure:
Agency Region -> Agency Country
Camp Region -> Camp Country -> Camp Name
Agency Region can drill down one level. Camp Region can drill down two levels. When they are both fully drilled down the array would contain three entries. The first would relate to “Agency Region”, the second would related to “Camp Region” and the third would relate to “Camp Country” as that is the child of Camp Region.
Event Reference
All report events will be triggered with an object that contains the following properties:
- eventData: The data for the specific event. This will vary depending on the event that has been triggered. See each event to see what is included in the eventData object.
- metadata: An Object that contains some basic data about the report the event was triggered on, including:
- reportId: The Internal ReportId.
- reportUUID: The report’s UUID.
- reportKey: A unique identifier for this instance of the report.
- eventName: The name of the event that was actually triggered.
seriesSelection
Description
Triggered when series selection is applied to the report.
Parameters
eventData
- Series: (Array[Number] )Array of the field IDs that were applied for this series selection event. This should only contain fields that are actually on the report.
- chartId: The chartId the series selection was applied to.
sort
Description
Triggered when the report is sorted.
Parameters
eventData
- fieldId: The field that sorting was applied on.
- sortDirection: The direction that the field was sorted. Will be “ASCENDING” or “DESCENDING”.
reportStart
Description
Triggered when the report sends a request to the server to get a new dataset.
Parameters
No Event Data.
reportComplete
Description
Called after the report has returned from the server, and all of the callbacks that were registered in the registerOutputType function are resolved.
Parameters
eventData will contain a number of output results from the report run.
Example of Event Data:
{ //Example Empty Dataset |
assistedInsightsRequestedByChart
Description
Triggered when a user prompts Assisted Insights from a chart tooltip.
Helpful if you want to extract the data used to generate a particular Assisted Insights report or if useDefaultAssistedInsightsPanel is false and you are calling runAssistedInsights yourself.
Parameters
The eventData object contains all of the information required to run Assisted Insights and can be passed directly to runAssistedInsights if you are calling it manually. The contents of this will change depending on the Assisted Insights type and the chart.
eventData
- categoryField
- categoryFieldId (optional)
- categoryKey (optional)
- dashboardName: Name of the dashboard
- dashboardUUID: UUID for the dashboard
- metricDescription
- metricField
- parentReportId: ID for the report that the chart belongs to
- possibleValues (optional): List of objects representing the values that can be used in a comparison analysis with value1
- reportKey: key for the report that the chart belongs to
- sourceId: ID for the Data Source used by the parentReport
- type: type of Assisted Insights analysis (either ‘explain’ or ‘compare’)
- value1: The value to be used in the analysis
- value2 (optional): The second value to be used in a comparison analysis
- viewId: ID for the view used by the parentReport
Example
reportAPI.addListener('assistedInsightsRequestedByChart', chartData => { // This already contains all of the data we need to run Assisted Insights so we don’t need to make any additional changes to it let newData = Object.assign({}, chartData.eventData); let promise = this.reportAPI.runAssistedInsights(newData); }); |
assistedInsightsStarted
Description
Triggered when runAssistedInsights is called.
Parameters
Nothing.
Example
reportAPI.addListener(assistedInsightsStarted, () => { console.log(“Assisted Insights has started”); }; |
compareValuesSelected
Description
Triggered when a second value is selected for comparison.
Parameters
eventData
- value1 {String or number}: The “actual” value one. This is what will be used in the analysis. Equivalent to the value/rawValue that is passed to openComparePanel
- valueOneFormatted {String or number}: The description of value one that will be displayed to the user. Equivalent to the description/formattedValue that is passed to openComparePanel
- value2 {String or number}: The “actual” value two. This is what will be used in the analysis. Equivalent to the value/rawValue that is passed to openComparePanel
- valueTwoFormatted {String or number}: The description of value two that will be displayed to the user. Equivalent to the description/formattedValue that is passed to openComparePanel
Example
this.reportAPI.addListener('compareValuesSelected', event => { let comparisonValues = event.eventData; // Combine them with the existing Assisted Insights data let allData = Object.assign({}, assistedInsightsData, comparisonValues); // Generate the assisted insights report reportAPI.runAssistedInsights(allData); }); |
assistedInsightsInProgress
Description
Triggered when the Assisted Insights background task is first started.
Parameters
eventData
- UUID of the Assisted Insights background task. This can be passed to cancelAssistedInsights when cancelling the task before it has completed
Note: The task UUID refers to the UUID for the background task and is different to the Assisted Insights report ID, which is returned when the runAssistedInsights promise is resolved or the assistedInsightsCompleted event is triggered.
Example
reportAPI.addListener(‘assistedInsightsInProgress’, event => { let assistedInsightsTaskUUID = event.eventData; reportAPI.cancelAssistedInsights(assistedInsightsTaskUUID); }); |
assistedInsightUpdate
Description
Triggered while the Assisted Insights task is in progress. Provides updates on the current state of the task.
Parameters
eventData
- progressText {String}: A string containing translated updates on the current progress of the assisted insights task. Useful for rendering updates to the user on a custom loader
- state {String}: Current state of the background task. Can be Queued, Running or Complete
Example
reportAPI.addListener(‘assistedInsightUpdate’, event => { let progressData = event.eventData; let customLoader = document.getElementById("myCustomLoader"). customLoader.innerHTML(progressData.progressText); }); |
assistedInsightsCompleted
Description
Triggered when the entire runAssistedInsights process has finished.
Note: This is in addition to the runAssistedInsights promise being resolved. Both return the same data.
Parameters
eventData
- assistedInsightsReportId {Number}: ID for the temporary Assisted Insights report. This is required when calling deleteTemporaryAssistedInsightsReport
- chartData {Object}: Object containing Assisted Insights data objects to be rendered in the display panel
- assistedInsightsImage {base64 String}: Image of the Assisted Insights chart
- assistedInsightsZoomedImage {base64 String}: Larger version the image of the Assisted Insights chart
- chartId {Number}: ID for the chart
- narratives {Array}: Formatted text outlining the Assisted Insights findings
Example
reportAPI.addListener('assistedInsightsCompleted', data => { // Display the report results reportAPI.displayAssistedInsightsData(data.eventData); }); |
assistedInsightsCancelled
Description
Triggered when cancelAssistedInsights has been cancelled.
Parameters
eventData
- UUID of the cancelled task
Example
reportAPI.addListener(‘assistedInsightsCancelled’, event => { console.log(“Task ” + event.eventData + “ has been cancelled”); }); |
assistedInsightsError
Description
Triggered when something has prevented the Assisted Insights process from completing.
Parameters
eventData
- getMessageText {function}: Generic error message indicating an error has occurred
Example
reportAPI.addListener(‘assistedInsightsError’, event => { console.log(event.eventData.getMessageText()); }); |
assistedInsightsExceptionError
Description
Triggered when an exception occurs during the Assisted Insights process.
Parameters
eventData
- errorMessage: Generic error message indicating that the analysis could not be completed
Example
reportAPI.addListener(‘assistedInsightsExceptionError’, event => { console.log(event.eventData.errorMessage); }); |
drilldown
Description
Triggered whenever drill down is applied to any field on the report.
Parameters
eventData includes:
- fieldId: The field that was drilled on.
- added: (Array) Array of objects containing information about what values were applied
- drillState: (Array) Array containing the entire drillState of the report. See convertDrillDownToArray
drillanywhere
Description
Triggered whenever 'Drill Anywhere' is applied to any field on the report.
Parameters
eventData includes:
- added: (Array) Array of drill objects that have been added in this drill event.
- drillState: (Arra) Drill State of the entire report. See convertDrillAnywhereToArray.
drillUp
Description
Triggered whenever a report drills up. This will trigger for both 'Drill Anywhere' and 'Drill Down' reports.
Parameters
- removed: (Array) Array of drill objects that have been removed in this drill event.
- drillState: (Array) Drill State of the entire report. See convertDrillAnywhereToArray or convertDrillDownToArray.
reportRunAlreadyInProgress
Description
Triggered if any process tries to start a report run while the report is already running.
Example
report.addEventListener("reportRunAlreadyInProgress", function() { alert("report is already running"); }); |
resetDrill
Description
Triggered when the drill state for a field is reset or the entire reports drill state is reset. This will trigger for both Drill Anywhere and Drill Down reports.
Parameters
- removed: (Array) Array of drill objects that have been removed in this drill event.
- drillState: (Array) Drill State of the entire report. See convertDrillAnywhereToArray or convertDrillDownToArray.
reset
Description
Triggered when the reports reset function is called.
Parameters
No Event Data.
slider
Description
Triggered when a chart's time slider value is modified.
Parameters
eventData
- from: (Number) Lower bound of the slider values.
- To: (Number) Upper bound of the slider values.
- chartId: (Number) The chart which the slider was modified on.
unitSelection
Description
Triggered when a chart's 'Unit Selection' is changed.
Parameters
eventData
- unit: (String) The unit to be applied to the chart.
- chartId: (Number) The chart that the unit selection was applied to.