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.
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'); |