Dynamic Forms Migration

Dynamic Forms Migration

This skill activates when a practitioner needs to migrate from traditional page-layout-driven record pages to Dynamic Forms — placing fields and sections as components in the Lightning App Builder with per-component visibility rules instead of record-type-driven full-layout switching.

Before Starting

Gather this context before working on anything in this domain:

• Confirm Dynamic Forms availability for your target object. Generally available on standard objects (Account, Contact, Opportunity, Lead, Case, custom objects, and most platform objects) since the Spring '24 wave; confirm for the specific object — Tasks, Events, and a small number of system objects still have constraints.
• Inventory page layouts per object: SELECT Id, Name, EntityDefinition.QualifiedApiName, RecordTypeId FROM LayoutAssignment (queryable via Tooling API). Identify how many distinct layouts exist and whether they vary by record type, profile, or both.
• Identify the current Lightning Record Page assignments: per-app, per-profile, per-record-type. The migration changes the Record Detail component on these pages — every assigned page must be touched.
• Confirm Compact Layouts and Quick Action layouts are inventoried separately. Dynamic Forms covers the Record Detail component; the Highlights Panel still uses Compact Layouts, and Quick Actions still reference Page Layouts. These are NOT migrated in scope.
• Check Field-Level Security per profile. Dynamic Forms respects FLS, but the field-visibility filters layered on top can confuse the "why can't I see this field?" debugging. Audit FLS first; layer Dynamic Forms visibility on top.

Core Concepts

1. What Dynamic Forms Replaces — and What It Doesn't

2. The Record Page Migration Path in App Builder

The "Upgrade Now" auto-conversion is the most important migration mechanic. It generates working Dynamic Forms components from the existing Page Layout in seconds — you don't rebuild the layout by hand.

3. Replacing Record-Type-Driven Differentiation

The simplification is meaningful for orgs with 5+ record types per object — managing 5 page layouts becomes managing one page with 5 visibility rules.

4. Field-Visibility Rule Semantics

Dynamic Forms component visibility supports filters on:

These rules are evaluated per component on render. Hidden fields are not present in the DOM at all — security implications below.

5. Field-Level Security vs Dynamic Forms Visibility

FLS is the security layer. Dynamic Forms visibility is a UX layer on top. Hiding a field via Dynamic Forms visibility while granting FLS read access means the user CAN see the value via API, reports, and other surfaces — just not on this Lightning page. Conversely, granting Dynamic Forms visibility while denying FLS results in a "this field is not accessible" placeholder. Always set FLS correctly first; use Dynamic Forms for UX layering.

Common Patterns

Pattern 1: Single Page Layout → Dynamic Forms (Simplest Migration)

When to use: The object has one or two page layouts, no record-type-driven differentiation, simple field visibility needs.

How it works:

1. Open the Lightning Record Page assigned to the object.
2. Click the Record Detail component → "Upgrade Now".
3. Verify the auto-generated Field Section components reproduce the original layout exactly.
4. Save and activate.

Why not the alternative: Building Dynamic Forms by hand is slower and more error-prone than the auto-conversion, even for simple cases.

Pattern 2: Record-Type-Driven Layouts → Single Page with Visibility Rules

When to use: The object has multiple page layouts differentiated by record type. E.g., 3 Account record types each with their own page layout.

How it works:

1. Choose a "primary" Record Type's page layout to convert first via "Upgrade Now."
2. For each additional Record Type's layout, identify the unique fields/sections.
3. Add those unique fields/sections as additional Dynamic Forms components on the same page.
4. Apply visibility rules: RecordType.DeveloperName equals 'X' per component.
5. Test by switching record types on a sample record; verify each record type sees its expected field set.
6. Decommission the per-record-type Page Layouts after sign-off.

Why not the alternative: Maintaining multiple Lightning Record Pages (one per record type) is a valid alternative, but loses the simplification benefit of Dynamic Forms. One page with rules is better when the unique-field count per record type is small (<10 fields).

Pattern 3: Profile-Driven Layouts → Visibility Rules with $User.Profile.Name

When to use: The object has different page layouts assigned to different profiles. E.g., "Sales Rep Layout" hides commission fields shown on "Sales Manager Layout."

How it works:

1. Convert the most-permissive profile's layout via "Upgrade Now."
2. For fields that should be hidden from less-permissive profiles, add visibility rules: $User.Profile.Name not equals 'Sales Rep' (or use a Custom Permission for cleaner abstraction).
3. Test by impersonating each profile; verify visibility matches expectations.

Why not the alternative: Profile-name string matching is brittle (renaming a profile breaks visibility). Prefer Custom Permissions: $Permission.View_Commission_Fields equals true. Custom Permissions are stable identifiers and can be assigned via permission sets, which is more flexible than profile-based matching.

Pattern 4: Hybrid — Dynamic Forms for Detail, Compact Layout for Highlights

When to use: Always (this is the steady-state architecture for a Dynamic Forms record page).

How it works:

1. Highlights Panel still reads from Compact Layout. Configure the Compact Layout to show the right fields (typically 3–5 most-important).
2. Record Detail uses Dynamic Forms components.
3. Quick Actions still reference Page Layouts (the Quick Action layout, not the Page Layout for Record Detail).
4. Acknowledge the dual-management: Compact Layout and Page Layout are still in play even after the Record Detail is on Dynamic Forms.

Why not the alternative: Trying to "migrate everything to Dynamic Forms" leads to confusion when Highlights Panel and Quick Actions don't behave as expected. They are out of scope; document that explicitly.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Inventory page layouts and audit FLS. List all Page Layouts, Record Type assignments, profile assignments, and Lightning Record Page assignments for the target object — identify the dominant layout (becomes conversion source). Run a per-profile FLS report; fix discrepancies BEFORE adding Dynamic Forms visibility rules so the data layer is correct first.
2. Convert via "Upgrade Now" in sandbox. Open the Lightning Record Page; click Record Detail → "Upgrade Now." The auto-generated components mirror the source Page Layout's structure.
3. Add visibility rules for record-type and profile differentiation. Replace the per-record-type / per-profile page layouts with visibility filters. Prefer Custom Permissions over profile-name strings.
4. Compose with non-field components. Dynamic Forms is not just about fields — interleave related lists, custom LWCs, Quick Actions, and Path components in the same canvas to create a richer record page.
5. Test exhaustively and run a user preview. Impersonate each affected profile per record type (Setup → Users → Login as User); verify field visibility on desktop and on real mobile devices. Activate in sandbox and run a 1–2 week preview with selected users.
6. Production rollout. Activate the Dynamic Forms record page in production. Keep at least one minimal Page Layout per object — Salesforce requires it for Quick Actions, Print View, and Classic users.
7. Decommission selectively and document. Retire only Page Layouts no longer assigned to any active surface. Maintain a per-component runbook ("field X visible when Y") in source — visibility rules are not self-documenting.

Review Checklist

Run through these before marking work in this area complete:

• Field-Level Security has been audited per profile and matches expected access at the data layer
• Lightning Record Page has been converted via "Upgrade Now"; auto-generated components match the source Page Layout
• Record-type differentiation has been moved into per-component visibility rules (or split into separate pages if field counts justify it)
• Profile-based visibility uses Custom Permissions (preferred) or $User.Profile.Name (acceptable but brittle)
• Compact Layout has been reviewed; Highlights Panel still configured correctly
• Quick Action layouts have been reviewed; the Quick Action surface still uses Page Layouts
• Mobile rendering verified on real devices for at least one record per record type
• User-impersonation testing completed for each affected profile / record type combination
• Documentation captures per-component visibility rules and their business intent
• Original Page Layouts retained (at least minimally) for Quick Actions, Print View, and Classic users
• Activation rolled out via Lightning Record Page assignment (per-app, per-profile, per-record-type as needed)

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Page Layout still drives Quick Action input fields, Print View, and Salesforce Classic. Migrating Record Detail to Dynamic Forms does NOT migrate Quick Action layouts (which still reference the Page Layout's Quick Action section), Print View (driven by Page Layout), or Salesforce Classic users (who don't see Lightning Record Pages at all). Plan to keep at least one minimal Page Layout per object permanently.

2. Dynamic Forms component visibility is a UI-only filter, not security. Hiding a field via component visibility does NOT prevent the user from accessing it via API, reports, or formulas. FLS is the security layer; Dynamic Forms visibility is for UX organization. Treating Dynamic Forms visibility as a security control creates false confidence in data protection.

3. Hidden fields ARE in the page metadata — but not in the DOM. When a visibility rule hides a field, the field component is excluded from the rendered DOM. This means scripted tests (Selenium, Playwright) that rely on element presence break unpredictably as visibility rules trigger or untrigger. Tests must be visibility-aware or operate via API rather than DOM.

4. Highlights Panel uses Compact Layout, not Dynamic Forms. Admins frequently expect that "the page is Dynamic Forms now" means the Highlights Panel is too. It isn't. The Highlights Panel field set comes from the Compact Layout for the record type. Ensure the Compact Layout has been reviewed alongside the Dynamic Forms migration.

5. Reading View / Read-Only User View renders differently. Reading View (the page rendered for users without edit access, or in some Communities contexts) may render Dynamic Forms differently than the standard edit view — typically simpler, with some component visibility rules behaving differently. Test the Reading View path explicitly for Communities users and read-only profiles.

6. Record-type changes after page render don't re-evaluate visibility. If a user changes a record's RecordType via inline edit on the page, visibility rules that depend on RecordType.DeveloperName re-evaluate only on full page reload — not on the inline-edit save. Users may see stale field visibility briefly. Workaround: refresh the page after record-type changes (Salesforce may improve this in future releases).

7. Visibility rule on a required field can hide it but not relax the validation. A field marked required on the Page Layout (or in Dynamic Forms component properties) remains required even when hidden by visibility rules. The save fails with "Required field missing" — and the user can't see the field to populate it. Fix: never combine "required" + "hidden by visibility" on the same component. Choose one or the other.

8. Migrating an object on a managed-package Lightning Record Page may be blocked. Dynamic Forms migration requires editing the page in App Builder. Pages owned by a managed package cannot be edited; you must clone them to your namespace, migrate the clone, and reassign. This is not a Dynamic Forms-specific limitation but is often discovered for the first time during migration.

Output Artifacts

Related Skills

• admin/dynamic-forms-and-actions — Use for new Dynamic Forms configuration (post-migration) and for Dynamic Actions
• admin/lightning-app-builder-advanced — Use for advanced Lightning Record Page composition patterns (custom LWCs, Path, Related Lists)
• security/field-level-security-design — Use to audit and re-architect FLS BEFORE applying Dynamic Forms visibility
• admin/page-layout-assignment-strategy — Use when planning which Page Layouts to retain for Quick Actions, Print View, and Classic
• lwc/visualforce-to-lwc-migration — Use if some record-page real estate also includes Visualforce components being modernized