Working with reports


Summary
This topic introduces the Desktop-only ArcObjects application programming interface (API) for generating reports.


About working with reports

Reports are a great way to present attribute information in a well-organized and stylized format. Reports can be generated using most datasets that contain attribute information, including feature layers, raster catalog layers, and stand-alone tables.
To automate the creation of a report, you need to create a report layout file (.rlf) using ArcMap. The .rlf can be thought of as a template that can be used with different datasets. However, when using different datasets with the .rlf, you need to map the fields used in the .rlf to fields from the data source.
The following interfaces can be used to generate a report:
  • IReportDataSource—Sets the data source of the report.
  • IReportTemplate—Specifies the .rlf and, optionally, modifies the starting page of the report.
  • IReportEngine—Includes the methods for running reports and exporting the report to various formats.

IReportDataSource

To generate a report, you must first specify a data source. The data source for a report can be a layer, table, or map document. Optionally, you can use a selection set, definition expression, or an extent to filter the data source. You cannot combine multiple filters on the data source; if you do, the most recent filter set will be used.
The IReportDataSource interface includes the following properties:
  • DefinitionQuery—Specifies a definition query on the report’s data source. If the data source is a layer that already has a definition query defined, this definition query will be appended to the one already set. If the .rlf includes a definition query, this property can be used to overwrite the query from the .rlf.
  • Extent—Specifies an extent on the report’s data source.
  • Layer—Specifies the layer to use as the report’s data source.
  • SelectionSet—Specifies a selection set on the report’s data source.
  • Table—Specifies the table to use as the report’s data source.

IReportTemplate

The IReportTemplate interface allows you to access a .rlf and modify some of its properties. Once you have defined a data source for your report, you need to load a report template.
The IReportTemplate interface includes the following property and methods:
  • FieldMapping—Sets the field mapping from the report template to the new data source.
  • LoadReportTemplate—Loads the report template file.
  • RelatedReportMapping—Sets the relationship mapping from the report template to the new relationship.
  • ReportTitle—Indicates the title for the report.
  • SaveReportTemplate—Saves the report template file.   
  • StartingPageNumber—Indicates the starting page number for the report.
The following are additional tips for working with FieldMapping:
  • If the data source in the .rlf has not changed, FieldMapping is not required.
  • FieldMapping is case sensitive.
  • Only fields that are used in the report need to be mapped.
  • Fields that are mapped need to be of the same type (that is, String to String).
  • The list of fields can be viewed in a text editor by opening the .rlf and looking at the ReportFields section.
The following are additional tips for working with RelatedReportMapping:
  • If the .rlf does not contain a RelatedReport, you cannot add a RelatedReport.
  • The first parameter of the RelatedReportMapping function is the name of the related report.  Each RelatedReport includes a unique Report Name property (for example: RelatedReport1, RelatedReport2).  You can look up this name by loading the .rlf in ArcMap and clicking on the RelatedReport and viewing its properties.

IReportEngine

The IReportEngine interface is used to generate the report and to export the report to a standard format. You need to define your data source and report template before you can generate a report for export. Reports can be exported to the following formats:
  • Hypertext Markup Language (HTML)
  • Portable Document Format (PDF)
  • Rich text format (RTF)
  • Tagged image file format (TIFF)
  • Text file (TXT)
  • Microsoft excel file format (XLS)
The IReportEngine interface includes the following methods:
  • ExportReport—Exports a generated report into the chosen format.
  • RunReport—Generates the report.
The following are additional tips for generating reports:
  • You can specify a range of report pages to export by specifying a page range when using the ExportReport method. To export all pages of the report, set the page range to an empty string.
  • File types are controlled by the esriReportExportType enumeration; the report type is a required parameter for exporting.
The following code example shows how to generate a report:
[C#]
IMxDocument mxDoc = (IMxDocument)ArcMap.Application.Document;
IReportDataSource rDS = new Report();
rDS.Layer = mxDoc.FocusMap.get_Layer(0);
IReportTemplate rwTemplate = (IReportTemplate)rDS;
rwTemplate.StartingPageNumber = 1;
rwTemplate.ReportTitle = "County Populations in 2010";
String templateFieldList = "STATENAME,POP2009,DEN2009";
String sourceFieldList = "COUNTYNAME,POP2010,DEN2010";
Boolean isOK = rwTemplate.FieldMapping(templateFieldList, sourceFieldList);
Boolean b = rwTemplate.LoadReportTemplate(@"C:\PopulationTemplate.rlf");
if (b)
{
    IReportEngine rwEngine = (IReportEngine)rDS;
    rwEngine.RunReport(null);
    String pdfReport = (@"C:\CountyPop2010.pdf");
    rwEngine.ExportReport(pdfReport, "", esriReportExportType.esriReportExportPDF);
}
[VB.NET]
Dim mxDoc As IMxDocument = ArcMap.Application.Document
Dim rDS As IReportDataSource = New Report()
rDS.Layer = mxDoc.FocusMap.Layer(0)
Dim rwTemplate As IReportTemplate = rDS
rwTemplate.StartingPageNumber = 1
rwTemplate.ReportTitle = "County Populations for 2010"
Dim templateFieldList As String = "STATENAME,POP2009,DEN2009"
Dim sourceFieldList As String = "COUNTYNAME,POP2010,DEN2010"
Dim isOK As Boolean = rwTemplate.FieldMapping(templateFieldList, sourceFieldList)
Dim b As Boolean = rwTemplate.LoadReportTemplate("C:\PopulationTemplate.rlf")
If b Then
    Dim rwEngine As IReportEngine = rDS
    rwEngine.RunReport(Nothing)
    Dim pdfReport As String = ("C:\CountyPop2010.pdf")
    rwEngine.ExportReport(pdfReport, "", esriReportExportType.esriReportExportPDF)
End If


See Also:

Sample: Generate a report




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced