Use asynchronous callouts to make long-running requests from a Visualforce page or a Lightning component to an external Web service and process responses in callback methods.
An asynchronous callout is a callout that is made from a Visualforce page or a Lightning component 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
A typical Salesforce application that benefits from asynchronous callouts contains a Visualforce page with a button. Users click that button to get data from an external Web service. For example, a Visualforce page that gets warranty information for a certain product from a Web service. Thousands of agents in the organization can use this page. Therefore, a hundred of those agents can 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 . 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.
1<apex:page controller="ContinuationController" showChat="false" showHeader="false">
2 <apex:form >
3 <!-- Invokes the action method when the user clicks this button. -->
4 <apex:commandButton action="{!startRequest}"
5 value="Start Request" reRender="result"/>
6 </apex:form>
7
8 <!-- This output text component displays the callout response body. -->
9 <apex:outputText id="result" value="{!result}" />
10</apex:page>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 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
1public with sharing class ContinuationController {
2 // Unique label corresponding to the continuation
3 public String requestLabel;
4 // Result of callout
5 public String result {get;set;}
6 // Callout endpoint as a named credential URL
7 // or, as shown here, as the long-running service URL
8 private static final String LONG_RUNNING_SERVICE_URL =
9 '<Insert your service URL>';
10
11 // Action method
12 public Object startRequest() {
13 // Create continuation with a timeout
14 Continuation con = new Continuation(40);
15 // Set callback method
16 con.continuationMethod='processResponse';
17
18 // Create callout request
19 HttpRequest req = new HttpRequest();
20 req.setMethod('GET');
21 req.setEndpoint(LONG_RUNNING_SERVICE_URL);
22
23 // Add callout request to continuation
24 this.requestLabel = con.addHttpRequest(req);
25
26 // Return the continuation
27 return con;
28 }
29
30 // Callback method
31 public Object processResponse() {
32 // Get the response by using the unique label
33 HttpResponse response = Continuation.getResponse(this.requestLabel);
34 // Set the result variable that is displayed on the Visualforce page
35 this.result = response.getBody();
36
37 // Return null to re-render the original Visualforce page
38 return null;
39 }
40}addHttpRequest method of the Continuation class. The callouts run in parallel for this continuation and suspend the Visualforce request. Only after the external service returns all callouts, the Visualforce process resumes.Note
Process for Using Asynchronous Callouts
To use asynchronous callouts, create a Continuation object in an action method of a controller, and implement a callback method.
Write tests to test your controller and meet code coverage requirements for deploying or packaging Apex. Because Apex tests don’t support making callouts, you can simulate callout requests and responses. When you’re simulating a callout, the request doesn’t get sent to the external service, and a mock response is used.
When a continuation is executing, the continuation-specific limits apply. When the continuation returns and the request resumes, a new Apex transaction starts. All Apex and Visualforce limits apply and are reset in the new transaction, including the Apex callout limits.
Making Multiple Asynchronous Callouts
To make multiple callouts to a long-running service simultaneously from a Visualforce page, you can add up to three requests to the Continuation instance. An example of when to make simultaneous callouts is when you’re making independent requests to a service, such as getting inventory statistics for two products.
Chaining Asynchronous Callouts
If the order of the callouts matters, or when a callout is conditional on the response of another callout, you can chain callout requests. Chaining callouts means that the next callout is made only after the response of the previous callout returns. For example, you might need to chain a callout to get warranty extension information after the warranty service response indicates that the warranty expired. You can chain up to three callouts.
Making an Asynchronous Callout from an Imported WSDL
In addition to HttpRequest-based callouts, asynchronous callouts are supported in Web service calls that are made from WSDL-generated classes. The process of making asynchronous callouts from a WSDL-generated class is similar to the process for using the HttpRequest class.
See Also
j