+ Start a Discussion

Important Changes to Salesforce.com NA1 Instance Configuration

As part of our continuing efforts to enhance service quality and availability, starting in May and continuing over the next few months, salesforce.com will be increasing the number of logical instances of the service.  Based on current experience managing instances of various sizes, including the NA1, EMEA, and AP instances, we believe these changes will advance our ability to improve delivery of the service today as well as enhance our scalability in the future. 

Because salesforce.com already operates using a multi-instance model, this change will have no impact for most users and developers. This note provides details associated with the change, as well as information on which uses of the AppExchange platform may be affected.

Background on Sign-on Server and Instance Redirection

A central part of using Salesforce and the AppExchange platform from either the Web user interface or Web service API is the concept of sign-on and redirection. When  users visit www.salesforce.com and log in via the login page, they are automatically redirected to the logical instance that contains their account. For example, after logging in, a user may be redirected to na1.salesforce.com or emea.salesforce.com, depending on the instance on which that user’s organization resides.

All modern versions of the API, including XML-RPC version 1.7+ and all versions of the SOAP API, operate on a similar principle, with the developer invoking a login call against www and then directing all subsequent calls to the URL and instance returned in that operation. This has been part of the standard development model of using the API for more than four years, and it is illustrated in all the documentation and samples available at developer.appexchange.com.

Managing the Transition

With the introduction of new logical instances, explicitly NA2, NA3, and NA4, integrations or code that is hard-wired to NA1 may no longer behave as expected. Below is a list of cases that will cause problems with this new system as well as directions for circumventing or avoiding those problems.

  • Developers using XML-RPC API 1.7 or earlier: The earliest versions of the API do not support instance redirection and are hard-coded to an instance (such as na1.salesforce.com). If you have code that uses this API, you need to either move to a more recent version of the API or hard-code the URL of the new instance that will map to your account (contacting support for the necessary information). If you are using  XML-RPC API 1.7 or earlier, we will attempt to proactively notify you via email; because a very small percentage of accounts do use this old version, it is unlikely you will be affected.
  • Developers not using the sign-on server: Although explicitly discouraged by the documentation and samples, it is possible to access the API by hard-coding the instance you are accessing rather than using the sign-on server and redirection. Your code should make login calls to www.salesforce.com rather than to a specific instance, such as na1.salesforce.com; if it does not, you should update it to do so or, worst case, hard-code your organization’s new instance URL.
  • Directly referencing an instance in a Web-to-Lead or other form: Wherever possible, salesforce.com will attempt to direct bookmarks and other direct references to a specific instance automatically to the new instance by inspecting the user’s cookie and login information. However, Web integrations such as Web-to-Lead, Web-to-Case, and the self-service portal that are hard-wired to a specific instance should instead be directed to www.salesforce.com.
Special support processes are now available to help any developers or customers who have questions about these changes or require assistance. Please contact support or post your questions to General Development forum if you have any questions about the new NA2, NA3, and NA4 instances going live.