Use SOAP API
- Generate a WSDL file for your org.
- Use SoapUI to create a SOAP project from the WSDL file.
- Log in to your DE org using SOAP API.
- Create an account using SOAP API.
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 DE org, 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 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.
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.
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 pane 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.1 or higher. If you’re using SoapUI with Java 7, TLS 1.1 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!
- 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.
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 DE org. Trailhead Playground orgs will require a password reset.
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. Your security token was emailed to you when you first reset your password after signing up for your DE org. If you’ve reset your password since then, a new security token was emailed to you. If you can’t find it, you can reset it in Salesforce.
- From your personal settings, enter Reset in the Quick Find box, then select Reset My Security Token.
- Click Reset Security Token. The new security token is sent to the email address in your Salesforce personal settings.
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 instance (or custom domain, if you’re using My Domain) 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 the Salesforce feature My Domain to configure a custom domain. A custom domain not only eliminates the headache of changing instance names, you can use it to highlight your brand, make your org more secure, and personalize your login page.
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://na30.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 15,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.