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.
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.
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.
When Drill Anywhere or Drill Down is applied to a field the process is as follows:
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.
String
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.
String
Returns the UUID of the report.
String
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.
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.
Array[ReportField]
Returns an ordered Array of the report’s fields.
Object{String, ReportChart}
Returns an Object containing all of the ReportCharts on the Report, keyed by chart UUID.
String
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.
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.
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.
In Code Mode:
let reportElement = this.apis.canvas.select('Performance by Region'); reportElement.onReportLoad.then(() => { let reportAPI = reportElement.reportAPI; reportAPI.useDefaultAssistedInsightsPanel = true; }); |
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.
let reportElement = this.apis.canvas.select('Performance by Region'); reportElement.onReportLoad.then(() => { let reportAPI = reportElement.reportAPI; reportAPI.preventDefaultAssistedInsights = true; }); |
Number
Returns the field ID for the passed fieldName. Returns null if no matching field is found.
Get the fieldId of the field “Invoiced”:
let fieldId = report.getFieldId('Invoiced'); |
String
Returns the field name for the passed fieldId. If no matching field is found null will be returned.
Log that a particular field was drill down on:
report.addListener('drilldown', function(event) { |
Number
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.
Nothing
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.
Array of FieldId’s that you wish to apply to the report.
The chartId that you want to apply the series selection to. If no chartId is passed the default chart ID will be used.
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'); |
Nothing
Applies ascending sorting to the passed field. If the passed fieldId doesn’t match a field on the report, no sorting will be applied.
FieldId or Name of the field that we wish to sort.
Nothing
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.
FieldId or Name of the field that we wish to sort.
Nothing
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.
Re-run the report every 5 seconds after the report finishes running.
//Add a listener for the reportComplete event |
Promise
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.
A new Assisted Insights report is generated each time this is called, even if the options are the same. If you are calling this manually, we recommend safeguarding against duplicate requests or multiple requests being made until the previous ones have returned. |
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.
Options {object}
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:
Optional:
Additional required values
Optional:
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); |
Nothing
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
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 |
Must be in the form:
[{ value: “AUS”, description: “Australia” }, { value: “NA”, description: “North America” }] |
reportAPI.addListener('assistedInsightsRequestedByChart', event => { let runAssistedInsightsData = event.eventData; if (runAssistedInsightsData.type === 'compare' && runAssistedInsightsData.value2 == null) { reportAPI.openComparePanel(runAssistedInsightsData.value1, runAssistedInsightsData.possibleValues, runAssistedInsightsData.metricDescription); } }); |
Nothing
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); }); |
Nothing
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.
reportAPI.addListener(‘assistedInsightsInProgress’, event => { let assistedInsightsTaskUUID = event.eventData; reportAPI.cancelAssistedInsights(assistedInsightsTaskUUID); }); |
Nothing
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.
let runAssistedInsightsPromise = reportAPI.runAssistedInsights(data); runAssistedInsightsPromise.then(assistedInsightsData => { let reportId = assistedInsightsData.assistedInsightsReportId; reportAPI.deleteTemporaryAssistedInsightsReport(reportId); }); |
Number
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.
Returns the dataset for the report.
No options can be defined for this output type
dataset
A two dimensional array. Each item in the array will be an Object containing the following values:
For the field “Gender” which by default is formatted as a Ref Code, the data object would look like the following.
{ |
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.
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.
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.
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) { |
Nothing
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.
The outputKey that you wish to de-register.
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) { |
Nothing
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().
Add a reset button that can reset the reports interactions, but not filters:
let resetButton = document.querySelector('div#resetReportButton'); |
Boolean
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.
Boolean
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.
Boolean
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.
console.log(report.isDrillDownApplied()); //Will return "false" as no drilling has been applied |
Boolean
Returns whether or not the report has had drill anywhere applied to it.
Nothing
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.
The field that you wish to drill on.
The value you wish to apply as the drill value.
View Field Template ID of the field that you wish to drill to. Will only be used on Drill Anywhere reports.
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'); |
Nothing
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.
The field that you wish to drill up on.
The number of levels to drill up.
Drill up a single level on a fieldId 1:
report.drillUpLevels(1, 1); |
Nothing
Drills up one level on all of the fields that are drillable in the report.
Create a drill up button which drills the entire report up a level.
let drillUpButton = document.querySelector('div#drillUp'); |
Nothing
Resets the drill on the passed fieldId. If no fieldId is passed, the entire report's drill state will be reset.
The field that you wish to reset drill on.
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); |
Nothing
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.
The time in milliseconds of the lower bound time slider value.
The time in milliseconds of the upper bound time slider value.
ChartId that you wish to apply the time slider values to.
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 |
Nothing
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.
The time granularity you wish to apply to the chart. The possible values are:
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 |
Array[Object]
Returns an Array of the currently applied drill state on the report.
Each object in the Array will contain the following information:
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.
All report events will be triggered with an object that contains the following properties:
Triggered when series selection is applied to the report.
eventData
Triggered when the report is sorted.
eventData
Triggered when the report sends a request to the server to get a new dataset.
No Event Data.
Called after the report has returned from the server, and all of the callbacks that were registered in the registerOutputType function are resolved.
eventData will contain a number of output results from the report run.
Example of Event Data:
{ //Example Empty Dataset |
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.
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
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); }); |
Triggered when runAssistedInsights is called.
Nothing.
reportAPI.addListener(assistedInsightsStarted, () => { console.log(“Assisted Insights has started”); }; |
Triggered when a second value is selected for comparison.
eventData
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); }); |
Triggered when the Assisted Insights background task is first started.
eventData
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.
reportAPI.addListener(‘assistedInsightsInProgress’, event => { let assistedInsightsTaskUUID = event.eventData; reportAPI.cancelAssistedInsights(assistedInsightsTaskUUID); }); |
Triggered while the Assisted Insights task is in progress. Provides updates on the current state of the task.
eventData
reportAPI.addListener(‘assistedInsightUpdate’, event => { let progressData = event.eventData; let customLoader = document.getElementById("myCustomLoader"). customLoader.innerHTML(progressData.progressText); }); |
Triggered when the entire runAssistedInsights process has finished.
Note: This is in addition to the runAssistedInsights promise being resolved. Both return the same data.
eventData
reportAPI.addListener('assistedInsightsCompleted', data => { // Display the report results reportAPI.displayAssistedInsightsData(data.eventData); }); |
Triggered when cancelAssistedInsights has been cancelled.
eventData
reportAPI.addListener(‘assistedInsightsCancelled’, event => { console.log(“Task ” + event.eventData + “ has been cancelled”); }); |
Triggered when something has prevented the Assisted Insights process from completing.
eventData
reportAPI.addListener(‘assistedInsightsError’, event => { console.log(event.eventData.getMessageText()); }); |
Triggered when an exception occurs during the Assisted Insights process.
eventData
reportAPI.addListener(‘assistedInsightsExceptionError’, event => { console.log(event.eventData.errorMessage); }); |
Triggered whenever drill down is applied to any field on the report.
eventData includes:
Triggered whenever 'Drill Anywhere' is applied to any field on the report.
eventData includes:
Triggered whenever a report drills up. This will trigger for both 'Drill Anywhere' and 'Drill Down' reports.
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.
Triggered when the reports reset function is called.
No Event Data.
Triggered when a chart's time slider value is modified.
eventData
Triggered when a chart's 'Unit Selection' is changed.
eventData