Updating Lookup Fields From PHP – Force.com Toolkit for PHP

Utilizing a Force.com backend for your data can prove to be a very challenging project. Perhaps you are trying to minimize development costs, or you are trying to utilize the Force.com backend that you already have. Either way, you’ve got a website front end built in PHP and you want it to be able to communicate back and forth between the Force.com backend.

SalesForce has a Force.com Toolkit for PHP, utilizing SOAP (XML-based protocol, which lets applications exchange information over HTTP). When set up and configured, your PHP application will have a SalesForce-generated WSDL file, which you will need to re-create through your SalesForce admin if the SalesForce data objects are altered in any way.

Force.com Toolkit for PHP – Requirements

  • PHP 5.x
  • SOAP Enabled
  • SSL Enabled
  • cURL Enabled
  • OpenSSL Enabled

What is a lookup field?

Take the Force.com default object called “Contact”, for example. A contact holds user data such as name, address, etc. A Contact also belongs to an “Account”, which is another default object in Force.com. The way that relation is created is by whats called a “Lookup” field in the Contact Object. This field contains a reference to the Account that the contact belongs to. It doesn’t just contain the AccountId, or an External ID (field set to be an External ID, something that gives you the ability to update an object from an external source such as a PHP application, based on the External ID). It contains more or less a reference to the object.

What’s the problem with updating the lookup field?

The problem is this. In your PHP application, you have to know what values are available to update the lookup fields with. You can’t just update a Contact with an Account Name (what shows up in the lookup field for Account, in the Contact object). Theoretically, that Account Name could be anything, and it is not necessarily an external identifier. You have to update it with the SalesForce ID (a hidden field for the Account object called AccountId) or by an external id in the Account Object.

The solution

This works for Upsert() or Create() methods. First, you need to know what Account you’re going to affiliate with the Contact, ahead of time. Then you’re going to need to get that Account’s AccountId or one of the External ID field values. Once you have that, you can pass that value in the Contact object as such (please note that I have stripped most of the code out and only left an upsert/create example):

// Force.com PHP Toolkit Files
require_once('path/to/files/soapclient/SforceEnterpriseClient.php');
require_once('path/to/files/soapclient/SforceHeaderOptions.php');
//
// Initialize variables
$sfdc = new SforceEnterpriseClient();
$SoapClient = $sfdc->createConnection("path/to/files/soapclient/enterprise.wsdl.xml");
$loginResult = $sfdc->login("salesforce_org_username","salesforce_org_password");
$savedUser = new stdClass(); // Just used standard php object class here for the example
//
// User Info - You can collect this info through POST, GET, Ajax,
// however method your application handles in. The parts of this object
// have to match the salesforce object you're going to save, we're
// going to use the Contact object.
$savedUser->FirstName = "Ralph";
$savedUser->LastName = "Higgins";
$savedUser->Email = "ralphhiggins@fakeemail.com";
//
// Instead of updating the Account.Name, which is not an external ID,
// you use this:
$savedUser->AccountId = "001V000000BdpiDLRF";
//
// Or alternatively, if you have an external ID in the Account
// Object named AccountUsername__c:
$savedUser->Account->AccountUsername__c = "TestAccount";
//
// Say we have a custom object named ContactPermission__c,
// which gives users a custom permission of Admin or User
// for your website, as a string. It's external ID is
// called ContactPermissionName__c, which is the text.
$savedUser->ContactPermission__r->ContactPermissionName__c = "Admin";
//
// Create the user
$savedUserResponse = $sfdc->create(array($savedUser),'Contact');
//
// If response is valid or invalid, display messages
if($savedUserResponse[0]->success == true) {
echo "User Saved!";
} else {
echo "User not saved!";
echo $savedUserResponse[0]->errors[0]->statusCode;
}

 

The downside

The problem with this solution, is you have to be dead-on accurate. If you’re trying to update a lookup field, you have to be updating it with a valid value which exists in the SalesForce data store already. The best practice would be to first pull the id for the Account you want to use, and then pass it in as the lookup field value when creating or updating the user. The upside, is that this helps you design for a more robust application from the start!

An Alternative?

Say for the user we just created, we wanted to give him/her a default ContactPermissionName__c value. In fact, we want to give ALL users the same default. We could just as easily create a Trigger in SalesForce side that will accomplish the same thing without having to add any code in the PHP application. This of course, limits scalability of the application and is only useful if this is something that will be permanent. Consider the code below, in which we automatically make all new users that are created (not upserted) with a default ContactPermissionName__c of “User” instead of “Admin”.

 

trigger SetDefaultPermission on Contact (before insert) {
     for(Contact thecontact: Trigger.new){
          Contact_Permission__c[] theid;
          theid = [SELECT Id FROM Contact_Permission__c WHERE Name = '1'];

          if(theid.size() > 0)
               thecontact.Contact_Permission__c = theid[0].id;
          }
     }
}

 

When I created the Contact_Permission__c custom object, I named the Record Name field “ContactPermissionId” and gave it an “Auto Number” type. This means each new Contact_Permission__c entry has an incremented number for this field. The ContactPermissionId of “User” is “1” whereas the ContactPermissionId of “Admin” is “2”. The code above saves a Contact’s Contact_Permission__c (lookup field) with a value of the SalesForce Id for the record where ContactPermissionId equals “1”, or “User”. The SalesForce Id is the back-end unique identifier that is invisible to users in SalesForce.

This “trigger” which can be set up under triggers in SalesForce, gets “triggered” when a new Contact is created. All new Contacts will now have a ContactPermissionName__c value of “User”.

I hope this helps someone out there, as it took me some research to fully understand the limitations and methods by which we can update Lookup fields in Salesforce, from PHP (or any other remote method).

About Curious Minds
We are a web development firm in New York and Chicago, providing development resources and consulting for websites and mobile apps since 2004.