Apex Developer Guide

Getting Started
Writing Apex
Ways to Invoke Apex
Invoking Apex
Apex Transactions and Governor Limits
Using Salesforce Features with Apex
Integration and Apex Utilities
Invoking Callouts Using Apex
Adding Remote Site Settings
Named Credentials as Callout Endpoints
SOAP Services: Defining a Class from a WSDL Document
Invoking HTTP Callouts
Using Certificates
Callout Limits and Limitations
Make Long-Running Callouts from a Visualforce Page
Process for Using Asynchronous Callouts
Testing Asynchronous Callouts
Asynchronous Callout Limits
Making Multiple Asynchronous Callouts
Chaining Asynchronous Callouts
Making an Asynchronous Callout from an Imported WSDL
JSON Support
XML Support
Securing Your Data
Encoding Your Data
Using Patterns and Matchers
Finishing Touches
Reference
Appendices
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Make Long-Running Callouts from a Visualforce Page

Use asynchronous callouts to make long-running requests from a Visualforce page to an external Web service and process responses in callback methods. Asynchronous callouts that are made from a Visualforce page don’t count toward the Apex limit of 10 synchronous requests that last longer than five seconds. As a result, you can make more long-running callouts and you can integrate your Visualforce pages with complex back-end assets.
An asynchronous callout is a callout that is made from a Visualforce page for which the response is returned through a callback method. An asynchronous callout is also referred to as a continuation.

This diagram shows the execution path of an asynchronous callout, starting from a Visualforce page. A user invokes an action on a Visualforce page that requests information from a Web service (step 1). The app server hands the callout request to the Continuation server before returning to the Visualforce page (steps 2–3). The Continuation server sends the request to the Web service and receives the response (steps 4–7), then hands the response back to the app server (step 8). Finally, the response is returned to the Visualforce page (step 9).

Execution Flow of an Asynchronous Callout
Diagram for the execution flow of a continuation

A typical Salesforce application that benefits from asynchronous callouts is one that contains a Visualforce page with a button that users click to get data from an external Web service. For example, the Visualforce page might get warranty information for a certain product from a Web service. This page can be used by thousands of agents in the organization. Consequently, a hundred of those agents might click the same button to process warranty information for products at the same time. These hundred simultaneous actions exceed the limit of concurrent long-running requests of 10, but by using asynchronous callouts, the requests aren’t subjected to this limit and can be executed.

In the following example application, the button action is implemented in an Apex controller method. The action method creates a Continuation and returns it. After the request is sent to the service, the Visualforce request is suspended. The user must wait for the response to be returned before proceeding with using the page and invoking new actions. When the external service returns a response, the Visualforce request resumes and the page receives this response.

This is the Visualforce page of our sample application. This page contains a button that invokes the startRequest method of the controller that’s associated with this page. After the continuation result is returned and the callback method is invoked, the button renders the outputText component again to display the body of the response.

The following is the Apex controller that’s associated with the Visualforce page. This controller contains the action and callback methods.

Before you can call an external service, you must add the remote site to a list of authorized remote sites in the Salesforce user interface. From Setup, enter Remote Site Settings in the Quick Find box, then select Remote Site Settings, and then click New Remote Site.

If the callout specifies a named credential as the endpoint, you don’t need to configure remote site settings. A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. To set up named credentials, see “Define a Named Credential” in the Salesforce Help. In your code, specify the named credential URL instead of the long-running service URL. A named credential URL contains the scheme callout:, the name of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path.

Note

  • You can make up to three asynchronous callouts in a single continuation. Add these callout requests to the same continuation by using the addHttpRequest method of the Continuation class. The callouts run in parallel for this continuation and suspend the Visualforce request. Only after all callouts are returned by the external service for does the Visualforce process resume.
  • Asynchronous callouts are supported only through a Visualforce page. Making an asynchronous callout by invoking the action method outside a Visualforce page, such as in the Developer Console, isn’t supported.
  • Asynchronous callouts are available for Apex controllers and Visualforce pages saved in version 30.0 and later. If JavaScript remoting is used, version 31.0 or later is required.

Note