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 Contact

Adding 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:

1. Salesforce Classic Publisher — Legacy section. Avoid for new work.
2. 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:

1. Open Setup → Object Manager → [Object] → Page Layouts → [Layout Name].
2. Drag Mobile & Lightning Actions palette items into the "Salesforce Mobile and Lightning Experience Actions" section.
3. Save the page layout.
4. 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:

1. In Object Manager → Account → Buttons, Links, and Actions → New Action.
2. Action Type: Create. Target Object: Opportunity. Label: "New Opportunity".
3. In the action layout, add fields: Opportunity Name, Close Date, Stage. Remove all other fields.
4. Under Predefined Field Values, set Account Name to {!Account.Name}.
5. 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:

1. Object Manager → [Object] → New Action. Action Type: Update.
2. Add only the status field to the action layout.
3. Add a predefined value for the new status if it should always be a specific value (e.g., "Closed").
4. 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:

1. Setup → Global Actions → New Action. Action Type: Log a Call.
2. Add fields: Subject, Description, Date.
3. The action appears in the global header (bell/quick action icon in Lightning).
4. 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

1. 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
2. Split the fields — put user-typed fields in quickActionLayout with the right uiBehavior, and everything you set for the user in fieldOverrides; check each override's field type against literalValue (picklists only) vs formula
3. 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
4. Place it — add the action to platformActionList with an explicit sortOrder, and to quickActionList too if Classic is still in use; keep the action and its layouts in one deployment
5. Check statically — run python3 scripts/check_global_actions_and_quick_actions.py --manifest-dir force-app/main/default and clear every ERROR; treat unplaced INFOs as release blockers unless the action is deliberately parked
6. 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
7. Record it — fill in templates/global-actions-and-quick-actions-template.md with 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:

1. 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.

2. LWC global quick actions are Field Service mobile only — According to the Lightning Web Components Developer Guide, LWC components exposed as lightning__GlobalAction targets 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.

3. 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.

4. 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.

5. 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 items
• flow/screen-flows — When the quick action type is "Flow", the referenced flow must be a screen flow; this skill covers building screen flows
• admin/object-creation-and-design — Object and field design that determines what can be referenced in quick actions and predefined values
• admin/dynamic-forms-and-actions — Dynamic Actions on a Lightning record page: this skill defines the actions, that skill controls when each one is visible
• admin/record-types-and-page-layouts — The full Layout metadata shape and record-type-to-layout assignment; read it before hand-editing a layout file
• admin/custom-button-to-action-migration — Replacing Classic JavaScript, URL, and list buttons with actions
• admin/case-feed-send-email-action — The Case Feed Send Email action and its QuickActionDefaultsHandler, which is the supported way to shape an outbound email before it sends
• lwc/lwc-quick-actions — Building the component behind a custom action: the required target, recordId, and closing the modal