Platform Custom Report Type Generate

Specification

Salesforce Custom Report Type Metadata Knowledge

Overview

Custom Report Types (CRTs) define the data framework for Salesforce reports. They specify a primary object, up to 3 related objects, the relationship (join) between them, and which fields are available in the report builder.

Purpose

• Enable reporting across custom objects and custom relationships not covered by standard report types
• Curate a focused set of fields for report builders (including fields reached via lookup)
• Control inner/outer join behavior to include or exclude primary records without related records

Configuration

File extension: .reportType-meta.xml. The file basename is the report type's developer name (e.g. AccountsWithProjects.reportType-meta.xml). Each CRT is a single file, not nested under an object folder.

Key Elements

Top-level <ReportType> children:

<sections> (group of columns) sub-elements:

<columns> (single field) sub-elements:

Critical Rules (Read First)

Rule 1: If <fullName> Is Present, It Must Match the File Name

In source format, fullName is inherited from Metadata and derived from the file name, so the <fullName> element is technically optional. The repo convention is to include it. If you include <fullName>, its value must equal the file name (everything before .reportType-meta.xml) exactly — same characters, same casing, same underscores.

Wrong — file name and <fullName> differ:

• File: account_projects.reportType-meta.xml
• <fullName>AccountProjects</fullName> (Mismatch: file uses account_projects, fullName uses AccountProjects)

Right — file name and <fullName> are identical:

• File: AccountProjects.reportType-meta.xml
• <fullName>AccountProjects</fullName>

Rule 2: Join Semantics — outerJoin Controls Inclusion

Each <join> block has an <outerJoin> element that determines which primary records appear in the report:

Default when unspecified: Use true (outer join) when the user wants to see all primary records regardless of children. Use false when the report only makes sense if children exist.

Rule 3: Each Object Needs Its Own <sections> Block

Every object in the CRT (primary + each joined object) must have a corresponding <sections> block that lists the fields exposed for reporting. Without a section for an object, none of its fields appear in the report builder.

• <masterLabel> on each section is the section heading in the report builder
• <columns> entries list the fields — each with a <field> (API name) and <table> (object API name)
• For fields reached via lookup, use the relationship path in <field> (e.g. Owner.Name with <table> set to the owning object)

Rule 4: Field API Names, Not Labels

Use exact API names for fields: standard fields use their defined names (Name, CreatedDate, OwnerId), custom fields use Field__c. Custom objects must include __c.

Wrong:

• <field>Account Name</field>

Right:

• <field>Name</field> with <table>Account</table>

Rule 5: Relationship Path for Joined Objects

When adding a <join>, the <relationship> element must use the child relationship name as defined on the lookup/master-detail field pointing from the child object to the parent. For custom relationships, this typically ends in __r.

Wrong:

• <relationship>Project</relationship> (for a custom child relationship)

Right:

• <relationship>Projects__r</relationship> (child relationship name)
• <relationship>Contacts</relationship> (standard, non-custom child relationship)

Rule 6: Maximum 4 Objects Total in a Join Chain

A single CRT can join a maximum of four objects total (the base object + up to 3 additional objects via nested <join> blocks).

Rule 7: No Inner Join After an Outer Join

Once the join chain contains an outer join (<outerJoin>true</outerJoin>), every subsequent nested join must also be an outer join. An inner join that follows an outer join earlier in the sequence is not allowed.

Wrong:

<join>
    <outerJoin>true</outerJoin>        <!-- outer join first -->
    <relationship>Contacts</relationship>
    <join>
        <outerJoin>false</outerJoin>   <!-- WRONG: inner join after outer -->
        <relationship>Assets</relationship>
    </join>
</join>

Right:

<join>
    <outerJoin>true</outerJoin>
    <relationship>Contacts</relationship>
    <join>
        <outerJoin>true</outerJoin>    <!-- outer stays outer -->
        <relationship>Assets</relationship>
    </join>
</join>

Rule 8: <table> for Joined Objects Uses Dotted Path

In <sections>, the <table> element identifies which object in the join chain each column belongs to. For the base object, use the object name directly (e.g. Account). For joined objects, use the dotted relationship path from the base object.

Rule 9: Field Paths Can Traverse Lookups

<field> values may reference fields reached via lookup relationships using dot notation — for example Owner.Email (owner User's email) or ReportsTo.CreatedBy.Contact.Owner.MobilePhone. The <table> must still be the object that owns the starting field.

Rule 10: Historical Trending Fields Use _hst Suffix

For a field with trackTrending=true, the API name in <field> and <table> uses the _hst suffix:

<columns>
    <checkedByDefault>false</checkedByDefault>
    <field>Field2__c_hst</field>
    <table>CustomTrendedObject__c.CustomTrendedObject__c_hst</table>
</columns>

Rule 11: Primary Object Cannot Be Changed After Deployment

Once deployed, the <baseObject> of a CRT is locked. To change the primary object, create a new CRT and retire the old one.