Report Metadata API

Reports are an essential part of any organization, as they provide insights into various aspects of the business. In the case of our CRM, you can use the Reports.ReportMetadata class to programmatically access metadata about a report in your organization. In this article, we will be covering the main topics of this interesting subject along with various examples to showcase its usage.

What is the ReportMetadata class?

Report metadata provides details about a report’s overall contents, including the report’s type, format, summary fields, row or column groupings, and filters that have been preserved. Moreover, the ReportMetadata class allows you to set metadata that can be used to filter reports and to get report metadata. It has many methods, each one giving you the possibility to perform an operation with your report’s metadata. It is part of the Salesforce Reports and Dashboards API, which provides a programmatic interface for working with reports and dashboards in Salesforce.

Use cases for the ReportMetadata class

With the ReportMetadata class, as its name states, you can retrieve report metadata to get information about a report and its report type. You may use the metadata obtained to do various things – among others:

• Find out what fields and values you can filter on in the report type.
• Build custom chart visualizations by using the metadata information on fields, groupings, detailed data, and summaries.
• Change filters in the report metadata when you run a report.

From Salesforce’s documentation, we can extract the following information: “Use the ReportResults.getReportMetadata method to retrieve report metadata. You can then use the “get” methods on the ReportMetadata class to access metadata values.”. This enables us to perform certain operations on the report metadata, such as the ones listed below, chosen from the many available in the Apex Developer documentation. For demonstration purposes only, we hardcoded the Id’s – a thing that should never be done in “real” examples.

Report filter values through Apex

To get the filters the report has, we can use the getReportFilters method, which returns a list of filter criteria for a report. The list of filters can be used to programmatically modify the report or to have a better understanding of the structure of the report. In this list, we can find each custom filter, along with the field name, filter operator, and filter value.

It is worth noting that getReportFilters only returns the custom filters added to the report. In order to access the standard ones, you can use getStandardFilters. If you wish to access the standard date filter, you can use the getStandardDateFilter method.

ReportsMetadata reportMetadata = new ReportsMetadata()

// Retrieve the metadata for a specific report
ReportMetadata report = reportMetadata.getReportMetadata(‘00O7i0000017DGQEA2’);

// Retrieve the filters for the report
List<reportfilter> filters = report.getReportFilters();

// Print the name and operator of each filter
for (ReportFilter filter : filters) {

  System.debug(filter.getName() + ': ' + filter.getOperator() + ‘-->’ + filter.getValue());
};
</reportfilter>

Obtain the Report Format Type

The getFormatType method returns the format type of the report. This is useful due to the fact that the format type determines how the report is displayed, such as a table, chart, or matrix.

ReportsMetadata reportMetadata = new ReportsMetadata();

// Retrieve the metadata for a specific report
ReportMetadata report = 
reportMetadata.getReportMetadata(‘00O7i0000017DGQEA2’);

// Print the format type of the report
System.debug(report.getFormatType());

It is worth noting that the getFormatType method returns a ReportFormatType enum value, which can be one of the following:

• ReportFormatType.TABLE – the report is displayed as a table.
• ReportFormatType.MATRIX – the report is displayed as a matrix.
• ReportFormatType.SUMMARY – the report is displayed as a summary.
• ReportFormatType.CHART – the report is displayed as a chart.

Know whether the Grand Total is displayed

In case you’re curious as to check if the Grand Total is displayed, you may use the getShowGrandTotal method. It returns a Boolean value that indicates whether it is displayed in the report. As a little reminder, the Grand Total is the sum of all the values in a column or row of the report.

ReportsMetadata reportMetadata = new ReportsMetadata();

// Retrieve the metadata for a specific report
ReportMetadata report = reportMetadata.getReportMetadata(‘00O7i0000017DGQEA2’);

// Check whether the grand total is displayed in the report
if (report.getShowGrandTotal()) {
  System.debug('The grand total is displayed in the report.');
} else {
  System.debug('The grand total is not displayed in the report.');
}

Create Cross Filters in a Report through Apex

Let’s get a little bit more creative! Imagine we want to add cross filters to our report. This will allow us to filter the data in our report based on the value of a field in a related object. For instance, you might use it to show only the opportunities that are related to a specific account. In the following example, the setCrossFilters method is used to set a cross-filter that filters the report by the Account Name field. The filter is set to show only the records where the Account Name equals ‘Antique Bookshop’.

ReportsMetadata reportMetadata = new ReportsMetadata();

// Retrieve the metadata for a specific report
ReportMetadata report = reportMetadata.getReportMetadata(‘00O7i0000017DGQEA2’);

// Create a list of cross filters
List<reportcrossfilter> crossFilters = new List<reportcrossfilter>();

// Add a cross filter that filters the report by the Account Name field
ReportCrossFilter filter = new ReportCrossFilter();
filter.setField('Account.Name');
filter.setOperator(ReportFilterOperator.EQUALS);
filter.setValue(‘Antique Bookshop');
crossFilters.add(filter);

// Set the cross filters for the report
report.setCrossFilters(crossFilters);

// Update the report metadata
update report;
</reportcrossfilter></reportcrossfilter>

 

Set the number of rows to display

Let’s say we want to limit the number of rows shown in a report. The method setTopRows would do the job for us! By default, Salesforce displays all rows in a report. However, you may use the setTopRows method to specify the number of rows to display, such as let’s say, the top 10 or top 100 rows. In this example, the aforementioned method is used to set the number of rows to display in the report to the top 10 rows.

ReportsMetadata reportMetadata = new ReportsMetadata();

// Retrieve the metadata for a specific report
ReportMetadata report = reportMetadata.getReportMetadata(‘00O7i0000017DGQEA2’);

// Set the number of rows to display in the report to the top 10 rows
report.setTopRows(10);

// Update the report metadata
update report;

Tips for working with the ReportMetadata class

To make the use of this class a little bit smoother, here are a few helpful tips:

• Make sure you have the necessary permissions: to use this class properly, you will need the “View Reports” and “Modify All Data” permissions. If you do not have them, you will not be able to access or modify the metadata for reports.
• Use SOQL to retrieve metadata for specific reports: To retrieve metadata for specific reports, you can use a SOQL query with the ReportMetadata object. For example, you can use a query like SELECT Id, Name FROM ReportMetadata WHERE Id = ’00O7i0000017DGQEA2′ to retrieve the metadata for a specific report.
• Use the ReportsMetadata class to call the methods: To use the methods of the ReportMetadata class, you will need to create an instance of the ReportsMetadata class and then call the methods on that instance.
• Error handling – try/catch blocks: If you are working with reports that may not exist or that you do not have access to, you should use try-catch blocks to handle any errors that may occur. This will help to prevent your code from crashing and will allow you to gracefully handle any exceptions that may be thrown.
• Test your code before deploying it: As always, it is nearly mandatory to test your code in a sandbox or Developer Edition environment before deploying it to production if you want to achieve the maximum performance of the code you have written. This will allow you to catch any errors or issues before they affect your users.

Summary

To summarise, the ReportMetadata class lets developers access metadata for reports in Salesforce. It is particularly useful since it gives the capability to modify report metadata in a programmatic way, which comes in handy when building custom report management tools or integrating reports into custom applications. For us developers (unlike admins) this tool turns out to be of use by allowing us to automate report-related tasks and interact with reports without having to use the traditional declarative approach.

References

ReportMetadata Class | Apex Reference Guide | Salesforce Developers

Get Report Metadata | Apex Developer Guide

Run Salesforce Reports in Apex | CloudAnswers