SOAP Services: Defining a Class from a WSDL Document

To invoke an external service after using its WSDL document to generate an Apex class, create an instance of the stub in your Apex script and call the methods on it. For example, to invoke the StrikeIron IP address lookup service from Apex, you could write a script similar to the following:

  // Create the stub 
    
  strikeironIplookup.DNSSoap dns = new strikeironIplookup.DNSSoap();

  // Set up the license header 
    
  dns.LicenseInfo = new strikeiron.LicenseInfo();
  dns.LicenseInfo.RegisteredUser = new strikeiron.RegisteredUser();
  dns.LicenseInfo.RegisteredUser.UserID = 'you@company.com';
  dns.LicenseInfo.RegisteredUser.Password = 'your-password';

  // Make the Web service call 
    
  strikeironIplookup.DNSInfo info = dns.DNSLookup('www.myname.com'); 

You can set the HTTP headers on a Web service callout. For example, you can use this feature to set the value of a cookie in an authorization header. To set HTTP headers, add inputHttpHeaders_x and outputHttpHeaders_x to the stub.

Note

In API versions 16.0 and earlier, HTTP responses for callouts are always decoded using UTF-8, regardless of the Content-Type header. In API versions 17.0 and later, HTTP responses are decoded using the encoding specified in the Content-Type header.

The following samples work with the sample WSDL file in Understanding the Generated Code:

docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.inputHttpHeaders_x = new Map<String, String>();

//Setting a basic authentication header 
    

stub.inputHttpHeaders_x.put('Authorization', 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==');

//Setting a cookie header 
    
stub.inputHttpHeaders_x.put('Cookie', 'name=value');

//Setting a custom HTTP header 
    
stub.inputHttpHeaders_x.put('myHeader', 'myValue');

String input = 'This is the input string';
String output = stub.EchoString(input);

docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.outputHttpHeaders_x = new Map<String, String>();
String input = 'This is the input string';
String output = stub.EchoString(input);

//Getting cookie header 
    
String cookie = stub.outputHttpHeaders_x.get('Set-Cookie');

//Getting custom header 
    
String myHeader = stub.outputHttpHeaders_x.get('My-Header');

The following limits apply when an Apex script makes a callout to an HTTP request or a Web services call. The Web services call can be a Force.com Web Services API call or any external Web services call.

• A single Apex transaction can make a maximum of 10 callouts to an HTTP request or an API call.
• The default timeout is 10 seconds. A custom timeout can be defined for each callout. The minimum is 1 millisecond and the maximum is 60 seconds. See the following examples for how to set custom timeouts for Web Services or HTTP callouts.
• The maximum cumulative timeout for callouts by a single Apex transaction is 120 seconds. This time is additive across all callouts invoked by the Apex transaction.

docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.timeout_x = 2000; // timeout in milliseconds 
    

HttpRequest req = new HttpRequest();
req.setTimeout(2000); // timeout in milliseconds 
    

You can send a client certificate with your callout to authenticate an HTTPS connection with a specified value. Perform the following tasks to support client certificates:

1. Set up your Web server to request the SSL client certificate, also referred to as setting up two-way SSL. This process depends on the type of Web server you use and other environmental factors. An example of how to set up two-way SSL with Tomcat on Java has been posted to this blog: http://www.vorburger.ch/blog1/2006/08/setting-up-two-way-mutual-ssl-with.html.
2. Generate a PKCS12 key store with your client certificate.
3. Verify that the server's trust keystore contains (accepts) your client certificate.
4. Encode your client certificate key store in base64, and assign it to a variable on the stub, in this case, clientCert_x.

Note

The client certificate you use should be one obtained from a third party for your organization. Do not use the client certificate available from the Salesforce.com user interface.

The following example illustrates the last step of the previous procedure and works with the sample WSDL file in Understanding the Generated Code:

docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.clientCert_x =
'MIIGlgIBAzCCBlAGCSqGSIb3DQEHAaCCBkEEggY9MIIGOTCCAe4GCSqGSIb3DQEHAaCCAd8EggHb'+
'MIIB1zCCAdMGCyqGSIb3DQEMCgECoIIBgjCCAX4wKAYKKoZIhvcNAQwBAzAaBBSaUMlXnxjzpfdu'+
'6YFwZgJFMklDWFyvCnQeuZpN2E+Rb4rf9MkJ6FsmPDA9MCEwCQYFKw4DAhoFAAQU4ZKBfaXcN45w'+
'9hYm215CcA4n4d0EFJL8jr68wwKwFsVckbjyBz/zYHO6AgIEAA==';

// Password for the keystore 
    
stub.clientCertPasswd_x = 'passwd';

String input = 'This is the input string';
String output = stub.EchoString(input);

Apex supports only the document literal wrapped WSDL style and the following primitive and built-in datatypes:

Note

The Salesforce.com dataype anyType is not supported in WSDLs used to generate Apex code that is saved using API version 15.0 and later. For code saved using API version 14.0 and earlier, anyType is mapped to String.

Apex also supports the following schema constructs:

• xsd:all, in Apex code saved using API version 15.0 and later
• xsd:annotation, in Apex code saved using API version 15.0 and later
• xsd:attribute, in Apex code saved using API version 15.0 and later
• xsd:choice, in Apex code saved using API version 15.0 and later
• xsd:element. In Apex code saved using API version 15.0 and later, the ref attribute is also supported with the following restrictions:
  • You can call a ref in a different namespace by specifying the namespace.
  • A global element cannot use ref
  • If an element contains ref, it cannot also contain name or type
• xsd:sequence

The following data types are only supported when used as call ins, that is, when an external Web service calls an Apex Web service method. These data types are not supported as callouts, that is, when an Apex Web service method calls an external Web service.

• blob
• decimal
• enum

Apex does not support any other WSDL constructs, types, or services, including:

• RPC/encoded services
• WSDL files with mulitple portTypes, multiple services, or multiple bindings
• WSDL files that import external schemas. For example, the following WSDL fragment imports an external schema, which is not supported:

    <wsdl:types>
      <xsd:schema
       elementFormDefault="qualified"
       targetNamespace="http://s3.amazonaws.com/doc/2006-03-01/">
        <xsd:include schemaLocation="AmazonS3.xsd"/>
      </xsd:schema>
    </wsdl:types>
  

  However, an import within the same schema is supported. In the following example, the external WSDL is pasted into the WSDL you are converting:

    <wsdl:types>
      <xsd:schema
        xmlns:tns="http://s3.amazonaws.com/doc/2006-03-01/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified"
        targetNamespace="http://s3.amazonaws.com/doc/2006-03-01/">
  
        <xsd:element name="CreateBucket">
          <xsd:complexType>
            <xsd:sequence>
       [...]
      </xsd:schema>
    </wsdl:types>
  

• Any schema types not documented in the previous table
• WSDLs that exceed the size limit, including the Salesforce.com WSDLs