Best Practices When Referencing Server Endpoints

Advisory Note: Instance Split Preparation

At salesforce.com, customer success through system availability and reliability is our top priority. As part of our ongoing plan to deliver high availability and performance, Salesforce, at times, performs instance splits to deliver on our commitment to outstanding reliability in your service.

What is an instance split?

As part of our ongoing commitment to continuously enhancing our infrastructure, an instance split moves a number of organizations from one service instance to a new service instance to continue providing full capacity for our customers on each Salesforce instance. In preparation and to announce an instance split, customers always receive an email notification with ample notice to plan and prepare for an upcoming instance split.

Any new service instances Salesforce is setting up resides in one of our data centers that are built based on industry-leading quality and service delivery specifications.

What action should you take?

In preparation for an instance split and to follow our best practice recommendation when referencing server endpoints, you should ensure that your organization follows our best practices outlined below of using relative URLs instead of hard coded URLs in any integrations and in your Salesforce application. We would like to take this opportunity to highlight best practices to ensure your company’s continued success:

1. Review all custom links to ensure they use relative URL references.

2. Review any integration that uses the Force.com web services API to ensure there are no hard-coded references to the instance you are currently on (e.g. na7.salesforce.com).

3. Review any customer and/or partner portal setup for hard-coded references to your current instance (e.g. na7.salesforce.com).

4. If you whitelist IP addresses, add the new IP addresses for the new instance. You can find the Salesforce IP address range in Help & Training.

If you have any questions or concerns related to an instance split kindly contact Salesforce support by logging a ticket in Help and Training.

Best Practices

Here are some best practices to take into account when building integrations with Force.com. As a best practice for any custom code or integrations, Salesforce.com recommends the use of relative references to instances/server endpoints.

For customized integrations

If you have a customized integration, you will need to clear the DNS lookup cache by restarting your integration following the maintenance window of your node. Your integration will then refresh and detect the IP address of the new data center. Click here for more detail on applications cache behavior for Java. The same principles will apply for your particular integration platform.

Hardcoded URL or IP address

If you hardcode URL or IP address of salesforce.com endpoints in your integration, the following changes should be made to conform to best practices:

Avoid hard coding your integration to specific instance URLs. Instead use the Force.com API's login() request as a starting point for all of your integrations to salesforce.com products or Force.com. The login() request should be sent to a generic endpoint, such as:

https://login.salesforce.com/services/Soap/u/19.0

Be sure to use the most recent version of the API, which you can choose to replace for future API releases. The login() call will establish a Force.com 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. See the example code sample.

Use relative URLs in custom links, web-to-lead, S-Controls, etc., rather than specific URLs (e.g., na3.salesforce.com)

Please note: S-Controls have been deprecated. View more information here.

For the majority of use cases you should not need to directly reference the Salesforce instance that you are on. Those use cases can be fulfilled by the use of Global Variables which are available for Merge Fields, S-Controls and Visualforce.

In the rare case 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;
}

How to find hard-coded references using the Force.com IDE

Here is how to find hard-coded references in an org’s metadata (setup or custom code) using the Force.com IDE:

Create a new Force.com Project:
- Go to File > New > Force.com Project
- Provide a name for your project, enter your login credentials for the org, then click "Next". As a best practice, you may want to name the project with your username for the org in question.
- Choose the project contents: Selected metadata components, then click "Choose". On the next screen for Metadata Components, select at least email templates, home page components, web links, workflow, triggers, classes, visualforce pages, and tabs, then click "OK".

  Note if you want to pull more metadata, keep in mind that you can only pull 1500 components at a time. You will get an error like this if you hit the limit: "LIMIT_EXCEEDED: Too many files retrieved in a single retrieve call, limit is 1500".   

The Metadata API (which the Force.com IDE uses to communicate with the server) enforces these limits per each deploy/retrieve transaction. Best practice is to break up your work into multiple projects.

After creating your project, press Ctrl-H to do a search. Do a search for the name of the instance that your org resides on, for example "na4"(without the quotes).

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

For more information about finding hard-coded references, please read the following:

Salesforce Portal

For the salesforce Portal login the URL can be changed from the default specific URL

e.g.

https://na6.salesforce.com/secur/login_portal.jsp?orgId=00D300000000YTd&portalId=07250000000001u

to a generic, non-instance specific URL:

https://login.salesforce.com/secur/login_portal.jsp?orgId=00D300000000YTd&portalId=07250000000001u

Once you changed the portal login URL to the generic URL, the login server will handle the redirect. One thing to realize about this is that the login page will show with the default colors and settings (rather than any changes made by you on the instance specific). For instance, in this org my instance specific login page looks like:

But if I use the instance non-specific all of my color customizations are gone.

The color changes only apply to the login page. None of the settings once you are logged in are changed.

As an alternative, if you want to preserve the customizations, you can use Force.com Sites to manage the portal (though this is a much larger change) which will allow a non-specific instance login page.

WSDL File Generation

The Web Service API WSDL (Enterprise and Partner) is not generated with the instance-specific URL. All of the addresses are generic, for e.g.:

    <service name="SforceService">
        <documentation>Sforce SOAP API</documentation>
        <port binding="tns:SoapBinding" name="Soap">
            <soap:address location="https://login.salesforce.com/services/Soap/c/20.0/0FL300000008123"/>
        </port>
    </service>

However, if you have a Web Service API WSDL that is referencing a specific instance, you should change the WSDL or re-generate it after your org gets migrated to a different instance.

The Apex Web Services Generated WSDL file (those that are generated from an Apex Class) do have the instance specific URL:

<service name="testWSClassService">
       <documentation></documentation>
       <port binding="tns:testWSClassBinding" name="testWSClass">
        <soap:address location="https://na6-api.salesforce.com/services/Soap/class/jde/testWSClass"/>
       </port>
      </service>

For any Apex Web Services Generated WSDLs, you will have to modify the WSDL to point to the new instance, or you will have to regenerate the WSDL after the move to the new instance.

At a high level, the code should do the following:

API user logs into salesforce.com to generate a session ID at login.salesforce.com
API user uses the session ID and sends a SOAP request to the URL provided in the generated Apex WSDL

A full explanation is in the API documentation: Can be found here - Salesforce API Documentation

Certificate Usage

A split will not affect the certificates. That said, there will be new certs per each instance (e.g. na8-api.salesforce.com and na8.salesforce.com). If you have imported certs into your servers that reference the previous instance, you will also have to import the corresponding cert for the new instance.

You would not have to add any additional certificates outside of what you have now and the corresponding new cert. For example if you installed these two certificates on your current NA6 instance:

na6.salesforce.com and na6-api.salesforce.com

Then you would need to install the following two new certificates for the new NA8 instance after the split:

na8.salesforce.com and na8-api.salesforce.com

If you currently have:

na6-api.salesforce.com

you should only install:

na8-api.salesforce.com

after the split.

So the install of new certificates depends on what certificates you have currently installed. An easier way to describe would be to say anywhere you see your current instance (e.g. “na6”) you will have to install the corresponding certificate for your new instance (e.g. “na8”). If you are on eu0, you would have to install any corresponding eu1 certs.

Whitelisting salesforce.com IP addresses

If you currently whitelist salesforce.com data center IP addresses, you may check against the list of salesforce.com IP address list to ensure you have the right ranges whitelisted with your organization. You can find the reference to all the address spaces by clicking on "Help and Training" while logged into your environment, and then searching for "What salesforce.com network IP addresses do I need to whitelist?"

Additional resources -
CIDR notation - http://en.wikipedia.org/wiki/CIDR_notation
Subnetting - http://en.wikipedia.org/wiki/IPv4_subnetting_reference

Core Content

By Category

Other

Top Boards

By Category

Top Blogs

Services

Galleries

Other Web Sites

Technical Library

Contributors

RSS Feeds

Best Practices When Referencing Server Endpoints

Best Practices When Referencing Server Endpoints

Advisory Note: Instance Split Preparation

What is an instance split?

What action should you take?

Best Practices

For customized integrations

Hardcoded URL or IP address

How to find hard-coded references using the Force.com IDE

Salesforce Portal

WSDL File Generation

Certificate Usage

Whitelisting salesforce.com IP addresses