5.1 Choosing the Right Grounding Technique
Key Takeaways
- Record merge fields such as {!$Input:Account.Name} are the simplest grounding for fields on the template's input record and its lookups.
- Flow grounding (template-triggered prompt flows) suits filtered, looped, or aggregated data, and all flow inputs must be present in the template.
- Apex grounding suits complex logic or external data, and Apex inputs are optional unless annotated as required.
- Retrievers ground prompts with relevant chunks from Data 360 search indexes; their search text is limited to globals and prompt inputs, up to 255 characters.
- Grounding is dynamic and secure: data is retrieved at run time using the permissions of the user executing the prompt.
5.1 Choosing the Right Grounding Technique
Quick Answer: Grounding gives the LLM the specific, current data it needs. In Prompt Builder you can ground with record merge fields, related lists, flows, Apex, Data 360 objects, retrievers (unstructured knowledge in Data 360 search indexes), and, for some types, files or data graphs. Pick the simplest technique that returns exactly the data the prompt needs: fields for one record, flows for filtered or aggregated data, Apex for complex or external data, and retrievers for knowledge and documents.
Why Grounding Matters
Without grounding, responses contain generic or irrelevant details, or hallucinated facts. Grounding supplies context such as the account's tier, the open cases, or the policy article, so the response is personal and accurate. Salesforce also stresses that sensitive data stays in Salesforce: grounding happens inside the platform, and the Trust Layer's zero-data retention agreements mean data shared with external LLMs isn't stored or used for training.
The Grounding Toolbox
| Technique | Syntax or resource | Best for | Watch out for |
|---|---|---|---|
| Record merge fields | {!$Input:Account.Name}, lookup traversal such as {!$Input:Case.Account.Industry} | Fields on the input record and its parents | Too many fields add noise; only fields the user can see resolve |
| Related lists | Related list resource on the input object | Simple child-record context, such as recent activities | Limited filtering and shaping |
| Flow | {!$Flow:Get_Open_Cases_for_Account} (a template-triggered prompt flow) | Filtered, looped, formatted, or aggregated data declaratively | All flow inputs are treated as required and must exist in the template; deploy with Manual Inputs |
| Apex | {!$Apex:OpenCasesPrompt} (invocable method returning prompt text) | Complex logic, calculations, callouts to external data | Inputs are optional unless annotated as required; packaged classes must be global |
| Data 360 DMO | DMO resources in the template | Harmonized, unified customer data | Requires Data 360 access |
| Retriever | Individual, ensemble, or web retriever resource | Knowledge articles, PDFs, transcripts, and other chunked content | Search text is limited to globals and prompt inputs, 255 characters; needs Data Cloud User |
| Data graph | Data graph resource (for example in Sales Email templates) | Precomputed related data from Data 360 | Requires a configured data graph |
| File inputs | File resource in Flex templates | Grounding on an uploaded document | Flex-specific |
| Prompt template action | Output of another active template | Reusing a summary or classification step | Adds another LLM call |
A template works with flows or Apex whose required inputs are a subset of the template's inputs. Flows and Apex with no parameters work with all templates.
Choosing: A Decision Guide
- Is the data on this record or a parent? Use merge fields.
- Do you need a filtered or formatted set of child records (for example open cases from the last 90 days, as bullet text)? Use a flow.
- Do you need heavy logic, calculations, or an external system's data? Use Apex.
- Is the answer inside unstructured content such as knowledge articles, manuals, or transcripts? Use a retriever over a Data 360 search index.
- Is the data unified from many sources in Data 360? Use DMOs or data graphs.
Grounding Examples
Merge fields (simple)
You are an account manager at {!$Input:Account.Owner.CompanyName}.
Write a two-sentence renewal reminder for {!$Input:Account.Name},
whose contract ends on {!$Input:Account.Contract_End_Date__c}.
Flow grounding (filtered list)
A template-triggered prompt flow takes the Account as input, gets cases where Status is not Closed, loops through them, and uses the Add Prompt Instructions element to append lines such as "Case 00123: printer jam, High priority." The template references {!$Flow:Get_Open_Cases_for_Account}. At resolution, the flow's text response is inserted into the prompt.
Apex grounding (calculated or external)
An invocable Apex method returns a formatted string with the customer's payment risk score from an external service. The template inserts {!$Apex:PaymentRiskContext}. Mark only truly required inputs as required, because optional Apex inputs don't need to exist in the template.
Retriever grounding (knowledge)
A Field Generation template on Case inserts a retriever resource and sets:
- Search Text:
{!$Input:Case.Subject}plus free text, within the 255-character limit - Output Fields: only the chunk text and article title
- Number of Results: 5
If the retriever has a dynamic filter, a Pre-filter field appears in Template Settings. You can bind it to a prompt input, such as the case's product line, so only that product's articles are searched.
Grounding for Agents
Agents usually ground in two ways:
- Answer Questions with Knowledge with an assigned Agentforce Data Library handles retrieval-augmented answers with citations.
- Actions and variables load record data deterministically, for example
run @actions.get_orderthenset @variables.order_summary, and insert it with template expressions.
When an agent calls a prompt template action, that template's own grounding (merge fields, flows, retrievers) runs as part of the action.
Secure, Dynamic Grounding
Every technique follows the Trust Layer's secure data retrieval:
- Data is retrieved at run time, based on the permissions of the user executing the prompt. For a Service agent, that's the agent user.
- Field-level security and role-based controls are preserved for CRM and Data 360 grounding.
- Retrievers apply row-level access checks, so inaccessible records don't appear.
Common Grounding Mistakes
| Mistake | Symptom | Better approach |
|---|---|---|
| Grounding with 40 account fields "just in case" | Long, unfocused responses | Include only fields the task needs |
| Using merge fields to list child records | Missing or messy child data | Use a flow that filters and formats |
| Using a retriever for a single known field value | Unnecessary search and credit use | Use a merge field |
| Search text references a flow output | The retriever can't use it | Search text supports only globals and prompt inputs |
| Template-triggered flow deployed with Automatic Inputs | Deployment fails | Use Manual Inputs and deploy the flow with the template |
Exam Traps
- "Unstructured documents" means a retriever and Data 360 search index, not merge fields.
- "Aggregate or filter related records" means a flow, not a related list dump.
- "External system data or complex computation" means Apex.
- Grounding can't bypass FLS. If the executing user can't see it, the prompt doesn't get it.
A Field Generation template must summarize only the Account's open cases from the last 90 days as a bulleted list. Which grounding technique is most appropriate?
What limitation applies to a retriever's Search Text field in a prompt template?
A template must include a customer's credit risk score retrieved from an external risk service and calculated with custom logic. Which grounding option fits best?
A Service agent runs a prompt template action that grounds with a custom field the agent user can't read. What happens?