img1

Learning Objectives

After completing this article, you’ll be able to:

Preface

Checkout the following related articles:

Prologue

SOAP API Salesforce integration and SOAP Apex Callouts will be the main subject of discussion today. To use SOAP API, you will need to have a Web Services Description Language (WSDL) file.

Web Services Description Language (WSDL)

What is a WSDL? An Web Services Description Language (WSDL) is an XML-based file that basically tells the client application what the web service does. The WSDL file is used to describe in a nutshell what the web service does and gives the client all the information required to connect to the web service and use all the functionality provided by the web service. I won’t dive into the nitty of WSDL as it is pretty complex and requires a full walk through.

Structure of a WSDL Document

A WSDL document is used to describe a web service. This description is required, so that client applications are able to understand what the web service actually does. the WSDL is just like a postcard which has the address of a particular location. The address provides the details of the person who delivered the postcard. Hence, in the same way, the WSDL file is the postcard, that has the address of the web service which can deliver all the functionality that the client wants.

  1. The WSDL file contains the location of the web service
  2. The WSDL file exposes methods to be consumed

Below is the general structure of a WSDL file:

  1. Definition
  2. TargetNameSpace
  3. DataTypes
  4. Messages
  5. PortType
  6. Bindings
  7. Service

Why WSDL

A web service is an important component in building modern day web applications. Their main purpose is to allow multiple applications built on various programming languages to talk to each other.

Apex and WSDL

Working with SOAP can be a painful experience. Luckily, tools exist that can help us work with SOAP with Apex. Namely WSDL2Apex, WSDL2Apex automatically generates Apex classes from a WSDL document. You download the web service’s WSDL file, and then you upload the WSDL and WSDL2Apex generates the Apex classes for you. The Apex classes construct the SOAP XML, transmit the data, and parse the response XML into Apex objects.

Note: Use outbound messaging to handle integration solutions when possible. Use callouts to third-party web services only when necessary.

Understanding Outbound Messaging

Outbound messaging allows you to specify that changes to fields within Salesforce can cause messages with field values to be sent to designated external servers. In laymen terms, when a field change occurs, a triggered event will subsequently send that field value to a specified web service. Outbound messaging is part of the workflow rule functionality in Salesforce. Workflow rules watch for specific kinds of field changes and trigger automatic Salesforce actions, such as sending email alerts, creating task records, or sending an outbound message. Outbound Messaging will not be explored in detail in this article.

img2

Apex Classes generated from WSDL

The WSDL document can be at most 1MB. When the document is parsed, each namespace becomes an Apex class. Save this file as locator.xml. Follow the steps listed below to generate an Apex Class from the WSDL file downloaded.

  • Authorize Endpoint using Remote Sites
  • From Setup, enter Apex Classes in the Quick Find box, then click Apex Classes
  • Click Generate from WSDL
  • Click Choose File and select the downloaded locator.xml file
  • Click Parse WSDL, confirm the Apex class name (ParkService) after parsing
  • Click Done (For each generated class, a second class is created with the same name and the prefix Async)

Execute Generated Classes

Create the following feature class to manipulate the web service. Then Launch developer console > Debug. Instantiate the ParkLocator, then call country method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

public class ParkLocator  {

    private ParkService.ParksImplPort service;
    public ParkLocator (){
        this.service = new ParkService.ParksImplPort();
    }
    
    public String[] country(String location){
        //Possible names include {Germany, India, Japan and United States}
        String[] parks = this.service.byCountry('India');
        return parks;
    }
}

img4

Testing Web Service Callouts

Testing Web Service Callouts is not that painful due to the enormous help given by the WSDL2Apex tool. The following are required in order to test web service callouts successfully, because test methods don’t support web service callouts, and tests that perform web service callouts fail.

  • Apex provides a built-in WebServiceMock interface and the Test.setMock method
    • This must be first method called in your test class
    • This instructs the Apex runtime to send the fake response by calling Test.setMock before making the callout
  • You need to specify a Mock Response for Callouts, implement WebServiceMock
    • Your implementation of WebServiceMock calls the doInvoke method, which returns the response you specify for testing

Test Example

The snippet demonstrates a very basic test suite.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

@isTest
global class ParkServiceMock implements WebServiceMock{
    global  void doInvoke( Object stub,
           Object request,
           Map<String, Object> response,
           String endpoint,
           String soapAction,
           String requestName,
           String responseNS,
           String responseName,
           String responseType){
        
       ParkService.byCountryResponse countryResponse = new ParkService.byCountryResponse();
       countryResponse.return_x = new String[]{'Anamudi Shola National Park', 'Anshi National Park', 'Bandipur National Park'};    
       response.put('response_x', countryResponse);              
    }
}

Key take aways from the above snippet:

  1. The method your testing will always have the suffix Response. Example byCountryResponse.
  2. Always set the return_x property for the instantiated response.
    1. This is the mock response you will be testing against.
  3. Populate Map<String, Object> response, by putting the 'response_x' key to the response instantiated.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

@isTest
public class ParkLocatorTest {
@isTest
    public static void testCountryParks(){
        Test.setMock(WebServiceMock.class, new ParkLocatorMock());
        ParkLocator locator = new ParkLocator();
		String[] parks = locator.country('India');
        String[] parkResponse = new String[]{'Anamudi Shola National Park', 'Anshi National Park', 'Bandipur National Park'};
        System.assert(parks != null);
        for(Integer i = 0; i < parkResponse.size(); i ++){
            System.assert(parks[i] == parkResponse[i], 'Incorrect park');
        }
    }
    
}

Exposing Apex Methods as SOAP Web Services

You can expose your Apex methods as SOAP web services so that external applications can access your code and your application. To expose Apex methods, webservice Methods must be used.

Apex SOAP web service VS Apex callouts

Apex SOAP web services allow an external application to invoke Apex methods through SOAP Web services. Apex callouts enable Apex to invoke external web or HTTP services.

Webservice Methods

The webservice keyword is used in Apex to expose class methods, hence allowing external application communication. Code example below:

Code Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

global class CaseWebService {
    webservice static ID createCase(String subject, String status, String priority){
        Case record = new Case();
        record.Status = status;
        record.Subject = subject;
        record.Priority = priority;
        insert record;
        return record.Id;
    }
}

Generate WSDL from Webservice Methods

Follow the following steps to generate an Web Services Description Language (WSDL). A developer of an external application can integrate with an Apex class containing webservice methods by generating a WSDL for the class.

  • Copy the snippet above and create a new class from it
  • Navigate to Setup, type “Apex Classes”
  • Click the C column and look for CaseWebService
  • Click Generate WSDL

Security Considerations

Invoking a custom webservice method always uses system context. Consequently, the current user’s credentials are not used, and any user who has access to these methods can use their full power, regardless of permissions, field-level security, or sharing rules. Developers who expose methods with the webservice keyword should therefore take care that they are not inadvertently exposing any sensitive data. Please consider the following recommendations whenever possible:

  • Please ensure that you make use of the appropriate object or field describe result methods to check the current user’s access level on the objects and fields that the webservice method is accessing
  • sharing rules (record-level access) are enforced only when declaring a class with the with sharing keyword

Considerations to be aware of

When using the webservice keyword, keep the following considerations in mind:

  • Use the webservice keyword to define top-level methods and outer class methods. You can’t use the webservice keyword to define a class or an inner class method.
  • You cannot use the webservice keyword to define an interface, or to define an interface’s methods and variables.
  • System-defined enums cannot be used in Web service methods.
  • You cannot use the webservice keyword in a trigger.
  • All classes that contain methods defined with the webservice keyword must be declared as global. If a method or inner class is declared as global, the outer, top-level class must also be defined as global.
  • Methods defined with the webservice keyword are inherently global. Any Apex code that has access to the class can use these methods.
  • Any method that uses the webservice keyword must be static.
  • You cannot deprecate webservice methods or variables in managed package code.
  • Use the webservice keyword with any member variables that you want to expose as part of a Web service. Do not mark these member variables as static.
  • SOAP and WSDL do not provide good support for overloading methods.
    • Consequently, Apex does not allow two methods marked with the webservice keyword to have the same name. Web service methods that have the same name in the same class generate a compile-time error.

Epilogue

Ahoy, that was quite the journey we did there. We explored SOAP, it’s different constituents namely the WSDL document that describes the service itself and provides the information needed for external clients to consume the service methods. We also saw the importance of the WSDL file, and the different ways the Salesforce platform provides the means to create, parse and consume SOAP webservices. SOAP Apex callouts was also explored, this included code examples to create and test such callouts. After that we started to discuss how to describe a WSDL from a apex class, detailing the different the security and general considerations you will need to take into account when generating your own WSDL file on the platform. Thanks for stopping by and I hope you were able to learn or reinforce your knowledge regarding SOAP Callouts and Webservices on the Salesforce platform 😃