// instantiate a SOAP connection to Salesforce
// catch Salesforce exception if there is one
try {
  $crmHandle->createConnection(SALESFORCE_WSDL);
} catch (Exception $e) {
  // handle exception - did you set the WSDL path above?

  // print out the exception string
  echo $e->getMessage();
}

If an exception occurs, and it’s not caught, it behaves more or less like a fatal error. PHP’s set_exception_handler() function provides a nice fallback, allowing you to avoid try/catching every method call. That’s pretty much all there is to it.

Tweet This Post 

- Objects (such as individual leads or contacts) have either a 15-character or an 18-character case-sensitive ID (e.g. 00Q6000000OaR87). You should not count on one format or the other being returned. The two formats can normally be used interchangeably (you can pass either version to an API call), but one notable exception to this rule is the Excel Connector, which integrates Salesforce and Excel. The 18-character version has some extra non-essential metadata about the object that’s not present in the earlier 15-character version. CORRECTION: This is wrong. The lesson here is that when your motivation for writing a blog is your horrible experience with your Salesforce integrators, you shouldn’t take what they say as gospel. David Schach pointed out that the 15-character version is simply case-sensitive. There is no metadata whatsoever. I apologize again for failing to fact-check this.

- Object IDs have a three-character prefix, which will be consistent for standard objects and will differ between instances for custom objects. This is not very well documented, and in fact, a Google search for “salesforce id prefix” returns no results (except this entry, after it gets indexed). If you don’t yet have any objects of a particular type, but need the ID, you can get it from the URL after clicking on the tab (or the ‘>’ to the right of the tabs if you don’t see the object you’re looking for). The URL will be something like ‘https://cs1.salesforce.com/00Q/o’, and the prefix is between the slashes (here, ‘00Q,’ for leads). Prefixes for common standard objects include:

• 00Q (Leads)
• 003 (Contacts)
• 001 (Accounts)
• 006 (Opportunities)
• 701 (Campaigns)
• 500 (Cases)

- Salesforce API logins (including logins from other third-party applications, like the Outlook tool) have the concept of a security token, which can be reset by going to Setup > My Personal Information > Reset My Security Token.

- Security tokens are appended to passwords when logging in via the API, so you might login with the username ‘joe’ and the password ‘mypasswordmytoken’.

- Security tokens change automatically when a password changes – watch out for this!

- There are no default administrator profiles whose passwords do not expire. This means that your API user’s password may expire, and your entire API integration will suddenly fail. I highly recommend making a new administrator profile called something like ‘Admins – Passwords Do Not Expire’ and adding your API and other back-end users to it. The original profile will not (currently) let you check the ‘Passwords do not expire’ checkbox.

- Avoid using the logout() call. As discussed before, all logins for a single user share a session id. Calling logout() will log out all concurrent connections for that Salesforce user via the API. Note also that this behavior is undocumented. Not to worry, the PHP Toolkit gracefully cleans up the SOAP connection for you.

- Deleted and merged data (e.g. deleted leads) can wreak havoc if your application relies on valid Salesforce IDs. Just because a lead exists today doesn’t mean Sales isn’t going to mass-delete those 10,000 ‘junk’ leads tomorrow.

- Salesforce objects are always referred to in the API in the singular form, so ‘Lead’ rather than ‘Leads.’

- Custom fields append __c to the field name, e.g. My_Custom_Field__c.

- There are a couple of Salesforce expressions that I’ll use here to be consistent, including ‘picklist’ to mean an HTML select element, ‘dependent picklist’ to mean a picklist whose appearance or values depend on another picklist, ‘auto number’ to mean an auto-increment field, and ‘upsert’ to mean a call that will update if a record with the specified ID exists, or else insert a new record.

Lastly, a quick aside about languages and operating systems. The code examples presented here assume a POSIX-compliant OS, such as Linux, but Windows-specific considerations should pretty much non-existent. PHP is fairly OS-agnostic for what we’re going to be doing, but inevitably there will be an OS-specific issue that will creep in. As far as portable paths go, PHP lets you use ‘/’ as a path separator in scripts on all OSes, but you could certainly instead use the native (and portable) DIRECTORY_SEPARATOR constant or ‘\\’ in the paths if you prefer. Lastly, in this blog, ‘native’ is taken to mean ‘native to PHP, written in C’ – an example of this is the native SOAP client (versus the much slower NuSOAP client written in PHP).

Tweet This Post 

Choosing the Right WSDL For You and Your Organization

Salesforce uses SOAP as its Web Services protocol, and SOAP uses an XML file called a WSDL (Web Services Definition Language) file that defines how a client (our code) can interact with a server (Salesforce). For our purposes, there are two different types of WSDL files, Enterprise and Partner. Here are the specifics:

Enterprise WSDL

• Is strongly typed
• Contains the metadata about all standard and custom fields and objects
• Can only be used against your Salesforce instance

Partner WSDL

• Is loosely typed
• Takes an array of key-value pairs
• Does not contain metadata about objects and fields
• Can be used against many Salesforce.com organizations

In our organization, we use the Enterprise WSDL, and the main reason why is that we like having a reference of all custom fields and objects readily available in the XML. Having the type of every field right there next to the field name at hand is nice as well. This being said, if we had a need to interact with many Salesforce.com instances, we might choose to use the Partner WSDL instead.

For the purposes of this blog, we’re generally going to be writing against the Enterprise WSDL, but our first example will be presented at the end in an ‘Enterprise’ version and a ‘Partner’ version. Those of you who find you prefer the Partner WSDL should be able to take the Partner example and adapt it in the future very easily.

Generating the WSDL

Each instance of Salesforce (each sandbox and production instance) will have their own corresponding WSDL file. It can be generated by going to Setup > Develop > API > Generate Enterprise WSDL (or Generate Partner WSDL) and downloading the generated XML. I prefer to keep the default name and put each file in a dev/, staging/, and production/ folder, but you could just as easily call the files dev.enterprise.wsdl.xml, or something to that effect.

Taking a Look at the Lead Generation Code

Now that we’re set up with our WSDL, let’s take a look at the code at the bottom of the previous post. I have removed the logout() call, after I read (and subsequently validated) this absolutely terrific article that pointed out that a user’s API connections all get the same session ID! This means that logout() actually invalidates all of the concurrent connections for that user. This is somewhat of an edge case for us, as page load times are generally very short, but all the same, we won’t be using the logout() call going forward. If you’re wondering, logging out through the Salesforce API does not log the same user out of any API connections. At any rate, here is the code, slightly modified, and this time with some comments:

Configuration passages:

define('SALESFORCE_USER', 'integration@example.com.sbox1');
define('SALESFORCE_PASS', '*password here*');
define('SALESFORCE_TOKEN', '*security token here*');
define('SALESFORCE_WSDL', '/path/to/enterprise.wsdl.xml');

Code:

require_once('SforceEnterpriseClient.php');

/**
 * explicitly turn off WSDL caching
 * there is a bug in PHP with this setting in php.ini
 * http://bugs.php.net/bug.php?id=41665
 * so it's safest to set it in the PHP source
 *
 * This param should take an int, not a string like most examples use
 * see http://us3.php.net/manual/en/soap.configuration.php
*/
ini_set('soap.wsdl_cache_enabled', 0);

// instantiate a new Salesforce Enterprise object
$crmHandle = new SforceEnterpriseClient();

// instantiate a SOAP connection to Salesforce
try {
  $crmHandle->createConnection(SALESFORCE_WSDL);
} catch (Exception $e) {
  // handle exception - did you set the WSDL path above?
  // we may also be in a Salesforce outage right now
}

// log in to Salesforce
try {
  $crmHandle->login(SALESFORCE_USER, SALESFORCE_PASS . SALESFORCE_TOKEN);
} catch (Exception $e) {
  // handle exception - did you modify the credentials above to your own?
}

// create our lead
$lead = array();
$lead['FirstName'] = 'Joe';
$lead['LastName'] = 'Moke';
$lead['Email'] = 'jmoke@example.com';
$lead['Title'] = 'CEO';

// create the lead
// $lead must be wrapped in an array, as create() can create
// many objects with a single API call
$result = $crmHandle->create(array($lead), 'Lead');

But Wait, Where’s Our Lead?

In this case, there was no exception thrown, but a var_dump() of the $result object will reveal what went wrong:

  ["errors"]=>
  object(stdClass)#8 (3) {
    ["fields"]=>
    string(7) "Company"
    ["message"]=>
    string(38) "Required fields are missing: [Company]"
    ["statusCode"]=>
    string(22) "REQUIRED_FIELD_MISSING"
  }
  ["id"]=>
  NULL
  ["success"]=>
  bool(false)

Salesforce will usually throw an exception when things go haywire, but not always, as in our example. When there is an error, and no exception is thrown, $result->success will equal false, so always be prepared for both possibilities, and you can re-throw or create an exception as it applies to your situation.

The REQUIRED_FIELD_MISSING error is actually fairly unusual to see in the API. In nearly all cases, creating and updating via the API will exempt you from populating required fields, except where it would render the resulting object useless (omitting LastName from a lead, for instance). So, let’s set the company, and take another look at var_dump($result):

$lead['Company'] = 'Bob\'s Country Bunker';

object(stdClass)#7 (2) {
  ["id"]=>
  string(18) "00QS00000034zU4MAI"
  ["success"]=>
  bool(true)
}

Creating a Lead with the Partner WSDL

As promised, the complete version that is compatible with the Partner WSDL is as follows:

define('SALESFORCE_USER', 'integration@example.com.sbox1');
define('SALESFORCE_PASS', '*password here*');
define('SALESFORCE_TOKEN', '*security token here*');
define('SALESFORCE_WSDL', '/path/to/partner.wsdl.xml');

require_once('SforcePartnerClient.php');

/**
 * explicitly turn off WSDL caching
 * there is a bug in PHP with this setting in php.ini
 * http://bugs.php.net/bug.php?id=41665
 * so it's safest to set it in the PHP source
 *
 * This param should take an int, not a string like most examples use
 * see http://us3.php.net/manual/en/soap.configuration.php
*/
ini_set('soap.wsdl_cache_enabled', 0);

// instantiate a new Salesforce Partner object
$crmHandle = new SforcePartnerClient();

// instantiate a SOAP connection to Salesforce
try {
  $crmHandle->createConnection(SALESFORCE_WSDL);
} catch (Exception $e) {
  // handle exception - did you set the WSDL path above?
  // we may also be in a Salesforce outage right now
}

// log in to Salesforce
try {
  $crmHandle->login(SALESFORCE_USER, SALESFORCE_PASS . SALESFORCE_TOKEN);
} catch (Exception $e) {
  // handle exception - did you modify the credentials above to your own?
}

// create our lead
$lead = new sObject();
$lead->type = 'Lead';
$lead->fields = array('FirstName' => 'Joe',
                      'LastName' => 'Moke',
                      'Email' => 'jmoke@example.com',
                      'Title' => 'CEO',
                      'Company' => 'Bob\'s Country Bunker');

// create the lead
// $lead must be wrapped in an array, as create() can create
// many objects with a single API call
$result = $crmHandle->create(array($lead), 'Lead');

WSDL Type Mismatches

Specifying the wrong WSDL such as pointing Salesforce to the Enterprise WSDL when you’re instantiating the SalesforcePartnerClient or vice-versa can give some obscure exception messages, such as this one:

Fatal error: Uncaught SoapFault exception: [soapenv:Client] Element {}item invalid
    at this location in /var/www...

Hopefully, if you see this message, this post will jog your memory.

API Coding Style

I always use the variable $crmHandle as the handle to my CRM object, and names like $lead or $contact as references to individual objects. From now on, we will leave the error/exception handling to you, as the different approaches vary widely. As Salesforce does routinely undergo maintenance, and does on occasion throw exceptions itself (Java socket exceptions, etc…) I would strongly recommend that you try/catch essential calls (e.g. createConnection()), and that you handle these exceptions in a way that doesn’t bring down your site if they occur. Registering a global exception handler with set_exception_handler() and re-throwing exceptions as CrmException($e->getMessage) or CrmCreateException… is certainly a good start.

User Input Considerations

There are a couple of simple things you can check user-supplied data for to avoid throwing exceptions left, right, and center.

• Validate email addresses. An extremely thorough, yet untested (by me) script can be found here. Salesforce will throw an exception if the email address is not RFC-compliant.
• Enforce field length limits. Have a look at Setup > Customize > {Object Name} > Fields for lengths. Data exceeding field lengths will throw an exception. Salesforce will trim whitespace for you, so factor that into your length calculations.

Documentation and References

Apart from the lack of PHP code examples, you’ll find that the API Developer’s Guide is an invaluable resource throughout your Salesforce PHP development.

A handy (and extensive) reference regarding the differences in capabilities and thresholds between the different Salesforce editions can be found here. This PDF is quite useful to keep at hand in order to understand exactly the limitations of your particular instance.

Wrapping Up

I realize this was lengthy, but to paraphrase Albert Einstein, I tried to make things as simple as possible, but not simpler. Coming up, we’ll take a look at some examples involving converting leads with the API, and creating and updating Contact and Account objects in Salesforce.

Tweet This Post 

Before we go any further, you must have either the Enterprise Edition or the Unlimited Edition to access the API with your production Salesforce.com instance. Those of you who are using the Group Edition or the Professional Edition can test your API code against the Developer Edition, by signing up here. However, there is currently a limit of 5,000 API calls per 24 hour period in the Developer Edition.

Downloading The Toolkit

Today, we’re going to walk through getting the PHP Toolkit set up and a sandbox copied off. Let’s start by downloading the Toolkit:

• Toolkit for PHP 5.2+
• Toolkit for PHP 5.1.2+
• Toolkit for PHP 5.0+ (free DeveloperForce login required)

All versions of the Toolkit require the curl, openssl, and soap extensions, the installation status of which can be determined by issuing `php -m` at the command line.

Unpacking the Toolkit

To set up the toolkit, simply unpack it. I normally unpack it to lib/crm/salesforce, but the only thing that’s really important is to keep the Toolkit in its own directory so it can easily be upgraded.

Sandboxes

If you have sandbox access, I highly recommend testing your code there before running it against your production instance. One reason for this (aside from inadvertently creating or deleting thousands of records, of course) is that the number of API calls per 24-hour period is metered, and once you’re out, you’re out. This means that if your site relies on Salesforce being available via the API to function correctly, the results could be very damaging to your business. If you have sandbox access, you can view your entitlement under Setup > Data Management > Sandbox. The current API limits can be found here.

If you don’t have a sandbox already, go ahead and clone one off by going to Setup > Data Management > Sandbox. The three types of sandboxes are:

• Configuration Only – Production configuration without the data. Holds 500 MB.
• Developer – The same as Configuration Only, but holds only 10 MB.
• Full – A full copy of your production instance.

A Configuration or Developer sandbox will be probably be fine, and if you do need a Full sandbox, keep in mind that it can take upwards of several hours to create. Also, sandboxes can only be refreshed every 30 days, and you can typically only have one full copy at a time. Another gotcha with sandboxes is that labels cannot currently be edited after the sandbox is created or refreshed, so go ahead and label yours now. You don’t want to have to worry about someone refreshing your critical sandbox instance because they didn’t realize it was in use. I tend to name my sandboxes ’sbox1′, ’sbox2′, etc., and to log into a sandbox called ’sbox1′, ‘user@example.com’ would log into SFDC at https://test.salesforce.com with the username ‘user@example.com.sbox1′ and the same password they use on production.

Yet another thing to bear in mind when cloning off a sandbox is that the process will copy over your existing workflow rules from production, and leave them active. This can cause a variety of issues, particularly if you have rules that trigger emails to mailing lists. Depending on your IT infrastructure, mail loops can inadvertently be created because of this. So, now would be a good time to disable any unnecessary workflow rules (under Setup > Create > Workflow & Approvals > Workflow Rules).

Finally, Some Code

We’ll go over this code in detail in the next entry, but I wanted to give you at least an idea of how straightforward it can be to develop against the API and integrate Salesforce and PHP. The following snippet will declare some configuration constants, log in, create a lead, and log out.

Configuration passages:

define('SALESFORCE_USER', 'integration@example.com.sbox1');
define('SALESFORCE_PASS', '*password here*');
define('SALESFORCE_TOKEN', '*security token here*');
define('SALESFORCE_WSDL', '/path/to/enterprise.wsdl.xml');

Code:

$crmHandle = new SforceEnterpriseClient();
$crmHandle->createConnection(SALESFORCE_WSDL);
$crmHandle->login(SALESFORCE_USER, SALESFORCE_PASS . SALESFORCE_TOKEN);

// create our lead
$lead = array();
$lead['FirstName'] = 'Joe';
$lead['LastName'] = 'Moke';
$lead['Email'] = 'jmoke@example.com';
$lead['Title'] = 'CEO';
$lead['Company'] = 'Acme Widget Corporation';
$result = $crmHandle->create(array($lead), 'Lead');

$crmHandle->logout();

Final Thoughts

I hope you enjoyed my first entry, and I hope it was helpful. I’ll generally be posting one or two entries a week, and next time, we’ll walk through getting your PHP environment configured to make the above snippet go, and start looking at some SFDC development considerations, gotchas, and quirks. See you again shortly!

Tweet This Post