Home / admin / global-actions-and-quick-actions
global-actions-and-quick-actions
Use this skill when configuring object-specific quick actions or global actions in Salesforce: choosing between action types, editing action layouts, pre-filling fields with predefined values, and adding actions to Lightning page layouts or mobile navigation.
Open the skill folder on GitHub
Global Actions and Quick Actions
This skill activates when an admin needs to create, configure, or troubleshoot global or object-specific quick actions — including editing action layouts, setting predefined field values, and surfacing actions in Lightning Experience or the Salesforce mobile app.
Before Starting
Gather this context before working on quick actions:
- Where should the action appear? Global actions appear in the global header and home page; object-specific actions appear on a specific object's record page. The object determines where Setup → Object Manager → Actions is found.
- What should the action do? Choose the correct action type before creating (see Core Concepts below). The type cannot be changed after creation.
- Who needs to see the action? Actions are added to page layouts. Multiple profiles using different page layouts may need separate layout updates.
- Mobile or desktop or both? The "Salesforce Mobile and Lightning Experience Actions" section of a page layout controls both. If you want desktop-only, there is no built-in filter — the same actions list applies to both surfaces.
Questions to Ask Before Configuring
Ask these before opening Setup. Each one maps to a gotcha in references/gotchas.md; skipping them produces an action that deploys cleanly and does the wrong thing.
| Ask | Why it matters | What a good answer adds |
|---|---|---|
| "Which record is the user looking at when they press this?" | A named record means object-specific and targetParentField can link the new record; "any page" means global and the user must pick the parent by hand | The scope decision, and whether parent linkage is free or manual |
| "Which fields must the user type, and which should we set for them?" | Typed fields go on the action layout; set fields become fieldOverrides and can be omitted from the layout entirely | The split between layout items and predefined values |
| "Is each pre-set field a picklist?" | literalValue is picklists only; every other type needs formula with a quoted string (gotcha 7) | The correct override element per field, before the deploy fails |
| "Do any of these fields already have a default value?" | A predefined value overrides the field default, so the action's records diverge from every other creation path (gotcha 8) | A conscious decision instead of a later data-quality investigation |
| "Which page layouts, and which surfaces — record bar, Classic publisher, mobile, list view?" | platformActionList and quickActionList are separate lists, and actionListContext picks the bar (gotcha 11) | The exact Layout edits, deployable in the same change |
| "Is this object already on Dynamic Actions?" | If yes, the FlexiPage action list drives the bar and Layout edits are dead configuration | A redirect to admin/dynamic-forms-and-actions before wasted work |
| "How many actions are already in front of this one?" | Position decides discoverability; sortOrder is the only lever (gotcha 5) | An agreed sortOrder, and which existing action loses its slot |
What a proper configuration adds over just creating the action: the record it creates is linked and pre-filled without user typing, the pre-set values are written with the element the field type actually accepts, and the action ships in the same deployment as every Layout that surfaces it — so it is visible to real users on the first release rather than the second.
Core Concepts
Action Types
These are the six action types an admin picks in Setup day to day. Choosing the wrong one at creation forces deletion and recreation. The full QuickActionType enum in the Metadata API also carries Post, SocialPost and Canvas — see the metadata table below:
| Action Type | Creates a new record | Updates current record | Logs activity | Launches UI |
|---|---|---|---|---|
| Create | Yes | No | No | No |
| Update | No | Yes | No | No |
| Log a Call | No | No | Yes | No |
| Custom (VF / LWC) | Configurable | Configurable | No | Yes |
| Flow | Configurable | Configurable | No | Yes |
| Send Email | No | No | No | Yes |
Create actions are the most common. They create a child or related record (e.g., create a Contact from an Account). When object-specific, the parent record is automatically linked. When global, no parent context is available.
Update actions modify fields on the current record without opening the full edit page. Useful for quick status changes or stage updates.
Log a Call actions create a completed Task record with subject, description, and date fields. Available on objects that support Activity tracking.
Flow actions launch a screen-flow UI within the action dialog. The flow receives the record ID as an input variable if the action is object-specific.
Global Actions vs Object-Specific Actions
| Global Actions | Object-Specific Actions | |
|---|---|---|
| Setup location | Setup → Global Actions | Setup → Object Manager → [Object] → Buttons, Links, and Actions |
| Parent record context | Not available | Available via merge fields and predefined values |
| Where they appear | Global header, Home page, Chatter | Record pages only |
| Page layout ownership | Global Publisher Layouts | Object's page layout |
| Mobile availability | Yes, via global header | Yes, via record page |
The key behavioral difference: object-specific actions can reference the source record's fields in predefined values (e.g., pre-fill Account Name on a new Contact from an Account record). Global actions cannot because there is no guaranteed source record.
Action Layouts
Every quick action has its own action layout — a separate, independent layout that controls which fields appear inside the quick action dialog. This is distinct from the page layout, which controls field visibility on the record detail page.
Key points:
- Adding a field to a page layout does not make it appear in a quick action. Fields must be added to the action layout separately.
- Action layouts are edited in Setup: navigate to the action, then click Edit Layout on the action detail page.
- Action layouts are compact by design — best practice is 4–8 fields maximum. More fields defeats the purpose of a quick action.
- Required fields must appear on the action layout or Salesforce will prevent saving.
- Formula fields, roll-up summary fields, and auto-number fields cannot be added to action layouts. (UNVERIFIED 2026-09-04: not stated in the Metadata API guide's QuickActionLayout section; confirm in Setup before relying on it.)
Predefined Values (Pre-filling Fields)
Predefined values let you auto-populate action layout fields so users do not have to enter them manually. This is configured per-action under Predefined Field Values.
Behavior:
- Predefined values support literal values and merge field formulas that reference the source record.
- For object-specific actions,
{!ObjectName.FieldAPIName}syntax resolves at runtime to the parent record's field value. - For global actions, only static literal values are supported — no source-record merge fields.
- Pre-filled values are editable by the user at action time unless the field is removed from the action layout (hidden but still set).
- A field can receive a predefined value without appearing on the action layout. This is intentional: the field is set silently in the background.
Example predefined value formula on a Contact quick action on Account:
Account Name: {!Account.Name}
Record Type: Customer ContactAdding Actions to Page Layouts
An action is not visible to users until it is added to a page layout. Two sections of the page layout editor are relevant:
- Salesforce Classic Publisher — Legacy section. Avoid for new work.
- Salesforce Mobile and Lightning Experience Actions — The correct section for all Lightning and mobile configurations. Actions dragged here appear in both Lightning Experience and the mobile app.
For global actions, they go into the Global Publisher Layout (Setup → Global Publisher Layouts), not an object's page layout.
Steps to add an object-specific quick action to a Lightning record page:
- Open Setup → Object Manager → [Object] → Page Layouts → [Layout Name].
- Drag Mobile & Lightning Actions palette items into the "Salesforce Mobile and Lightning Experience Actions" section.
- Save the page layout.
- If the layout already has actions, confirm the action is not buried behind the "More" overflow — the first 5 actions in this section appear directly on the highlights panel; subsequent actions go under a "More" dropdown.
The Metadata Behind the Setup Screens
Every Setup field maps to one element of the QuickAction metadata type. Read this table when reviewing a diff or writing the XML by hand; references/metadata-examples.md has the full deployable files.
| Setup control | Element | Notes from the Metadata API guide |
|---|---|---|
| Action Type | type | Required. Canvas, Create, Flow, LightningComponent, LogACall, Post, SendEmail, SocialPost, Update, VisualforcePage |
| Target Object | targetObject | "The object for which the action is created and performed" |
| (implicit parent link) | targetParentField | "Links the target object to the parent object" — object-specific actions only |
| Record Type | targetRecordType | Only Business Account, Person Account, Master — see gotcha 6 |
| Label / Standard Label | label / standardLabel | standardLabel uses the QuickActionLabel enum so the platform supplies a translated label |
| Create a feed item | optionsCreateFeedItem | Required; applies only to Create, Update and Log a Call |
| Success Message | successMessage | API 36.0+ |
| Edit Layout | quickActionLayout | layoutSectionStyle (required) + quickActionLayoutColumns → quickActionLayoutItems (field, emptySpace, uiBehavior) |
| Predefined Field Values | fieldOverrides | field + formula or literalValue |
| Flow | flowDefinition | API name of the flow |
| Lightning / Visualforce / Canvas | lightningComponent / page / canvas | plus height and width in pixels |
Files live in quickActions/, suffix .quickAction. Object-specific actions are addressed with dot notation — the platform uses Account.QuickCreateContact for an entity-level action and Global.CreateNewContact for a global one, per the Apex describeQuickActions signature.
The action's placement is not part of the action. It lives on the Layout (platformActionList for the Lightning and mobile bar, quickActionList for the Classic publisher) or, when Dynamic Actions are on, on the FlexiPage.
Common Patterns
Pattern 1: Create-Child Quick Action with Pre-filled Parent Lookup
When to use: You need users to quickly create a related record (e.g., new Opportunity from an Account) without navigating away.
How it works:
- In Object Manager → Account → Buttons, Links, and Actions → New Action.
- Action Type: Create. Target Object: Opportunity. Label: "New Opportunity".
- In the action layout, add fields: Opportunity Name, Close Date, Stage. Remove all other fields.
- Under Predefined Field Values, set
Account Nameto{!Account.Name}. - Add the action to the Account's "Salesforce Mobile and Lightning Experience Actions" section in the page layout.
Why not a manual navigate: Users stay in context. The Opportunity is already linked to the Account via the predefined account lookup.
Pattern 2: Update Action for Quick Status Change
When to use: A field (like Case Status or Lead Status) needs to be changed without opening the full record edit.
How it works:
- Object Manager → [Object] → New Action. Action Type: Update.
- Add only the status field to the action layout.
- Add a predefined value for the new status if it should always be a specific value (e.g., "Closed").
- Add to page layout.
Why not inline edit: Inline edit on a record detail page requires the field to be on the page layout and the user to click the field. A quick action is discoverable as a button and works well for mobile.
Pattern 3: Global Quick Action for Object-Agnostic Record Creation
When to use: Users need to log a Call or create a Task from any page (home, Chatter feed, report) without being on a specific record.
How it works:
- Setup → Global Actions → New Action. Action Type: Log a Call.
- Add fields: Subject, Description, Date.
- The action appears in the global header (bell/quick action icon in Lightning).
- Users can manually relate the log to a record after creation via the "What" and "Who" fields.
Why not object-specific: The user may not be on the record when they need to log. Global actions are accessible from anywhere.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| Action must pre-fill from the current record's fields | Object-specific action + predefined values | Global actions have no source-record context |
| Action should be accessible from any Salesforce page | Global action + Global Publisher Layout | Object-specific actions only appear on their object's record pages |
| Action launches a Flow | Object-specific Flow action (pass record ID) | Flows that mutate the current record need the record ID as input |
| Action should only appear for one profile/role | Use page layout assignments to restrict | Actions are surfaced via page layouts; profile → layout assignment controls visibility |
| Action should create a related child record | Create action on the parent object | Pre-fill the parent lookup using predefined values with merge fields |
| You need to update a single field quickly | Update action | Narrower UX than full edit; works well on mobile |
Recommended Workflow
- Scope and surface — answer the Questions table above; decide object-specific vs global, and list every page layout (or FlexiPage) that must carry the action. If the object is on Dynamic Actions, stop and route to
admin/dynamic-forms-and-actions - Split the fields — put user-typed fields in
quickActionLayoutwith the rightuiBehavior, and everything you set for the user infieldOverrides; check each override's field type againstliteralValue(picklists only) vsformula - Write or configure the action — copy the matching shape from
references/metadata-examples.md(Create with parent link, global Log a Call, Update, Flow, custom component, Person Account), or build it in Setup and retrieve it - Place it — add the action to
platformActionListwith an explicitsortOrder, and toquickActionListtoo if Classic is still in use; keep the action and its layouts in one deployment - Check statically — run
python3 scripts/check_global_actions_and_quick_actions.py --manifest-dir force-app/main/defaultand clear every ERROR; treatunplacedINFOs as release blockers unless the action is deliberately parked - Verify as a user, not as an admin — run
QuickAction.describeAvailableQuickActions('<Object>')and('Global')in anonymous Apex as a test user on the target profile, then open a record and confirm the pre-filled values and the action's position in the bar - Record it — fill in
templates/global-actions-and-quick-actions-template.mdwith the layout placement, the overrides, and the profiles that can see it
Review Checklist
Before marking quick action configuration complete:
- [ ] Action type is correct for the use case (cannot change after creation)
- [ ] Action layout has only the fields needed — remove unnecessary fields
- [ ] Required fields are on the action layout (absent required fields block saves)
- [ ] Predefined values are set for parent record linkages and any constant defaults
- [ ] Action has been added to the correct page layout section: "Salesforce Mobile and Lightning Experience Actions"
- [ ] Page layout is assigned to the correct profiles
- [ ] Action tested in both Lightning Experience (desktop) and mobile app if both are in use
- [ ] For global actions: action appears in the Global Publisher Layout
Salesforce-Specific Gotchas
Non-obvious platform behaviors that cause real production problems:
- Action layout ≠ page layout — Adding a field to the object's page layout does not add it to the action's form. You must edit the action layout separately via the action's Edit Layout button. This trips up admins who expect one layout to control everything.
- LWC global quick actions are Field Service mobile only — According to the Lightning Web Components Developer Guide, LWC components exposed as
lightning__GlobalActiontargets are available only in the Field Service mobile app, not in standard Lightning Experience on desktop or mobile. Using a Visualforce or Aura component is the correct approach for global custom actions in regular Lightning Experience. - Actions do not appear without a page layout assignment — Creating an action and editing its layout is not sufficient; the action must also be dragged into the page layout's actions section and the page layout must be assigned to the user's profile. If an action is missing for some users but visible to others, check page layout assignments.
- The first ~5 actions in the mobile/Lightning section display directly; the rest go to "More" (UNVERIFIED 2026-09-04: the count is not in the extracted guides; observed behaviour, not a documented limit) — Users often cannot find actions that are listed 6th or later. Keep the highest-frequency actions in the first five positions.
- Predefined values using merge fields only work for object-specific actions — If you attempt to use
{!ObjectName.Field}syntax on a global action predefined value, Salesforce will throw a validation error at save time. Global action predefined values must be static literals or formulas without source-record references.
Output Artifacts
| Artifact | Description |
|---|---|
| Configured quick action | Action of the correct type, attached to the object or global context |
| Action layout | Compact form with only the necessary fields, required fields present |
| Predefined values | Pre-filled parent lookups and constant defaults reducing user effort |
| Page layout update | Action visible in the "Salesforce Mobile and Lightning Experience Actions" section |
Reference Files
| File | Read it when |
|---|---|
references/metadata-examples.md | Writing or reviewing .quickAction-meta.xml, the Layout action lists, package.xml, or the deploy and verification commands |
references/gotchas.md | An action deployed but is invisible, a predefined value is ignored or rejected, or a record from the action differs from every other creation path |
references/examples.md | You want a worked end-to-end configuration (create-child, quick update, global log-a-call) with the Setup clicks spelled out |
references/well-architected.md | Deciding global vs object-specific, declarative vs custom component, or how many actions a record page should carry |
references/llm-anti-patterns.md | Reviewing AI-generated quick action guidance before acting on it |
templates/global-actions-and-quick-actions-template.md | Documenting a finished action: type, layout fields, overrides, placement, profile access, test results |
scripts/check_global_actions_and_quick_actions.py | Static-checking retrieved metadata before a deploy |
Related Skills
admin/app-and-tab-configuration— Lightning app configuration; action bar visibility is affected by the Lightning app's navigation itemsflow/screen-flows— When the quick action type is "Flow", the referenced flow must be a screen flow; this skill covers building screen flowsadmin/object-creation-and-design— Object and field design that determines what can be referenced in quick actions and predefined valuesadmin/dynamic-forms-and-actions— Dynamic Actions on a Lightning record page: this skill defines the actions, that skill controls when each one is visibleadmin/record-types-and-page-layouts— The fullLayoutmetadata shape and record-type-to-layout assignment; read it before hand-editing a layout fileadmin/custom-button-to-action-migration— Replacing Classic JavaScript, URL, and list buttons with actionsadmin/case-feed-send-email-action— The Case Feed Send Email action and itsQuickActionDefaultsHandler, which is the supported way to shape an outbound email before it sendslwc/lwc-quick-actions— Building the component behind a custom action: the required target,recordId, and closing the modal