A Callout is an outbound integration from Salesforce to an external system. These are my notes on this topic while working towards the Integration Architect certification.
Apex Callouts are used to integrate Salesforce with an external system by making a call to an external web service (using SOAP and WSDL), or sending an HTTP request and receiving a response (RESTful services).
A key element to Apex Callouts whether SOAP or REST-based is Remote Site Settings or Named Credentials. Salesforce requires calls to external networks to be authorised.
Remote Site Settings
These are located under Security / Remote Site Settings in Salesforce Setup. To create a Remote Site, simply click on New Remote Site and add the name and URL.
You can optionally opt to disable Protocol Security. Protocol Security prevents data from passing from an HTTPS session to an HTTP session or the other way round.
Leave the check box active.
Tip: Complete the description box so that not only you but other, and future, administrators know why this remote site has been created.
Named Credentials
The Apex Developer Guide states the following for Named Credentials used as Callout Endpoints:
“A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. Salesforce manages all authentication for Apex callouts that specify a named credential as the callout endpoint so that your code doesn’t have to. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the named credential.”
They are supported in Apex Callouts, External Services, and External Data Sources via Salesforce Connect.
Named Credentials are located under Security / Named Credentials. Click the new Named Credential button to create a new one. Add a Label (for Salesforce User Interface use), a Name (the Unique Identifier you will use with the API), and the URL (the endpoint for your external web service).
There is a section to set up the authentication settings. A certificate can be uploaded, and the Identity Type can be either Anonymous, Named Principal (for org-wide authorisation), or Per User (for individual user authorisation). If a certificate is uploaded and specified, this will be used when establishing the two-way SSL connection with the external system and for providing a digital signature to the Callout. The Authentication Protocol can be changed to OAuth 2.0, Password Authentication, AWS Signature Version 4, JWT, or JWT Token Exchange. Depending on the Authentication Protocol selected, additional fields will appear to capture the information required to support that protocol.
Finally, the Callout Options need to be set. By default the Generate Authorization Header checkbox is ticked. This is so that all Callouts that use this Named Credential have the authorisation in the Header. There may be an endpoint that does not support authorisation headers. If that is the case, deselect this option and provide the authorisation via code.
The two Allow Merge Fields checkboxes are there to enable relevant fields from this Named Credential to be merged into the Callout’s header or body.
The Callout options include an Outbound Network Connection field that can be utilised to route callouts through a private connection. This separates the endpoint URL and authentication from the callout definition.
SOAP Callouts to Third Party Web Services
When using SOAP Callouts, the Apex classes can be created automatically from a WSDL document that describes the third Party Web Service the callout is accessing. From Custom Code / Apex Classes click Generate from WSDL.
WSDL2Apex generates the Apex classes to construct the SOAP XML, transmit data and parse XML responses.
Complete this Trailhead Module to get a feel of generating a SOAP Callout from an xml file. You will see that uploading a WSDL generates two classes, one will be for synchronous callouts and one for asynchronous callouts.
Ensure the endpoint has been authorised in a Remote Site Setting or a Named Credential.
Salesforce requires test classes to be created for Apex code so that there is a minimum of 75% coverage in order for it to be deployed or packaged. Test classes do not support web service callouts. Mock test methods for the callouts need to be created. To send a mock test response, use Test.setMock method and the WebServiceMock interface. To learn more about this go to the Test Web Service Callouts in the Apex Developer Guide.
HTTP Callouts
Rather than using WSDL to generate SOAP-based web services, and also to integrate REST-based services, Apex’s HTTP classes can be used to generate the code. The Http Class initiates the Http Request and Response. Http Requests are created programmatically to use HTTP verbs such as GET (retrieve data), POST (create a resource or post data), PATCH (Partially modify a resource), PUT (replaces a resource with the request payload), and DELETE amongst others. See more about HTTP request methods here.
HTTP Requests support a message body, request headers, read and connection timeouts, and necessary redirects. HttpResponse supports headers and response body as well as an HTTP Status code. HttpResponse Class hands the HTTP response returned following the request. Either XML or JSON can be used for the content in the request and response body.
Test Classes for HTTP Callouts are similar to the SOAP Callouts save that it is also possible to use Static Resources for the Mock Callout. Read more here about Testing HTTP Callouts.
Continuation Calls
Asynchronous Callouts have a call and callback pattern called a Continuation. This prevents a typical synchronous Callout holding a thread resource open and waiting as long as it takes for a response to be returned (and sometimes timing out). A Continuation enables the thread to pause or sleep while waiting for the callout to return. When working with the Apex Continuation class a Continuation Object is used and Salesforce also uses a separate server for this type of web service request. It allows for the thread resource to be released until a response is returned and then it carries on from that point.
A Continuation Call using the Apex continuation class does not count towards the Apex limit of 10 synchronous requests that last longer than 5 seconds.
Note that Data Manipulation Languages (DML) operations cannot be performed in an apex method that returns a Continuation Object.
Read more about making long-running Callouts with Continuations here.
This means that a continuation asynchronous callout from a button on a Visualforce page using a continuation controller will enable a user to click it and wait for the response from the external system that will then refresh the User Interface.
Testing continuation classes involves using Test.setContinuationResponse and TestinvokeContinuationMethod. Again it will be a simulation rather than a true callout made in the test class.
Authenticating Callouts
Two-way SSL authentication is recommended with Callouts. To use it, generate a Salesforce certificate or upload a certificate signed by a Certificate Authority (CA). The receiving party must have the same certificate in their keystore. As mentioned above with Named Credentials, there is an option to select a certificate when creating it.
Securing Callouts
To secure callouts, methods from Apex’s Crypto Class can be used. These provide algorithms for encrypting and decrypting information as well as other elements. Crypto Classes can be used for securing integrations with external services such as Amazon WebServices.
It is also possible to encode and decode URLS and to convert strings using the EncodingUtil class.
Limits and Limitations
For a full list, see Callout Limits and Limitations. A few I want to highlight are:
- A maximum of 100 Callouts to an HTTP Request or an API call in a single Apex transaction.
- Callouts can only be made before DML operations
- The default timeout is 10 seconds. The maximum is 120 seconds.