Create and Update Reports

The Reports service for the DCM/DFA Reporting and Trafficking API allows you to create and update Report Builder reports using report resource objects. A report resource outlines basic information about a report to be run, as well as the structure of the report output.

This guide details how to programmatically create and update Report Builder reports via the Reports service.

Configure a report resource

The first step in creating or updating a Report Builder report is to configure a report resource object. If you're creating a new report, you'll start with an empty resource and set the necessary fields. If you're updating an existing report, you have a choice of:

  1. Preferred: Performing a partial update. Using this approach, you'll start with an empty resource and set the fields you'd like to change. A partial update only saves changes to fields you specify.
  2. Performing a full update. Using this approach, you'll load an existing report resource and directly modify its fields. A full update always saves all of the report's fields.

The exact contents of a report resource vary depending on the type of report you're configuring. Even so, there are a few fields that are common to all report types:

FieldDescription
Required fields
nameThe name of the report.
typeThe type of the report.
Optional fields
deliveryThe report's email delivery settings.
fileNameThe filename used when generating report files for this report.
formatThe output format of the report, either CSV or Excel.
scheduleA schedule used to run your report on a recurring basis.

These common fields make up the skeleton of your report. The example below illustrates the creation of a new standard report resource:

Java

Report report = new Report();

// Set the required fields "name" and "type".
report.setName("Example standard report");
report.setType("STANDARD");

// Set optional fields
report.setFileName("example_report");
report.setFormat("CSV");

Define the report criteria

Once you've chosen a report type and configured common fields, the next step is to define the report criteria. The report criteria are used to limit the scope of your report, ensuring only relevant information is returned. It also defines the structure of the report output.

The criteria used depends on the type of report. The relationship between report type and criteria is explained in the following table:

Report type Criteria field
STANDARD criteria
REACH reachCriteria
PATH_TO_CONVERSION pathToConversionCriteria
FLOODLIGHT floodlightCriteria
CROSS_DIMENSION_REACH crossDimensionReachCriteria

While each of these type-specific criteria expose a slightly different set of fields, there is a set of common criteria fields that are generally useful for controlling report output:

Field Description
dateRange The dates for which this report should be run. Can be used to specify either a custom start and end date or a relative date range. Note that dates in the Reporting UI may be displayed relative to your local timezone while dates in the reporting portion of the API are always relative to the reporting timezone configured in DCM. This includes relative date ranges like YESTERDAY. Something to watch out for if you're located in a different timezone than the DCM account.
dimensionFilters A list of filters that restrict the results returned. See the query filter values section for more information on configuring filters.
dimensions A list of DCM elements to include in the report output.
metricNames Standard units of measure to include in the report output.

See the section on determining field compatibility for more information on choosing dimensions, metrics, and filters for your report. Additional type-specific criteria fields are explained in the reference documentation and the help center.

The example below adds a basic criteria to our standard report resource:

Java

// Define a date range to report on. This example uses explicit start and end dates to mimic
// the "LAST_MONTH" relative date range.
DateRange dateRange = new DateRange();
dateRange.setEndDate(new DateTime(true, System.currentTimeMillis(), null));

Calendar lastMonth = Calendar.getInstance();
lastMonth.add(Calendar.MONTH, -1);
dateRange.setStartDate(new DateTime(true, lastMonth.getTimeInMillis(), null));

// Create a report criteria.
Report.Criteria criteria = new Report.Criteria();
criteria.setDateRange(dateRange);
criteria.setDimensions(Lists.newArrayList(new SortedDimension().setName("dfa:advertiser")));
criteria.setMetricNames(Lists.newArrayList("dfa:clicks", "dfa:impressions"));

// Add the criteria to the report resource.
report.setCriteria(criteria);

Query filter values

When configuring filters for a report, you need to specify the exact values that the filters will use to restrict the report output. If you aren't sure what the possible values for a particular filter are, look them up using the DimensionValues service.

A basic dimension values query contains a dimension name, as well as a start date and end date. The start and end dates limit the response to values valid within that time period. Additional filters can be specified if you need to limit the query results further.

The below example looks up valid advertiser filter values during the dates that our report will run and adds them to the report criteria:

Java

// Query advertiser dimension values for report run dates.
DimensionValueRequest request = new DimensionValueRequest();
request.setStartDate(report.getCriteria().getDateRange().getStartDate());
request.setEndDate(report.getCriteria().getDateRange().getEndDate());
request.setDimensionName("dfa:advertiser");

DimensionValueList values = reporting.dimensionValues().query(profileId, request).execute();

if (!values.getItems().isEmpty()) {
  // Add a value as a filter to the report criteria.
  List<DimensionValue> filters = Lists.newArrayList(values.getItems().get(0));
  report.getCriteria().setDimensionFilters(filters);
}

Determine field compatibility

When configuring your report criteria, it's important to remember that not all combinations of metrics, dimensions, and filters are valid. You won't be allowed to save a report that contains an invalid combination, so it's important to ensure the fields you plan to use are compatible with one another.

As you build your report resource, you can pass it into the Reports.compatibleFields service to see which fields are valid given the ones you've already selected. The configuration of the report will be analyzed, and a response containing the compatible dimensions, metrics, and filters will be returned. Since the fields in this response are not all guaranteed to be compatible with one another, you may need to make multiple requests to ensure all the fields you choose will work together.

The example below illustrates how to make a sample compatible fields request, using our report resource as input:

Java

CompatibleFields fields = reporting.reports().compatibleFields()
    .query(profileId, report).execute();

ReportCompatibleFields reportFields = fields.getReportCompatibleFields();

if (!reportFields.getDimensions().isEmpty()) {
  // Add a compatible dimension to the report.
  Dimension dimension = reportFields.getDimensions().get(0);
  SortedDimension sortedDimension = new SortedDimension().setName(dimension.getName());
  report.getCriteria().getDimensions().add(sortedDimension);
} else if (!reportFields.getMetrics().isEmpty()) {
  // Add a compatible metric to the report.
  Metric metric = reportFields.getMetrics().get(0);
  report.getCriteria().getMetricNames().add(metric.getName());
}

Save the report

The final step in this process is to save your report resource. If you're creating a new report, you can insert it with a call to Reports.insert:

Java

Report insertedReport = reporting.reports().insert(profileId, report).execute();

If you're performing a partial update, you can save your changes by calling Reports.patch:

Java

// Patch an existing report.
Report patchedReport = reporting.reports().patch(profileId, reportId, report).execute();

Or, if you've decided to perform a full update, you can save your changes by calling Reports.update:

Java

// Update an existing report.
Report updatedReport = reporting.reports().update(profileId, report.getId(), report).execute();

After a successful save request, a copy of the report resource will be returned in the response body. This resource will have a few new fields filled out, the most important of which is the id field. This id is what you will use to refer to this report throughout the rest of your workflow.

Send feedback about...

DoubleClick Campaign Manager
DoubleClick Campaign Manager