User-defined report templates

Report templates are the first step in creating user-defined reports (My Reports). A template defines the format, report types, fields, metrics, and conversion pixel metrics that your scheduled reports will include. You can build templates in two ways: through the Platform UI or programmatically with the GraphQL API. If you create templates through the API, you must use GraphQL. Here's what you can do when creating report templates:

Choose the report types and customize its columns (fields and metrics), which are available to your account.
Create multiple tabs within a report.
Create reports in excel pivot table format.

Create a report template

The following table lists the tasks for creating report templates.

Step	Task	Operation	Notes
1	Retrieve the report types that are available to you.	`reportTypes` query	Take note of the ID of the report type you want to use. You will use it to create the template in the following steps.
2	Retrieve the columns and metrics of the report type you want to generate.	`reportType` query `reportTypes` query	Use this query to decide which columns to include in the report template. Be sure to have the ID of the report type you want to use.
3	Generate a report template.	`myReportsTemplateCreate` mutation	Be sure to have the ID of the report type and the IDs of each column you want to include in the report template.

The following sections provide instructions for each step.

Retrieve available report types

To retrieve a list of report types you can use to create a template, use the GraphQL reportTypes query and include the file format you want to use for the report.

query GetExcelReportsExample {
  reportTypes(input: { format: EXCEL }) {
    id
    name
    deprecationDate
  }
}

TIP: Take note of the ID of the report type you want to use. You will use it to create the template in the following steps.

Retrieve the columns and metrics for a report type

To retrieve the fields, metrics, and conversion pixel metrics available in a report type, use the GraphQL reportType query and include the ID of the report type you want to use.

query GetFieldsAndMetricsForReportType {
  reportType(input: { format: EXCEL, reportTypeId: "REPORT_TYPE_ID_PLACEHOLDER" }) {
    queryableDataAgeInDays
    fields {
      nodes {
        id
        name
      }
    }
    metrics {
      nodes {
        id
        name
      }
    }
    conversionMetrics {
      nodes {
        id
        name
      }
    }
  }
}

TIP: To retrieve columns and metrics from multiple report types, use the GraphQL reportTypes query.

When generating a report template, you must specify the columns you want in your report.

Generate a report template

To create a report template, use the GraphQL myReportsTemplateCreate mutation and include the following IDs retrieved from the preceding steps:

The ID for each report type you want to use.
The ID of each column and metric you want to include in the template.

TIP: To create multiple tabs within the report, include multiple resultSets objects. A report template can have more than one report type.

Here's an example of a GraphQL myReportsTemplateCreate mutation for creating an Excel report template with multiple tabs in the report.

mutation {
  myReportsTemplateCreate(
    input: {
      name: "REPORT_TEMPLATE_NAME_PLACEHOLDER"
      format: EXCEL
      resultSets: [
        {
          name: "Performance Report - 100 Days"
          reportTypeId: "REPORT_TYPE_ID_PLACEHOLDER"
          fields: [
            { columnId: "21", columnOrder: 1, includedInPivot: true }
            { columnId: "1", columnOrder: 2, includedInPivot: false }
          ]
          metrics: [
            { columnId: "4158", columnOrder: 3, includedInPivot: true }
            { columnId: "7", columnOrder: 4, includedInPivot: true }
            { columnId: "25", columnOrder: 5, includedInPivot: true }
          ]
        }
        {
          name: "Data Element Report"
          reportTypeId: "2"
          fields: [
            { columnId: "10", columnOrder: 1, includedInPivot: false }
            { columnId: "49", columnOrder: 2, includedInPivot: false }
          ]
          metrics: [
            { columnId: "19", columnOrder: 3, includedInPivot: false }
            { columnId: "160", columnOrder: 4, includedInPivot: false }
          ]
        }
      ]
    }
  ) {
    data {
      id
    }
    errors {
      __typename
      ... on MutationError {
        field
        message
      }
    }
  }
}

After you create a report template, you can use its ID to set up a report schedule. For details, see User-defined report schedules.

Report template management tasks

After you create a report template, you can retrieve its structure and ID, and update it with a new structure, if needed. The following table lists the management tasks for report templates.

Task	Operation Name	Notes
Retrieve a list of all report templates available to you.	`reportingTemplates` query	None.
Update a report template.	`myReportsTemplateUpdate` mutation	Updating the report structure completely replaces its existing structure. If there are fields and metrics you would like to continue using, be sure toprovide those in the new structure.
Retrieve the available columns and metrics of a specific report template.	`derivedReportTemplate` query	Use this query to retrieve the entire structure of a report template and determine if the report template includes a report type, fields, or metrics that are unavailable.

The following sections provide examples and guidelines for managing report templates.

Retrieve all report templates

Here's a GraphQL reportingTemplates query example for retrieving the report templates that are available for you.

query GetAvailableReportTemplatesExample{
  reportingTemplates (first: 10){
    pageInfo {
      startCursor
      hasNextPage
      endCursor
    }
    nodes {
      id
      name
      userGenerated
      createdBy
      format
    }
  }
}

To use a template to schedule reports, take note of the report template ID in the response.

Update a report template

To update an existing report template, use the GraphQL myReportsTemplateUpdate mutation and include the report template ID. For details about how to retrieve the template ID, see Retrieve all report templates.

IMPORTANT: The updated report structure completely replaces the existing structure. If there are fields and metrics you would like to continue using, be sure to provide those in the new structure. For details on retrieving the current structure of a report, see Retrieve the columns and metrics for a report type.

Here's an example myReportsTemplateUpdate mutation that shows how to update a report template with additional columns.

mutation {
  myReportsTemplateUpdate(
    input: {
      id: "REPORT_TEMPLATE_ID_PLACEHOLDER"
      name: "REPORT_NAME_PLACEHOLDER"
      resultSets: [
        {
          name: "Tab 1"
          reportTypeId: "60"
          fields: [
            { columnId: "10", columnOrder: 1, includedInPivot: true }
            { columnId: "1", columnOrder: 2, includedInPivot: false }
          ]
          metrics: [
            { columnId: "7", columnOrder: 3, includedInPivot: true }
            { columnId: "25", columnOrder: 4, includedInPivot: true }
            { columnId: "58", columnOrder: 5, includedInPivot: true }
          ]
        }
        {
          name: "Tab 2"
          reportTypeId: "10"
          fields: [
            { columnId: "10", columnOrder: 1, includedInPivot: false }
            { columnId: "2078", columnOrder: 2, includedInPivot: false }
          ]
          metrics: [
            { columnId: "2195", columnOrder: 3, includedInPivot: false }
          ]
        }
      ]
    }
  ) {
    data {
      id
    }
    errors {
      __typename
      ... on MutationError {
        field
        message
      }
    }
  }
}

Retrieve report template structure

To retrieve the structure of the fields and metrics in the report template, use the GraphQL derivedReportTemplate query and include the report template ID.

query MyReportsTemplateRetrieve {
  derivedReportTemplate(id: "REPORT_TEMPLATE_ID_PLACEHOLDER") {
    __typename
    ... on MyReportsGetDerivedTemplateResponse {
      requestedReportTemplateId
      partialAccess
      name
      reportFormatType
      resultSets {
        reportType {
          id
          name
          filters {
            id
            name
          }
        }
        fields {
          columnType {
            id
            name
          }
          columnOrder
          includedInPivot
          isOverlapColumn
        }
        metrics {
          columnType {
            id
            name
          }
          columnOrder
          includedInPivot
          isOverlapColumn
        }
        conversionMetrics {
          columnType {
            id
            name
          }
          columnOrder
          includedInPivot
          isOverlapColumn
        }
      }
    }
    ... on MutationError {
      field
      message
    }
  }
}

FAQs

The following is a list of frequently asked questions about report templates.

Is there a limit to the number of tabs I can add to a template?

Yes. You can add up to 29 tabs to a report template.

How can I tell if a report contains fields and metrics that are no longer available to me?

In a GraphQL derivedReportTemplate query, include the template ID and the partialAccess field. If the response returns the partialAccess value as true, then the report template has metrics and fields that are no longer available. See also Retrieve report template structure.

How do I retrieve the entire structure of a report template?

Use the GraphQL derivedReportTemplate query. For details, see Retrieve report template structure.

How do I create a geofence performance report?

To create a report that contains your individual geofence shapes, contact your Technical Account Manager and request access. After you have access, use the reportTypes query to search for the Geofence Performance Report template, then use its report type ID to generate the report.