Use SOAP API

Learning Objectives

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

• Generate a WSDL file for your org.
  
• Use SoapUI to create a SOAP project from the WSDL file.
  
• Log in to your Trailhead Playground using SOAP API.
  
• Create an account using SOAP API.
  

Enterprise and Partner WSDLs

If you’ve sailed the straits of another SOAP-based API, you know that the Web Services Description Language (WSDL) file is basically your map to understanding how to use the API. It contains the bindings, protocols, and objects to make API calls.

Salesforce provides two SOAP API WSDLs for two different use cases. The enterprise WSDL is optimized for a single Salesforce org. It’s strongly typed, and it reflects your org’s specific configuration, meaning that two enterprise WSDL files generated from two different orgs contain different information.

The partner WSDL is optimized for use with many Salesforce orgs. It’s loosely typed, and it doesn’t change based on an org’s specific configuration. Typically, if you’re writing an integration for a single Salesforce org, use the enterprise WSDL. For several orgs, use the partner WSDL.

For this unit, we’re using the enterprise WSDL to explore SOAP API. The first step is to generate a WSDL file for your org. In your Trailhead Playground, from Setup, enter API in the Quick Find box, then select API. On the API WSDL page, click Generate Enterprise WSDL.

On the Generate Enterprise WSDL page, click Generate. When the WSDL is generated, right-click on the page and save the WSDL as an XML file somewhere on your computer. We’ll be using it shortly.

Here’s a tip for working with the enterprise WSDL. The enterprise WSDL reflects your org’s specific configuration, so whenever you make a metadata change to your org, regenerate the WSDL file. This way, the WSDL file doesn’t fall out of sync with your org’s configuration.

Create a SOAP Project with SoapUI

Now that we have our WSDL file, we need a way to extract the information to start making SOAP API requests. In web parlance, this process is called consuming the WSDL. Much like a kraken consumes a ship full of hapless sailors, tools such as the Web Services Connector (WSC) consume the WSDL file. The tools then create classes that enable you to make requests with SOAP API using common programming languages.

For this unit, we’re using a third-party tool called SoapUI to consume our enterprise WSDL file. SoapUI is a free and open-source app for testing web services. To get started, download and install SoapUI OpenSource from the SoapUI website. Install only the SoapUI component.

Ensure that the version of Java that SoapUI bundles and uses is compatible with your organization's security policies. You can find the version of Java that SoapUI uses by selecting Help | System Settings from within SoapUI. See www.soapui.org for more information.

After you get SoapUI installed and launched, from the File menu, select New SOAP Project. For the project name, enter Exploring Salesforce SOAP API. For the initial WSDL, browse to where you saved the enterprise WSDL file and select it. Don’t change any other options. Your SoapUI window looks something like this.

Click OK. After a few seconds of processing, an Exploring Salesforce SOAP API folder appears in the navigator panel on the left side of the screen. Underneath it is an entry called SoapBinding that contains several operations.

So what are we looking at here? Each operation corresponds to a SOAP API request we can make. The properties of each operation are pulled from information in the WSDL file. Each operation also contains a sample XML request that includes the operation’s HTTPS endpoint and a prepopulated SOAP message.

One more thing—Salesforce requires all connections to use TLS 1.2 or higher. If you’re using SoapUI with Java 7, TLS 1.2 isn’t enabled by default. If you try to connect to Salesforce with an old version of TLS, you’ll get an error message. The good news is that this is a pretty simple fix. Check out this handy-dandy blog post for more information.

Now we’re all set to make SOAP API requests. Full sail ahead, cap’n!

Log In to Your Trailhead Playground

In SoapUI, scroll down to the login operation. Expand it, and then double-click Request 1. A sample SOAP login request appears.

Here’s a quick breakdown of the endpoint URI (1).

• https://—Specifies secure HTTP.
  
• login.salesforce.com—Top-level domain for a login request.
  
• /services/Soap—Specifies that we’re making a SOAP API request.
  
• /c—Specifies that we’re using the enterprise WSDL. Use /u for the partner WSDL.
  
• /36.0—API version number. The v prefix is missing because some APIs include it before the version number, and some don’t. This behavior is just a quirk of Salesforce APIs.
  
• /0DF36000000LHZw—Package version number.
  

We aren’t using managed packages for this example, so we can remove the package version number from the end of the URI. Go ahead and do that now.

The SOAP message (2) contains everything we expect to find in a SOAP message: an envelope, a header, and a body.

The properties inside the LoginScopeHeader element concern the authentication of Self-Service and Customer Portal users. Because we don’t have to worry about these values for our purposes, delete the entire <urn:LoginScopeHeader> element (everything from <urn: LoginScopeHeader> to </urn:LoginScopeHeader>). Highlight the text in the window, and press the Delete key.

Next, look at the <urn:login> element in the message body. This element is the bulk of the login request. It’s where we provide our user credentials. Replace the ?s with your username and password for your Trailhead Playground.

To do this, you’ll need your Trailhead Playground credentials. From the App Launcher, find and open Playground Starter and follow the steps below. If you don’t see the Playground Starter app, check out Find the Username and Password for Your Trailhead Playground on Salesforce Help.

1. Click the Get Your Login Credentials tab and take note of your username.
   
2. Click Reset My Password. This sends an email to the address associated with your username.
   
3. Click the link in the email.
   

Since you’re making an API request from an IP address unknown to Salesforce, you need to append your security token to the end of your password. For example, if your password is mypassword and your security token is XXXXXXXXXX, enter mypasswordXXXXXXXXXX inside the <urn:password> element.

Click your Avatar in the upper right of the screen, select Settings, then choose Reset My Security Token under My Personal Information. Click Reset Security Token to send an email to the email address associated with your Trailhead Playground with your token.

Your SOAP message looks something like this.

Click the play button (green triangle) in the upper left of the request window. This button sends the request, casting your SOAP message-in-a-bottle into the sea. Here’s what it looks like when we expand the response.

Congratulations, captain. You successfully logged in. The response contains a bunch of information about your org and user. Most importantly, it contains your org’s My Domain name and a session ID that we’ll use to make future requests, highlighted here.

Copy the instance and session ID into a text file. We use them in a minute.

Because your org’s instance is likely to change, don’t hard-code references to the instance when you start building integrations! Instead, use your org's My Domain login URL. With My Domain, you configure a customer-specific domain for your Salesforce org. A My Domain not only eliminates the headache of changing instance names; you can also use it to highlight your brand, make your org more secure, and personalize your login page.

Create an Account

Just like we did with REST API, let’s create an account with SOAP API. In the navigation panel on the left side of the screen, find the create operation. Expand it, and double-click Request 1.

Because creating a record is more complicated than logging in, the create() SOAP message includes many more elements. Most of the elements are contained in the request header, and most of them are optional. To simplify things, we’ll delete most of the header info, but remember that the options provided by these headers are available when you create a record. For information on what each header does, check out the SOAP Headers topic in the SOAP API Developer Guide.

One header we don’t want to delete, though, is SessionHeader. It’s going to contain the session ID we got from the login() response. Go ahead and delete the other headers, from <urn:EmailHeader> to </urn:AssignmentRuleHeader>. Your message looks like this.

Get the session ID you copied to a text file and paste it inside the <urn:sessionId> tag, replacing the ?.

We have a few more adjustments to make to the message body. First, we specify that we’re creating an account. Change the text in the <urn:sObjects> tag to look like this: <urn:sObjects xsi:type="urn1:Account" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> . This adjustment specifies the correct record type using the XML instance schema declaration.

We also want to give the account a name. Add <Name>Sample SOAP Account</Name> inside the sObjects element. Delete the fieldsToNull and Id elements, too. Now your message looks something like this.

One last thing to do before we make the request. Change the endpoint to specify your org’s instance rather than login, and remove the package version from the end of the URI. The endpoint URI looks something like this: https://MyDomainName.trailblaze.develop.my.salesforce.com/services/Soap/c/36.0.

We’re ready to send the request. Click the green triangle again. It worked! Let’s look at the response.

Notice the LimitInfoHeader. This header returns information about your API usage. In the above example, we’ve made 9 out of 100,000 allowed calls today.

In the response body, notice the <result> element. <success>true</success> indicates that the record was created successfully. <id> includes the ID of the record, which you can use in future requests.

We covered the basics of making requests with SOAP API. Of course, each operation has its own parameters and peculiarities. Make sure that you use the SOAP API Developer Guide as your map when you start writing integrations with SOAP API.

Resources

• SOAP API Developer Guide
• SOAP API Cheatsheet
• SOAP API Sample WSDL Structures
• SOAP API Web Services Connector (WSC)
• SoapUI Homepage