Custom Objects, Fields, and the Architecture Conversation
Series: Build a Salesforce Guide App with AI
Page: 2 of 10
Time to complete: 45–60 minutes
Prerequisites: Page 0 (development environment set up), active Salesforce org
Start With the Architecture Conversation
Before touching Setup, have this conversation with Claude. This is the most important step in any AI-assisted build — getting alignment on what you’re building before writing a line of code saves hours of rework later.
Open claude.ai and paste this prompt:
💬 Prompt to paste into Claude:
I’m a Salesforce Admin building an internal guide application inside Salesforce. The app will allow designated admins to create and publish help guides explaining how to use the org. All other users can read the published guides.
I don’t want to use Salesforce Knowledge — it’s already in use for a different purpose in this org.
Before we write any code, I want to design the data model. Please:
- Suggest what custom objects I’ll need and why
- For each object, suggest the key fields
- Explain any tradeoffs in the design
- Ask me any questions you need answered before finalising the design
I’m building this in a Trailhead Developer Edition org. This is my first custom Salesforce app — please explain your reasoning so I understand the decisions being made.
Claude will walk you through a data model design. The key objects you should end up agreeing on are:
Guide__c— the primary object storing guide contentGuide_Topic__c— topics that guides are tagged with, used to surface guides contextually on record pagesGuide_Topic_Assignment__c— a junction object linking guides to topics (allows one guide to have many topics)Guide_Video__c— a child object for videos attached to a guide
If Claude suggests a different structure, ask it to explain the tradeoffs before proceeding. The above structure is what this tutorial uses — you can adapt Claude’s suggestions to match if needed.
Why These Four Objects
Guide__c is straightforward — you need somewhere to store guide content. The key design decision is using a Rich Text Area for the body rather than plain text, which enables formatting, inline images, and HTML content.
Guide_Topic__c exists to create a reusable tagging system. A topic like “Account Management” is created once, then many guides can be tagged with it. This is how the contextual sidebar knows which guides to show on an Account record page — it looks for guides tagged with topics that have Object_API_Name__c = 'Account'.
Guide_Topic_Assignment__c is a junction object — the standard Salesforce pattern for many-to-many relationships. Without it, a guide could only have one topic. With it, a guide about logging a case can be tagged with both “Case Management” (an Object topic) and “Logging Activities” (a Functionality topic).
Guide_Video__c is a child object rather than just a URL field on Guide__c because you might want multiple videos per guide at different positions. Each video record has its own URL, type (YouTube / Vimeo / External Link / Salesforce File), sort order, and description.
Create the Objects in Setup
All of this is done in Setup → Object Manager. No code required for this section.
Guide__c
- Object Manager → Create → Custom Object
| Setting | Value |
|---|---|
| Label | Guide |
| Plural Label | Guides |
| Object Name | Guide |
| Record Name | Guide Title |
| Data Type | Text |
Tick Allow Reports and Track Field History, then click Save.
Now add these fields via Fields & Relationships → New:
| Label | API Name | Type | Notes |
|---|---|---|---|
| Summary | Summary__c |
Text Area(500) | Short description shown on cards |
| Body | Body__c |
Rich Text Area(32768) | Main guide content |
| Status | Status__c |
Picklist | Values: Draft, Pending Approval, Published, Archived. Default: Draft |
| Category | Category__c |
Picklist | Values: Sales, Support, Onboarding, CPQ, Data Management, Productivity, General |
| Audience | Audience__c |
Picklist | Values: User, Admin. Default: User |
| Version | Version__c |
Number(3,1) | Default: 1.0 |
| Read Time Mins | Read_Time_Mins__c |
Number(3,0) | |
| Tags | Tags__c |
Text(255) | Comma-separated keywords for search |
| Video URL | Video_URL__c |
URL | Legacy field — superseded by Guide_Video__c |
| Video Position | Video_Position__c |
Picklist | Values: Top, After Introduction, Bottom |
| Helpful Count | Helpful_Count__c |
Number(6,0) | Default: 0 |
| Is Active | Is_Active__c |
Checkbox | Default: checked |
Set Org-Wide Default to Public Read Only: Setup → Sharing Settings → Edit → find Guide → set to Public Read Only → Save.
💡 Why Public Read Only? This allows all internal users to read published guides without needing explicit sharing rules. The Apex code enforces what they can actually see (published guides only) — the OWD just ensures the records are accessible.
Guide_Topic__c
- Object Manager → Create → Custom Object
| Setting | Value |
|---|---|
| Label | Guide Topic |
| Plural Label | Guide Topics |
| Object Name | Guide_Topic |
| Record Name | Topic Name |
| Data Type | Text |
Fields:
| Label | API Name | Type | Notes |
|---|---|---|---|
| Topic Type | Topic_Type__c |
Picklist | Values: Object, Functionality, Subject, Admin |
| Object API Name | Object_API_Name__c |
Text(255) | e.g. Account, Opportunity |
| Is Active | Is_Active__c |
Checkbox | Default: checked |
💡 Topic Type explained:
- Object — linked to a specific Salesforce object. Set Object API Name to
Account,Opportunityetc. Guides with this topic appear in the sidebar on that object’s record pages.- Functionality — cross-object guides (List Views, Reports, Dashboards). Appear in the Functionality tab of the modal on any record page.
- Subject — general subject matter (Getting Started, Data Hygiene). Used for search and organisation.
- Admin — for admin-specific content that should never appear to regular users.
Guide_Topic_Assignment__c
- Object Manager → Create → Custom Object
| Setting | Value |
|---|---|
| Label | Guide Topic Assignment |
| Plural Label | Guide Topic Assignments |
| Object Name | Guide_Topic_Assignment |
| Record Name | Assignment Name |
| Data Type | Auto Number — Display Format: GTA-{00000} |
Tick Allow Reports, then click Save.
Fields — these are Master-Detail relationships, so create them carefully:
Field 1 — Guide:
- Type: Master-Detail Relationship
- Related To: Guide
- Label: Guide
- Child Relationship Name:
Topic_Assignments
Field 2 — Guide Topic:
- Type: Master-Detail Relationship
- Related To: Guide Topic
- Label: Guide Topic
- Child Relationship Name:
Guide_Assignments
⚠️ Important: The child relationship names
Topic_AssignmentsandGuide_Assignmentsmust match exactly. They’re used in SOQL subqueries later —Topic_Assignments__randGuide_Assignments__r.
Guide_Video__c
- Object Manager → Create → Custom Object
| Setting | Value |
|---|---|
| Label | Guide Video |
| Plural Label | Guide Videos |
| Object Name | Guide_Video |
| Record Name | Video Title |
| Data Type | Text |
Fields:
| Label | API Name | Type | Notes |
|---|---|---|---|
| Guide | Guide__c |
Master-Detail | To Guide__c. Child relationship: Guide_Videos |
| Video URL | Video_URL__c |
Text(500) | ⚠️ Must be Text not URL — URL type rejects ContentDocumentIds |
| Video Type | Video_Type__c |
Picklist | Values: YouTube, Vimeo, External Link, Salesforce File |
| Sort Order | Sort_Order__c |
Number(3,0) | |
| Description | Description__c |
Text Area(500) |
⚠️ Why Text not URL for Video_URL__c? Salesforce’s URL field type validates that the value is a proper URL. Salesforce File ContentDocumentIds (which start with
069) aren’t URLs and will fail validation. Use Text(500) instead.
Create Your First Guide Topics
Before you can test the app later, you need some topic records. Create these now:
-
Go to App Launcher → Guide Topics (If the tab isn’t visible, go to Setup → Tab → New → Guide Topic and create a tab first)
-
Create the following records:
| Topic Name | Topic Type | Object API Name |
|---|---|---|
| Account Management | Object | Account |
| Opportunity Management | Object | Opportunity |
| Case Management | Object | Case |
| List Views | Functionality | (leave blank) |
| Reports | Functionality | (leave blank) |
| Getting Started | Subject | (leave blank) |
Check Your Work
Before moving to Page 3, confirm all four objects appear in Object Manager:
- ✅ Guide — 12 custom fields including Status, Audience, Body, Is Active
- ✅ Guide Topic — 3 custom fields including Topic Type and Object API Name
- ✅ Guide Topic Assignment — 2 master-detail fields, child relationship names correct
- ✅ Guide Video — 5 fields, Video URL is Text(500) not URL type
- ✅ Guide__c OWD set to Public Read Only
- ✅ At least 6 Guide Topic records created
If everything looks right, move to Page 3 — the approval process.