Rewrite URLs for Salesforce Sites
Sites provides built-in logic that helps you display user-friendly URLs and links to site visitors. Create rules to rewrite URL requests typed into the address bar, launched from bookmarks, or linked from external websites. You can also create rules to rewrite the URLs for links within site pages. URL rewriting not only makes URLs more descriptive and intuitive for users, it allows search engines to better index your site pages.
For example, let’s say that you have a blog site. Without URL rewriting, a blog entry’s URL might look like this: https://myblog.my.salesforce-sites.com/posts?id=003D000000Q0PcN
With URL rewriting, your users can access blog posts by date and title, say, instead of by record ID. The URL for one of your New Year’s Eve posts might be: https://myblog.my.salesforce-sites.com/posts/2019/12/31/auld-lang-syne
You can also rewrite URLs for links shown within a site page. If your New Year’s Eve post contained a link to your Valentine’s Day post, the link URL might show: https://myblog.my.salesforce-sites.com/posts/2019/02/14/last-minute-roses
To rewrite URLs for a site, create an Apex class that maps the original URLs to user-friendly URLs, and then add the Apex class to your site.
To learn about the methods in the Site.UrlRewriter interface, see UrlRewriter Interface.
The Apex class that you create must implement the provided interface Site.UrlRewriter. In general, it must have the following form:
Consider the following restrictions and recommendations as you create your Apex class:
-
Class and Methods Must Be Global: The Apex class and methods must all be
global. -
Class Must Include Both Methods: The Apex class must implement both the
mapRequestUrlandgenerateUrlFormethods. If you don’t want to use one of the methods, simply have it returnnull. -
Rewriting Only Works for Visualforce Site Pages: Incoming URL requests can only be mapped to Visualforce pages associated with your site. You can’t map to standard pages, images, or other entities. To rewrite URLs for links on your site’s pages, use the
!URLFORfunction with the$Pagemerge variable. For example, the following links to a Visualforce page named myPage:Visualforce
<apex:form>elements withforceSSL=”true”aren’t affected by theurlRewriter.See the “Functions” appendix of the Visualforce Developer’s Guide.
-
Encoded URLs: The URLs you get from using the
Site.urlRewriterinterface are encoded. If you need to access the unencoded values of your URL, use theurlDecodemethod of the EncodingUtil Class. -
Restricted Characters: User-friendly URLs must be distinct from Salesforce URLs. URLs with a 3-character entity prefix or a 15- or 18-character ID aren’t rewritten. You can’t use periods in your user-friendly or rewritten URLs, except for the
.well-knownpath component, which can’t be used at the end of a URL. -
Restricted Strings: You can’t use the following reserved strings as the first path component after a site’s base URL in either a user-friendly URL or a rewritten URL. Some examples of the first past component after a site’s base URL are
baseURLin https://MyDomainName.my.salesforce-sites.com/baseURL, https://MyDomainName.my.salesforce-sites.com/pathPrefix/baseURL, https://custom-domain/pathPrefix/baseURL, and https://MyDomainName.my.salesforce-sites.com/pathPrefix/baseURL/another/path.apexcomponentapexpagesaurachatterchatteranswerschatterservicecometdexfacesflashflexgooglehomeidideasidpimagesimgjavascriptjsknowledgelightningloginmmobilencsphotonuipushresourcesamlsccommunitiessearchsecurservicesservletsetupsfcsfdcsfdc_nssfsitessitestylevoteWEB-INFwidg
You can’t use the following reserved strings at the end of a rewritten URL path:
- /aura
- /auraFW
- /auraResource
- /AuraJLoggingRPCService
- /AuraJLVRPCService
- /AuraJRPCService
- /dbcthumbnail
- /HelpAndTrainingDoor
- /htmldbcthumbnail
- /l
- /m
- /mobile
-
Relative Paths Only: The PageReference.getUrl() method only returns the part of the URL immediately following the host name or site prefix (if any). For example, if your URL is
https://mycompany.my.salesforce-sites.com/sales/MyPage?id=12345, where “sales” is the site prefix, only/MyPage?id=12345is returned. You can’t rewrite the domain or site prefix. -
Unique Paths Only: You can’t map a URL to a directory that has the same name as your site prefix. For example, if your site URL is
https://acme.my.salesforce-sites.com/help, where “help” is the site prefix, you can’t point the URL tohelp/page. The resulting path,https://acme.my.salesforce-sites.com/help/help/page, would be returned instead ashttps://acme.my.salesforce-sites.com/help/page. -
Query in Bulk: For better performance with page generation, perform tasks in bulk rather than one at a time for the
generateUrlFormethod. -
Enforce Field Uniqueness: Make sure the fields you choose for rewriting URLs are unique. Using unique or indexed fields in SOQL for your queries may improve performance.
Once you’ve created the URL rewriting Apex class, follow these steps to add it to your site:
- From Setup, enter
Sitesin theQuick Findbox, then select Sites. - Click New or click Edit for an existing site.
- On the Site Edit page, choose an Apex class for
URL Rewriter Class. - Click Save.
If you have URL rewriting enabled on your site, all PageReferences are passed through the URL rewriter. PageReferences with redirect set to true and a redirectCode other than 0 return redirected URLs instead of rewritten URLs.
In this example, we have a simple site consisting of two Visualforce pages: mycontact and myaccount. Be sure you have “Read” permission enabled for both before trying the sample. Each page uses the standard controller for its object type. The contact page includes a link to the parent account, plus contact details.
Before implementing rewriting, the address bar and link URLs showed the record ID (a random 15-digit string). Once rewriting was enabled, the address bar and links show more user-friendly rewritten URLs.
The Apex class used to rewrite the URLs for these pages is shown in Example URL Rewriting Apex Class, with detailed comments.
This section shows the Visualforce for the account and contact pages used in this example.
The account page uses the standard controller for accounts and is nothing more than a standard detail page. This page should be named myaccount.
The contact page uses the standard controller for contacts and consists of two parts. The first part links to the parent account using the URLFOR function and the $Page merge variable; the second simply provides the contact details. Notice that the Visualforce page doesn’t contain any rewriting logic except URLFOR. This page should be named mycontact.
The Apex class used as the URL rewriter for the site uses the mapRequestUrl method to map incoming URL requests to the right Salesforce record. It also uses the generateUrlFor method to rewrite the URL for the link to the account page in a more user-friendly form.
Here is a visual example of the results of implementing the Apex class to rewrite the original site URLs. Notice the ID-based URLs in the first figure, and the user-friendly URLs in the second.

Site URLs Before Rewriting
The numbered elements in this figure are:
- The original URL for the contact page before rewriting
- The link to the parent account page from the contact page
- The original URL for the link to the account page before rewriting, shown in the browser’s status bar

Site URLs After Rewriting
The numbered elements in this figure are:
- The rewritten URL for the contact page after rewriting
- The link to the parent account page from the contact page
- The rewritten URL for the link to the account page after rewriting, shown in the browser’s status bar