August 2, 2011

Calling Marketo SOAP API from Salesforce APEX Classes !

We know about Marketo and its having a deep Salesforce integration.  Recently I came across a new requirement to call Marketo SOAP API from Apex. You must be thinking this process is pretty straight forward, but it required me a bit of effort to make it working, so thought of sharing this via blog and code on GIT, so that other busy developers can fork/reuse and save some time :)
I started falling in love with github.com, so the two core classes involved in this prototype are available there.  Here is the link to the repository : https://github.com/abhinavguptas/apex-marketo-soap-api-helper

Basic steps : From Marketo WSDL to Apex Stubs.

To start with I followed the normal steps to import a WSDL and generate Apex classes from it, i.e.
  • Download the required WSDL, I tried this one : http://app.marketo.com/soap/mktows/1_6?WSDL
  • Goto Setup > Develop > Apex Classes > Hit "Generate From WSDL" button
  • In the wizard next, feed the WSDL downloaded above to generate a single master apex class having everything. I named this WSDL2Apex class "Mktows.cls". For more details on this process, please refer to this Salesforce Guide.
Next, we will see what are the few things you need to make a successful call to Marketo SOAP operations.

Obtain Marketo UserId, Enc Key and SOAP Endpoint

All this information is available in Marketo Admin Console. Just goto Admin > Integration > SOAP API menu item in left side tree view. You will find all the details as indicated in the screenshot below
image

Setting up the Authorization Headers correctly !

This is the only tricky part in after generating WSDL2Apex stub i.e. Mktows.cls. Creating correct Marketo AuthorizationHeader requires a few things, like
  • Calculating a W3C Datetime format TimeStamp for request.
  • Calculating HMacSHA1 signature using
    1. the timestamp generated in previous step
    2. + Marketo User Id
    3. and Marketo Encryption Key
  • Converting that HMacSHA1 to Hex.
We are lucky that recently Apex added some super useful classes like
  • Datetime : That now takes Dateformat like “yyyy-MM-dd\'T\'HH:mm:ssZ” and converts the datetime value in that. This helped in generating the request timestamp.
  • Crypto : Super helpful in generating signatures for various algos like HMacSHA1
  • EncodingUtil : For generating Hex required for Marketo signatures.
Once this Auth Header is prepared correctly, we just need to associate it with WSDL2Apex Ports.

“MarketoClient.cls” – A helper class !

All the code to create correct AuthenticationHeader and associating it correctly with WSDL2Apex stubs is available in this class called MarketoClient.cls. This class is the core helper class that will prepare a correct Marketo SOAP Apex Port instance, that will be ready for making SOAP calls to various Marketo operations.
Here is a sample code that prepares the port using Marketo User Id and Encryption Key
String mktowsUserId = '[YOUR MARKETO USER ID]';
String encKey = '[YOUR MAKRETO ENCRYPTION KEY]';
// Instantiate MarketoClient using the userId and encKey
MarketoClient client = new MarketoClient(mktowsUserId, encKey);
// Get a readymade SOAP Port using prepareSoqpPort() call
MkTows.MktowsApiSoapPort port =  client.prepareSoapPort();

// Now one can call any method for ex.
// code below gets Lead for a given email via Marketo
Mktows.LeadKey objLeadKey=new Mktows.LeadKey();
objLeadKey.keyType='EMAIL';
objLeadKey.keyValue='abhinav@tgerm.com';
Mktows.ResultGetLead results =port.getLead(objLeadKey);
You might need to change the SOAP endpoint, its defaulting to 'https://na-c.marketo.com/soap/mktows/1_6' in MarketoClient class. Doing this is pretty simple, just update this static variable to required in MarketoClient.cls, for ex.
/**
Change this endpoint if required, as per your Marketo SOAP Endpoint*/
public static String API_ENDPOINT = 'https://na-c.marketo.com/soap/mktows/1_6';

Feedback & Views !

Would love to read your views and comments on this, please share !