Print this page

Updating Hard-Coded References

Knowledge Article Number 000230820
Last updated (in English) on October 19, 2016.

Salesforce recommends that you implement My Domain, especially if you have hard-coded instance-specific references in your integrations, email templates, Knowledge articles, etc. To enable My Domain, you must first update your hard-coded references. Updating hard-coded references will help prepare your org for system maintenances that we perform to continue to provide you with the performance you have come to expect from Salesforce. See below for frequently asked questions on this topic.

NOTE: This document is for informational purposes only, and is not part of any legal or otherwise binding agreement. The policies and practices described in this document are subject to change at Salesforce's sole discretion.


General FAQs


1. What are hard-coded references (also known as instance-specific references)?

a. A hard-coded reference is a URL that contains the instance name in the URL (e.g. instead of a generic, non-instance specific URLs (e.g. or


2. How can I find hard-coded references?

a. Salesforce has released a new tool to help admins find hard-coded references. This is part of the Lightning Readiness Assessor Tool, as enabling My Domain is required for many Lightning features. In addition, My Domain is recommended to ensure your org is prepared for future maintenances such as instance refreshes or org migrations.

b. You can use this new tool by going to Setup | In Quick Finder type “Lightning Experience” | scroll until you see Check Your Lightning Experience Readiness.

c. For more information on this feature, check out our See If Your Org Is Ready for Lightning with the Lightning Experience Readiness Check help topic.

3. How can I update hard-coded references using IDE?

Follow the steps below to update hard-coded references* in your org and your org's metadata (setup or customer code):

i. Create a new Project:

1. Go to File > New > Project
2. Provide a name for your project, enter your login credentials for the org, then click "Next.”

ii. Choose the project contents:

1. Select metadata components, then click "Choose."
On the next screen for metadata components, select the fields required then click "OK."

a. At a minimum, we suggest selecting the following: email templates, home page components, web links, workflow, triggers, classes, visualforce pages, and tabs.

3. Please keep in mind that you can only pull 1500 components at a time. If you need to pull more metadata, we recommend dividing your work into multiple projects.

a. If you exceed the limit for number of components, you will receive this error message: "LIMIT_EXCEEDED: Too many files retried in a single retrieve call, limit is 1500." The Metadata API, which the IDE uses to communicate with the server, enforces these limits per each deploy/retrieve transaction.

iii. Once you have created your project, press Ctrl-H to perform a search.

1. Search for the name of the instance that your org resides on, for example: NA4. See Figure 1 below.

a. If you have multiple projects open, right-click on each project you don't want to search on and choose "Close Project" or modify the search criteria so that you have a "working set" to minimize the files you're searching on.

Figure 1. Example Search output

b. If you need to access the server instance in your Visualforce page, you can use the following JavaScript function getServerInstance() to parse out the server instance from the URL:

            function getServerInstance()


                    var URL = window.location + “”;

                    var urlParseArray = url.split(“.”);

                    var i;

                    for(i=0; i< urlParseArray.length; i++)


                    if(urlParseArray[i].indexOf(“salesforce”) != -1)

                        return urlParseArray[i-1];

                        if(urlParseArray[i].indexOf(“force”) != -1)

                        return urlParseArray[i-2]


                    return null;



* These steps will remove hard-coded references from Visualforce Pages, home page components, web links, workflow, triggers, classes, and tabs. These steps will NOT remove hard-coded references from image URLs within email templates or Knowledge articles

3. How do I update hard-coded references in integrations?


a. For your integrations to Salesforce products or, use the API’s login() request as a starting point. The login() request should be sent to a generic endpoint, such as:

b. The login() call will establish a session and respond with the login server URL. Set this server URL as the target server for subsequent API requests, and set the returned session ID in the SOAP header to provide server authorization for subsequent API requests.


4. Where can I go for further help?


a. The Developer Discussion Boards can be accessed directly at:!/feedtype=RECENT&criteria=ALLQUESTIONS.

i. You can use your Salesforce username and password to log into the developer forums.

b. Below are additional resources for developers:

i. Developer Workbooks
Best Practices and Code Samples
iii. Developer Documentation
iv. Salesforce live streaming channel: CodeTalk Live

c. If you have Premier Support, you can log a case via the Help & Training Portal (code review is not supported for Standard Customers).


Instance Refresh & Org Migration-related FAQs

The following questions may be relevant when you are preparing to move to a new instance.


5. What hard-coded references can Salesforce servers redirect* after moving to a new instance?


a. While Salesforce servers are able to redirect the following objects with hard-coded references, you may experience slow performance when using these objects after moving to a new instance. Therefore, Salesforce recommends that you implement My Domain or remove all hard-coded references prior to moving to a new instance.

i. Browser links
ii. Browser bookmarked URLS
iii. Custom buttons
iv. Content URLs
v. Chatter posts
vi. Self-Service Login URLs (sserv/login.jsp?orgid)
vii. Integrations

* These will redirect assuming that you are following our Network Settings Best Practices, outlined in the Network Settings article, so that your application can connect to our secure servers.


6. What hard-coded references must be updated (i.e. won't redirect) prior to moving to a new instance?

a. If you do not have My Domain enabled, you must update hard-coded references in email templates and Knowledge articles.
b. Whether or not you have My Domain enabled, you will need to ensure all images within Knowledge articles and email templates have been uploaded from your computer as opposed to a web address in order for them to continue displaying following the maintenance.

i. If you have images that have been inserted via web address, you will need to download the image to your computer and re-upload the image by choosing the "Upload Image" option when inserting the image int a Knowledge article or email template. See the following diagrams for representation of the appropriate process.

add article image

User-added image

NOTE:  If you find that images are broken following the maintenance because they were not uploaded from your computer, you will need to replace the old instance name in the image URL with your new instance name. Then, you should download the image to your computer and re-upload the image from your computer to prevent the image from breaking after future maintenances.


7. How can I verify all images within my Knowledge articles and email templates have been uploaded from my computer as opposed to web address?

a. If an image has been uploaded from a local machine, the image URL should read “https://[HOST-OR-MY-DOMAIN]/servlet/rtaImage…”.

b. If an image has been linked from a web address (or your Documents tab), the image URL should read “https://[HOST-OR-MY-DOMAIN]/servlet/servlet.ImageServer...” or “https://[HOST-OR-MY-DOMAIN]/servlet/servlet.FileDownload…”

8. Do I need to update the hard-coded references in my CTI integrations if I am moving to a new instance?


a. This maintenance will impact your CTI integration, if you are using Open CTI and the CTI Adapter URL in your Call Center definition is hard-coded with your Salesforce instance (e.g.

b. Please change this hard-coded reference to a relative URL (e.g. /apex/Softphone) to ensure your CTI integration will continue to work after the moving to a new instance.

c. To update this, you can navigate to the specific click path of the call center object: Setup > Customer > Call Centers.

d. If you are using the Salesforce Desktop CTI Integration Toolkit, this maintenance will not impact your CTI integration as the Toolkit does not allow hard-coded references.


9. Do I need to update my Email Thread IDs if I am moving to a new instance?


a. No. Existing Email Thread IDs will not change when you move to a new instance.

b. Please do not create your own custom Thread ID formats, as that is not a Salesforce supported functionality and formats may change over time. This could negatively impact your Email-To-Case (E2C) functionality following the maintenance.

i. If you change your Thread IDs, you may experience an issue with on-demand Email-To-Case (E2C) where replies with Thread IDs are creating new cases and not attaching to the original case.

c. If you generated your own Email Thread ID and need to fix it:

i. Update your custom formula to the following format:

1. ref:_00D[XX][yyyyy]._500[AA][bbbbb]:ref

a. Where yyyyy and bbbbb are the 10-char ID with the leading zeros stripped.
b. Email Thread ID formats that are parseable by our system code are as follows, (yyyyy and bbbbb are the record ID without the leading zeros)

2. Note that ref:00DXyyyyy.500Abbbbb:ref is the old format that is no longer used. Salesforce may change the formats over time which is why customers should refrain from generating their own Thread IDs.

d. Please note that we do not officially support custom formulas for case Thread IDs. We recommend customers use the out-of-box Thread ID formula that Salesforce generates.


10. Will customers still be able to access our partner portal from the old instance URL after we move to a new instance?


a. For approximately 30 days after moving to a new instance, customers should be able to access your partner portal using the old instance URL. After this 30 day window, the old instance login URL will be decommissioned. Prior to moving to a new instance, we recommend admins add a custom note under the "System Maintenance" message on their org’s partner portal directing customers to use the new partner portal URL following the move to a new instance. Admins may also choose to recommend customers update their login bookmarks with the new partner portal URL.


11. Will there be any impact to Web-to-Leads/Cases (W2X) after I move to a new instance?

a. If you have hard-coded references in your W2X, you will need to update them to relative URLs prior to moving to a new instance. If you do not update hard-coded references, you may experience unintended service disruptions to W2X following the maintenance.

b. W2X will be queued and processed after the maintenance is complete.


12. Do remote site names need to be updated after I move to a new instance?


a. Yes. If you are not using My Domain, hard-coded references in remote site names will need to be updated with the new instance name immediately after the maintenance.

b. If you do not update hard-coded references in remote site names following the maintenance, you may experience unintended service disruptions to remote sites.

13. Will moving to a new instance affect Salesforce Mobile SDK?


a. Moving to a new instance may affect data on Salesforce Mobile SDK-created apps if users do not have the latest versions. We recommend that you update all Salesforce Mobile SDK-created apps and push these updates to all users in your org prior to the maintenance.

If users have the latest versions of all Salesforce Mobile SDK-created apps, moving to a new instance should not affect data within the apps.

​​14. Do I need to change Live Agent server endpoints after I move to the new instance (ex. the URLs within Live Agent Chat buttons)?
a. Yes. Once the maintenance completes, replace the Live Agent deployment code and button with a new deployment code that reflects the new instance name. You can replace both through Live Agent Setup. Replace all deployment and button code used on other sites with the new snippet of code that you can access via Setup after the maintenance has completed. If you do not update your Live Agent Deployment Code, you may experience downtime, without notification, when Salesforce make updates to Live Agent in other data centers.
User-added image

15. What actions do I need to take for any Apex Web Services Generated WSDLs?

a. If you use WSDLs to generate code, all areas where you have employed the code will need to be checked for hard-coded references. All hard-coded references must be updated to either a My Domain URL or a relative URL ( We recommend implementing My Domain prior to moving to a new instance. This will ensure that once you have fixed all hard-coded references to point to the new My Domain URL you will not have to perform this work again.


promote demote