Home / content / Calling ET SOAP API from Salesforce.com (SFDC) Using APEX HTTPRequest Call

Calling ET SOAP API from Salesforce.com (SFDC) Using APEX HTTPRequest Call

3720 points
jmeketa's picture

 

Calling ExactTarget Web Services (SOAP) API from SFDC Using APEX HTTPRequest

 

 

SFDC(APEX) cannot consume and properly expose the ExactTarget (ET) Web Services (SOAP) API WSDL file for use – it’s just too large and complex. For this reason, ExactTarget suggests writing a middle tire/proxy web application in .NET, Java, PHP, or another applicable language to consume the ExactTarget and SFDC WSDLs properly and allow for easier development between the two systems. You would then be able to call your web application from SFDC and pass the appropriate IDs and information using query string parameters (or another preferred method).

 

This preferred method gives you the ability to write SOAP Requests leveraging the WSDL objects and ultimate flexibility.

 

However, we’ve seen a variety of use cases where someone simply wants to build a SOAP Request manually (XML) and submit to the ExactTarget web service endpoint directly from an APEX Trigger or Page using the APEX HTTPRequest object. Typically, the developer chooses this path because they have only one spot of integration from SFDC or their IT department does not want to support a solution outside of SFDC or a middletier app.

 

Since we get questions all the time on doing this less preferred scenario, I decided to write a quick blog post on how to accomplish the setup for a successful call. This example does not show XML parsing of results for possible use in SFDC/APEX. It merely enables your SOAP call to ExactTarget to succeed.

 

Step 1 – Access to ET Web Service

 

You must first give your SFDC organization access to call the ExactTarget Web Services API. Be sure to use the correct endpoint for your ExactTarget instance. If you don’t know what instance your ExactTarget account uses, simply log in to the ExactTarget application and note the URL of the success screen. If you note an S4 or S6 in the URL, use the appropriate endpoint.

ET Server Stack - Web Services End Point
S1 - https://webservice.exacttarget.com/Service.asmx
S4 - https://webservice.s4.exacttarget.com/Service.asmx
S6 - https://webservice.s6.exacttarget.com/Service.asmx
Production Support (Test) - https://webservice.test.exacttarget.com/Service.asmx

 

You must add the appropriate web service endpoint into your SFDC Remote Sites:

1. Navigate to Setup

2. Select Administrative Setup.

3. Select Security Controls.

4. Select Remote Sites.

5. Add the information shown below:

SFDC Remote Sites

SFDC Remote Site Settings

 

You’ll also want to add the appropriate ExactTarget IP addresses to be whitelisted in SFDC using the Network Access section. You must add the appropriate web service endpoint IP ranges into your SFDC Network Access:

1. Navigate to Setup.

2. Select Administrative Setup.

3. Select Security Controls.

4. Select Network Access and add the appropriate information for your instance. The IP address ranges for ET in SFDC are listed below.

 

ET Server Stack: IP Start Address - IP End Address

S1:          206.246.157.1 - 206.246.157.6

                66.231.91.195 - 66.231.91.195

S4:          66.231.94.250 -  66.231.94.252

                64.79.134.164 - 64.79.134.164

S6:          68.232.203.56     - 68.232.203.63

Production Support (Test):         
              207.250.76.176 - 207.250.76.183

                207.250.79.96 - 207.250.79.110

                207.67.53.64 - 207.67.53.78

                207.67.66.192 - 207.67.66.222

 

The screenshot below illustrates the two ranges for the S1 stack highlighted with orange boxes:

 

SFDC Network Access Settings

 

Step 2 – Write APEX Code

 

Next, you’ll need to create your APEX Page or Trigger from which you will be calling the ExactTarget Web Services API. You must know the appropriate XML for the SOAP call, since you will be supplying it as string you build in the APEX code. Below is an example call for an APEX page that returns all of the subscriber lists in an ExactTarget account. Keep in mind that you can leverage and SFDC IDs/information available to you in building the XML in SOAP Request. For simplicity, I have the entire SOAP Request XML statically added to the variable called xml. Replace ##USERNAME## and ##PASSWORD## with the appropriate credentials.

public class ExactTargetSOAP {
    public static List<String> getEmailList(){
        String xml = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header><wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"><wsse:UsernameToken wsu:Id="UsernameToken-24440876" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:Username>##USERNAME##</wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">##PASSWORD##</wsse:Password></wsse:UsernameToken></wsse:Security></soapenv:Header><soapenv:Body><RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI"><RetrieveRequest><ObjectType>List</ObjectType><Properties>ID</Properties><Properties>List.ListName</Properties><Properties>List.Type</Properties><Properties>List.Category</Properties><Properties>Client.ID</Properties></RetrieveRequest></RetrieveRequestMsg></soapenv:Body></soapenv:Envelope>';
        makeRequestNow(xml);
        return null;
    }
 
    private static void makeRequestNow(String xml){
        Http h = new Http();
        HttpRequest req = new HttpRequest();
        req.setMethod('POST');
        req.setHeader('SOAPAction','Retrieve');
        req.setHeader('Accept-Encoding','gzip,deflate');
        req.setHeader('Content-Type','text/xml;charset=UTF-8');
        req.setHeader('User-Agent','Jakarta Commons-HttpClient/3.1');
        req.setBody(xml);
 
        req.setEndpoint('https://webservice.exacttarget.com/Service.asmx');
 
        string bodyRes = '';
 
        try {
            HttpResponse res = h.send(req);
            bodyRes = res.getBody();
            } 
            catch(System.CalloutException e) {
            System.debug('Callout error: '+ e);
            ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.FATAL, e.getMessage()));
            }
        System.debug('Soap request:' + xml);
        System.debug('Soap response:' + bodyRes);
 
        ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.INFO,bodyRes));
       }
  }

Please review the above code and note that all of the header values in the request shown above should be set to create a valid SOAP call. The code above changes the SOAPAction header. The code performs a Retrieve call so that the variable is set to that value. Possible values for this include the list shown below:

 

ET SOAP Actions

 

You can use the Remote Site name instead of specifying the URL for the endpoint. Also note that the call captures the response object is being captured and outputs that object to the screen (shown below).

Your code will most likely perform XML parsing of the results depending on the response type. For a create, delete, perform, or update action, you might check to see if the StatusCode in the response is set to OK.

 

ET SOAP Response in SFDC

Product Group: 

Comments

107 points
SFGene's picture

Hello. Great tutorial. I'm currently in the process of doing this for my organization and am fairly new to XML and SOAp so I am a little confused.

What I need to do is send the email body, subject line, user email, and client email over to Exact Target so a 1 time (Triggered Send) email could be sent. My confusion is over the following:

req.setMethod('POST');
req.setHeader('SOAPAction','Retrieve');
req.setHeader('Accept-Encoding','gzip,deflate');
req.setHeader('Content-Type','text/xml;charset=UTF-8');
req.setHeader('User-Agent','Jakarta Commons-HttpClient/3.1');


What does it all mean? The documentation online is almost non-existant. Is the "Accept-Encoding" necessary? What parameters need to be coupled and are available with the SOAPAction? What does the User-Agent and Jakarta mean?

I Have the following inside the soapenv:Body:

<TriggeredSend xmlns="https://webservice.s4.exacttarget.com/etframework.wsdl">

                <TriggeredSendDefinition>

                <Email>

                   <Name>SF API Test</Name>

                   <Folder>my emails/Test</Folder>

                     <HTMLBody></HTMLBody>

                     <TextBody></TextBody>

                     <Subject></Subject>

                  </Email>

                  <EmailSubject></EmailSubject>

                </TriggeredSendDefinition>

                <Subscribers>

                <Subscriber>

                <EmailAddress></EmailAddress>

               <Status>

               <SubscriberStatus>Active</SubscriberStatus>

               </Status>

               <EmailTypePreference>

               <EmailType>HTML</EmailType>

               </EmailTypePreference>

                </Subscriber>

                </Subscribers>

                <Attributes>

                <Attribute>

                <Attribute>

               <Body></Body>

               <Value></Value>

               </Attribute>

                </Attribute>

                </Attributes>

           </TriggeredSend>

I'm assuming the xmlns="https://webservice.s4.exacttarget.com/etframework.wsdl" is correct since, from what I can gather, it is supposed to point to the wsdl that interpret the message. In this case it would be for the s4 webservice. I've already set the endpint to https://webservice.s4.exacttarget.com/Service.asmx.