- 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 

• Privacy. No need to send your users’ passwords to Salesforce.
• Stability. No need to change your existing field names to match Salesforce.
• Security. The Web-to-Lead tool can be used to create spam leads. See here.
• Flexibility. Easily avoid creating duplicate leads by de-duping on email address.

There are two main advantages that the Web-to-Lead method holds, both in terms of simplicity:

• All of the form creation and handling is done for you.
• In case of an outage, queuing of the new leads is handled for you.

That Web-to-Lead queues your new leads during outages is not an inconsiderable point, and ‘queuing strategies and the API’ is a topic we’re going to discuss in the very near future. If you’re interested, you can learn more about Web-to-Lead here.

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