WebLink Metadata Type for Custom Buttons and Links

Why the WebLink Metadata Type Still Matters#

While QuickAction handles modal LWC and Screen Flow actions on record pages, WebLink (objects/<ObjectName>/webLinks/<Name>.webLink-meta.xml) remains essential for three high-value patterns in Lightning Experience:

1. List View & Related List Mass Action Buttons (massActionButton): Launching an Autolaunched/Screen Flow URL (/flow/Mass_Approve_Orders?retURL=...) or a Visualforce StandardSetController page with selected checkboxes (requireRowSelection = true).
2. Native Record Creation with Default Field Values (/lightning/o/Order/new?defaultFieldValues=...): Opening the standard Lightning record creation modal pre-populated with parent field values without writing custom code.
3. External Deep Links (link / button): Launching external ERP, shipping tracker, or DocuSign endpoints with merge fields ({!Account.ERP_Customer_ID__c}).

Key Metadata Fields on WebLink#

Real-World XML Example: Lightning Pre-Populated Record Creation Button#

File: force-app/main/default/objects/Opportunity/webLinks/New_Renewal_Quote.webLink-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<WebLink xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>New_Renewal_Quote</fullName>
    <availability>online</availability>
    <description>Opens standard Quote creation modal with pre-populated Opportunity and Account fields.</description>
    <displayType>button</displayType>
    <encodingKey>UTF-8</encodingKey>
    <linkType>url</linkType>
    <masterLabel>New Renewal Quote</masterLabel>
    <openType>replace</openType>
    <protected>false</protected>
    <url>/lightning/o/Quote/new?defaultFieldValues=OpportunityId={!Opportunity.Id},Name={!URLENCODE(Opportunity.Name + &apos; - Renewal&apos;)},ExpirationDate={!TEXT(TODAY() + 30)}</url>
</WebLink>

Querying WebLink via SOQL & Tooling API#

You can query WebLink in standard SOQL to audit legacy javascript buttons or hardcoded sandbox URLs across your org.

1. Audit Legacy OnClick JavaScript Buttons Blocking Lightning Migration#

SELECT Id, PageOrSobjectType, Name, MasterLabel, DisplayType, LinkType, OpenType
FROM WebLink
WHERE NamespacePrefix = null
  AND (LinkType = 'javascript' OR OpenType = 'onClickJavaScript')
ORDER BY PageOrSobjectType, Name

2. Find WebLinks Containing Hardcoded Domains or URLs#

SELECT Id, PageOrSobjectType, Name, MasterLabel, DisplayType, Url
FROM WebLink
WHERE NamespacePrefix = null
  AND LinkType = 'url'
ORDER BY PageOrSobjectType, Name

Senior Architect Best Practices#

• Deploying a WebLink Does Not Automatically Show It on the UI: Creating the .webLink-meta.xml file only registers the button on the object. To make it visible, you must also add it to the Layout (customButtons), the FlexiPage Dynamic Actions bar, or the object’s Search Layout / List View button configuration (searchLayouts.listViewButtons).
• Always Use URLENCODE() inside Merge Expressions: If an Account or Opportunity name contains an ampersand (AT&T), an unencoded merge field inside defaultFieldValues will truncate the query string parameter.

Frequently asked questions

When should you use a WebLink instead of a QuickAction in Lightning Experience?

Use a QuickAction for modal LWC or Screen Flow actions on a single record. Use a WebLink when you need a List View mass action button that accepts multiple selected checkboxes, a direct URL redirect with default field values, or a custom detail link inside a field section.

What are the three displayType values supported by WebLink?

The displayType field supports link (a hyperlink placed inside a detail page layout section), button (a detail page button placed in the action bar), and massActionButton (a button placed on List Views and Related Lists).

Why do JavaScript WebLink buttons (linkType javascript) not appear in Lightning Experience?

OnClick JavaScript buttons (openType onClickJavaScript and linkType javascript) are blocked in Lightning Experience for security compliance under Lightning Locker and LWS. Convert them to Lightning QuickActions, Screen Flows, or URL-addressable LWCs.

Can you query WebLink definitions using SOQL?

Yes. Both standard SOQL and the Tooling API allow querying the WebLink object to inspect Name, MasterLabel, PageOrSobjectType, DisplayType, LinkType, OpenType, and Url.