Related lists
Child records, as rows, on the parent’s payload — what turns a flat field list into a 360.
Add one
In the entity builder, click + Add Related List under Related Objects.
| Setting | What it does |
|---|---|
| Related List | The child relationship. Named relationships and lookup-based ones both appear |
| Label | What the agent calls it. “Open Opportunities” beats “Opportunities” if it’s filtered |
| Columns | Which level of the child entity supplies the columns |
| Sort By / Direction | Which field orders the rows |
| Max Rows | How many rows come back |
| Filters | Which rows qualify |
Related lists render at detailed only — rows × fields is expensive. For a summary at a leaner level, use a metric.
Columns come from the child
A related list’s columns are the child entity’s curated fields at the level you pick — they are not configured on the parent. If Contacts under an Account show the wrong columns, edit the Contact entity’s list fields; that changes every table Contacts appear in. A child object with no entity has nothing to curate from — give it an entity first.
For Columns, list is almost always right. standard is occasionally justified for one high-value relationship; detailed is 30 fields × N rows — avoid it.
Files
Files attached to a record come through the Document entity, shipped on ContentDocumentLink. Opportunity and Account carry a Files list out of the box — newest first, five rows. Add it to any other entity the same way you’d add any related list: pick ContentDocumentLinks as the relationship.
Each row is the file’s name, type, size and a download link. Contents are never inlined. A 1.5 MB PDF costs about 35 tokens as a link; inlined it would cost roughly 710,000 — far beyond any payload budget — and Apex cannot extract text from a PDF anyway. The agent hands over the link; a person with a Salesforce session opens it.
IMPORTANT
Use ContentDocumentLinks, not a ContentVersion list. ContentVersion’s only link to a record is where the file was first uploaded, so a file uploaded elsewhere and attached here is invisible — the list reports zero documents when there are documents, which is worse than showing none. It also returns one row per version.
Filter aggressively
An unfiltered list bloats the payload and buries the relevant rows.
| Instead of | Use |
|---|---|
| All Opportunities | Open Opportunities — IsClosed = false |
| All Cases | Open Cases — IsClosed = false |
| All Activities | Last 90 days — ActivityDate ≥ LAST_N_DAYS:90 |
| All Contacts | Usually fine — contacts per account are few |
The filter builder offers the child object’s fields with operators =, !=, <, <=, >, >=, IN, and LIKE. Date fields accept literals like THIS_QUARTER, LAST_N_DAYS:90, and TODAY. → Filters
Name the list for what it now contains — a list filtered to open deals but labeled “Opportunities” reads as everything.
Two lists over the same child object with different filters is allowed, and often better than one mixed list: Open Cases (5 rows, newest first) and Recently Closed Cases (3 rows, newest first).
Set max rows
Keep it small — five to ten covers most questions. The payload marks a list as truncated when there were more, so the agent can say the list is partial. If the honest answer is “there are 340 of these”, that’s a metric; the best lists pair with one — “Open Cases: 34” alongside the five most recent.
Sort
Sort By picks the field; Direction picks ascending or descending. Default is last modified, newest first. Sort so the top rows are the most useful ones — newest activity, largest amount, soonest close date.
Related list, metric, or reference?
| You want | Use |
|---|---|
| The actual rows, to reason about individually | Related list |
| A count or total | Metric |
| A parent record’s details | Reference |
The most common fix for an oversized payload is converting a related list nobody reads row-by-row into a metric.