Working with the folks over at MK Partners on some recent projects, I’ve learned how to call into Apex Web Services from PHP. It’s actually pretty easy. Special thanks for Simon Fell for helping me through a particularly tricky part.

Apex Web Service Class

A simple web service class is below. The method we call from PHP is myMethod. There are 2 inner classes that are used to capture inputs and send back outputs to PHP.

global class MyWebService {

    // A class to accept an array of input records (e.g. product/amount combinations)
    global class myInputs{
        webservice Id productId;
        webservice Double amount;
    }

    // A class to send back as an output to PHP
    global class myOutputs{
        webservice String errorMessage;
        webservice Boolean success;
        webservice List<myInputs> inputs;
        webservice Id contactId;
    }

    // The actual web service method we will call
    webservice static myOutputs myMethod(Id contactId, List<myInputs> inputs){

        /*
        * Write a bunch of code here to do all kinds of stuff.
        */

        myOutputs output = new myOutputs();
            output.errorMessage = 'No errors here.';
            output.success = true;
            output.inputs = inputs;
            output.contactId = contactId;
        return output;

    }
}

PHP

Login like you normally would using the PHP toolkit. Nothing new here. The final part is defining some constants for use later when we call the web service.

// Include the PHP Toolkit
require_once('salesforceAPI/SforcePartnerClient.php');
require_once('salesforceAPI/SforceHeaderOptions.php');

// Login
$sfdc = new SforcePartnerClient();
$SoapClient = $sfdc->createConnection('salesforceAPI/wsdl.xml');
$loginResult = false;
$loginResult = $sfdc->login('user@domain.com', 'password' . 'securitytoken');

// Define constants for the web service. We'll use these later
$parsedURL = parse_url($sfdc->getLocation());
define ("_SFDC_SERVER_", substr($parsedURL['host'],0,strpos($parsedURL['host'], '.')));
define ("_WS_NAME_", 'MyWebService');
define ("_WS_WSDL_", _WS_NAME_ . '.xml');
define ("_WS_ENDPOINT_", 'https://' . _SFDC_SERVER_ . '.salesforce.com/services/wsdl/class/' . _WS_NAME_);
define ("_WS_NAMESPACE_", 'http://soap.sforce.com/schemas/class/' . _WS_NAME_);

Next we will call the web service. First thing to do is setup a Soap Client and modify the headers. Then we are setting up some fake data that maps to the expected inputs of the myMethod method in the web service. Then we actually call the web service.

// SOAP Client for Web Service
$client = new SoapClient(_WS_WSDL_);
$sforce_header = new SoapHeader(_WS_NAMESPACE_, "SessionHeader", array("sessionId" => $sfdc->getSessionId()));
$client->__setSoapHeaders(array($sforce_header));

// Setup fake data to send into the web service
$prodAmtArray = array();
	$prodAmtArray[] = array('productId'=>'01t60000000lvBN','amount'=>100);
	$prodAmtArray[] = array('productId'=>'01t60000000lvBS','amount'=>200);

$wrkArray = array(
				'contactId'=>'0036000000nVtpT',
				'inputs'=>$prodAmtArray
				);

// Call the web service
$response = $client->myMethod($wrkArray);

// Output results to browser
echo "<p><pre>" . print_r($response, true) . "</pre></p>";
echo "Contact Id is " . $response->result->contactId;

Results

Below displays what those 2 echo statements output.

stdClass Object
(
    [result] => stdClass Object
        (
            [contactId] => 0036000000nVtpTAAS
            [errorMessage] => No errors here.
            [inputs] => Array
                (
                    [0] => stdClass Object
                        (
                            [amount] => 100
                            [productId] => 01t60000000lvBNAAY
                        )
                    [1] => stdClass Object
                        (
                            [amount] => 200
                            [productId] => 01t60000000lvBSAAY
                        )
                )
            [success] => 1
        )
)
Contact Id is 0036000000nVtpTAAS

One last little trick

One annoyance during the development of Apex Web Services is having to continually generate a WSDL for the web service. When testing, I would find that I would continually need to put a new WSDL on the web server. I decided to automate this where I could add a variable to the queryString and have PHP refresh the WSDL on my web server. You need the cURL module for this, but most PHP installs have it.

$ch = curl_init();
	$fp = fopen(_WS_WSDL_, "w");
	curl_setopt($ch, CURLOPT_URL, _WS_ENDPOINT_);
	curl_setopt($ch, CURLOPT_FILE, $fp);
	curl_setopt($ch, CURLOPT_HEADER, 0);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
	curl_setopt($ch, CURLOPT_COOKIE, 'sid='.$sfdc->getSessionId());
	setcookie("sid", $sfdc->getSessionId(), 0, "/", ".salesforce.com", 0);
	curl_setopt($ch, CURLOPT_TIMEOUT, 30);
	curl_exec($ch);
	fclose($fp);
curl_close($ch);

If you have experience with this kind of integration, please comment here on other tips & tricks.

I changed it into a Visualforce page with a custom Apex controller and now it runs super fast and I am able to keep the “Show Custom Sidebar Components on All Pages” option turned on and see it on every page I go to.  There’s a bit of hardcoding in here, but it gets the job done pretty well.  Bye bye s-Control.

Visualforce

The Page is almost all raw HTML.  The only dynamic thing in there are the count values.  Each one retrieves the value from a specific “get” method in the controller.  If you like the queries I use, then the only thing you’ll need to confirm are the URLs that get linked to.  The first 2 go to Views in my Org and the last 2 go to Reports in my Org.  You’ll need to change those URLs.

I named the VF Page “SidebarSummary”.

<apex:page controller="VFController_Sidebar_Summary" sidebar="false" showHeader="false" standardStylesheets="true">
<style type="text/css" media="all">
body{margin: 0; padding: 0; color: #000000; background-color: #E8E8E8;}
#DIV_Container {background-color: #F3F3EC;}
</style>
<div id="DIV_Container">
<table>
<tr><td><em>Unread Leads</em>:  </td><td><a href="/00Q?fcf=00B30000005JhsT" target="_parent"><b>{!UnreadLeads}</b></a></td></tr>
<tr><td><em>Leads - Not Contacted</em>:  </td><td><a href="/00Q?fcf=00B30000005Jhru" target="_parent"><b>{!NotContactedLeads}</b></a></td></tr>
<tr><td><em>Oppty - Next 30 Days</em>:  </td><td><a href="/00O30000001aEHV" target="_parent"><b>{!Next30DayOppty}</b></a></td></tr>
<tr><td><em>Oppty - Past Due</em>:  </td><td><a href="/00O30000001aEHV" target="_parent"><b>{!PastDueOppty}</b></a></td></tr>
</table>
</div>
</apex:page>

Apex

The controller has a method for each query to be run.  Each query is a count() query and returns an Integer.  At the end is a really lame Test method, but it does get 100% of the code covered.  I am certain the code works, so I didn’t do too much with the Test method.  Salesforce just requires the code to be tested.

public class VFController_Sidebar_Summary {

public Integer getUnreadLeads() {
return [
select count() from Lead
where IsConverted = False
AND IsUnreadByOwner = TRUE
];
}

public Integer getNotContactedLeads() {
return [
select count() from Lead
where IsConverted = False
AND Status = 'Open - Not Contacted'
];
}

public Integer getNext30DayOppty() {
return [
select count() from Opportunity
where IsClosed = False
AND (CloseDate = Next_N_DAYS:30 OR CloseDate = TODAY)
];
}

public Integer getPastDueOppty() {
return [
select count() from Opportunity
where IsClosed = False
AND CloseDate < TODAY
];
}

static testMethod void testVFController_Sidebar_Summary() {
Test.setCurrentPageReference(new PageReference('Page.SidebarSummary'));
VFController_Sidebar_Summary controller = new VFController_Sidebar_Summary();
Integer i1 = controller.getUnreadLeads();
Integer i2 = controller.getNotContactedLeads();
Integer i3 = controller.getNext30DayOppty();
Integer i4 = controller.getPastDueOppty();
}

}

Homepage HTML Component

I created a component for the Narrow side and put the following HTML into the editor.  Essentially, you create an IFRAME and embed the VF page into it.  I found a (unsupported) trick on the forums to remove the developer bar from a page.  Just add ?core.apexpages.devmode.url=1 to the URL.  This will turn off development mode when that page is rendered.  This is important for this little iFrame page on the sidebar.  From what I’ve gathered, this hack is not supported and could change at any time.

The code below should work for you.  The only thing you might need to change is the Page URL if you didn’t name your page SidebarSummary and the height of it.

<iframe src="/apex/SidebarSummary?core.apexpages.devmode.url=1" frameborder="0" height="100" width="100%"></iframe>

Let me know what you think.

There were a couple of webinars today about the changes. The customer-focused webinar will be available at http://www.salesforce.com/security soon. The partner-focused one will be available in the Partner Portal.

Below is my understanding of what was said and a high-level overview of the main impacts. Please add clarifications in the comments.

API Logins

• If you connect via a Session ID passed from a web link/tab, none of these restrictions apply as the user is explicitly providing you with login access to his/her active session.
• To login with a username and password, the IP address you are logging in from needs to be white-listed.
• Salesforce will pre-populate the org’s whitelist with IPs used in the past 4 months.
• Each end-user can generate an API token to replace their password for API logins.
• API logins using the API token do not require their IP to be whitelisted.
• API tokens do not expire. Only 1 is active at a time. It can be replaced by the user generating a new one. This automatically invalidates the old one.
• API tokens cannot be used to login at https://www.salesforce.com/login.jsp.
• Going forward, the best practice would be for end users to provide their API token to any app/service they use other than the main Salesforce.com login page.

Logging in at https://www.salesforce.com/login.jsp

• Username and password will still be the way to access Salesforce.com from the main login page
• A new feature will be added requiring you to confirm that your computer is valid to login using that username.
• The login page will check if you’ve logged in from that computer before (by looking for a browser cookie)
• If not, the email address on the user record will be sent an email to confirm that you are, in fact, the one trying to login now.
• You will click a link in that email “activating” your computer for login with that username
• Unless you delete the cookie or clear your broswer’s cache, you should be good to go for a while without repeating these steps.
• There are no new IP restrictions affecting logins at the main login page. The profile-based IP restrictions that have been around for a long time are still the way to go there.

If you are a consultant, you may fall victim of the new security measure when you try to login as your client (maybe they couldn’t afford another temporary username just for you). On the call, I was told that you can request a temporary one via the Partner Portal or ask your customer to forward you the email to confirm your PC is okay.

My thoughts

I think it is great to see Salesforce taking a step to tighten up the API, especially. I like to think that my old API Authentication List post had something to do with it, but who knows.

The biggest impact to me will be using client’s logins to get into the system from my PC, but I’ll just have to workaround that one. Security and convenience are generally a trade off and overall I’d rather use/subscribe to a service that is tightened down with my business data. If anyone can handle the inconveniences of logging in, it’s developers since we are used to doing hacks/workarounds in the first place.

I was recently looking at Rave CRM by Entellium and I was inspired by their UI design. I only saw the demo on their website, but they had a lot of really good UI ideas. One of the things I really liked was a quick summary of data counts on the homepage that were very applicable to the end user.

I wanted to see if I could create something similar in Salesforce. Using an s-Control that is shown via an IFRAME on the sidebar, I was able to do it. The end result is like having a bunch of Metric style dashboard components stacked on top of each other. You can see it in action below. Each line shows a record count and the record count is a hyperlink to a View or Report. It’s small, clean and tells the user vital information with quick links to see more. I like the concept.

How it works

It is all running in an s-Control and uses the AJAX toolkit to talk to Salesforce. The s-Control is in an IFRAME in a homepage component. The s-Control has a function called getCount and you pass getCount the following:

• Object to Query
• WHERE clause for the query
• Label for the returned HTML
• A URL to let a user drilldown on the result

A call to it looks like this:

theHTML += getCount("Lead", "WHERE IsConverted = False AND CreatedDate = TODAY", "Leads - Today", "/00Q?fcf=00B30000001Qizn");

It uses the object and where clause to do a count() query. It then returns an HTML table row with 2 columns. The first has the label you passed it in italics. The second has the record count of the query as a hyperlink to the URL you passed it. If you don’t pass it a URL, then it shows the record count without a hyperlink.

The s-Control is made up of 2 functions: getCount() and main(). getCount is described above. main() calls getCount once for each metric and then wraps the results in some more HTML. A bit of CSS is sprinkled in to output it nicely on the homepage sidebar. That’s it.

Try It

I uploaded it to the AppExchange to let people try it and improve upon it. It is just a proof of concept. I am using it in my org right now, but it needs to be improved if I will let it stick around. For example, it’d be great to have it cache the data and only run the queries once every 30 minutes because running it can slow the load time a bit. Is anyone up for improving it to meet that requirement?

To make this work for you, you should be familiar with s-Controls. It’s not plug and play. Getting it setup expects you have a working knowledge of this stuff. I kind of hacked it together and wanted to get it out there for other to see. It’s very simple code, but I think it serves a very good purpose. I am interested in what you think.

I set it up with some basic queries, but I’d recommend you change them to meet your needs. To change what the queries are, you need to go into the main() function and edit the lines that call the getCount function. You will need a single line of code for each query you want to run.

If you really want it to work nicely, you should create corresponding Views or Reports and link to those by passing the getCount function the URL of the View or Report.

Once you have your queries all set, you need to add the homepage component. I didn’t package one in the AppExchange package because I have been unable to edit a homepage component that only has an IFRAME in it (WYSIWYG editor bug). I’ve had to delete it and recreate it every time. So you get to do that too!

1. Create an HTML Area Homepage Component
2. Choose it to go on the left (narrow) navigation bar
3. Click the Show HTML checkbox on the WYSIWYG editor
4. Copy the HTML below and replace IdOfScontrol with the ID of the s-Control in your AppExchange package. You can change the height of the IFRAME too.

   <IFRAME src="/servlet/servlet.Integration?lid=IdOfScontrol&amp;enc=UTF-8&amp;ic=1" frameBorder=0 width="100%" height="150"></IFRAME>

5. Add the new Homepage Component to your Homepage Layout

Now you should be ready to test it out. Using a tool like Firebug can greatly improve your ability to troubleshoot issues and make enhancements.

Please let me know what you think by posting comments. I am interested in thoughts on the concept, ways to improve it, issues you are having, etc.

• Oracle script
• MySQL script

If you try these, feel free to comment here about how it went. If you actually want to let Mike know about your use of the scripts, you could submit replies on his site or at his forum postings about the functionality (Oracle, MySQL)

Part 1 is a screencast overview of your integration options (ADN login is required to view it). If you are getting started with Salesforce integration or maintaining a curriculum for people in your company, this is a good place to point them to. Part 1 should help you visualize the various options and segment them in your mind, so you can figure out the integration method that works best to address your needs.

Part 2 is called “Next Generation Integration Services”, which will talk about new capabilities in store for the platform. No date is published for it. Just that it’s “coming soon”.

Visit the Enterprise Integration Series on ADN.

This first example focuses on querying an Oracle database and pushing data to Salesforce.com using the upsert method.

If you are interested in the PHP toolkit (which is my preferred toolkit), it’s worth a read.

Check it out.

The concept for this library is simple: Begin with the Salesforce AJAX toolkit, port the data layer to the ActionScript 3.0 programing language found in Adobe Flex, returning native strongly typed ActionScript objects for the Flex programmer to manipulate and render. This allows Flex programmers to build S-controls — components within the Apex interface where custom code can be executed — without dropping into JavaScript.

For more information:

• Visit the Flex Toolkit page on the Apex Wiki. There you will find Getting Started materials, downloads, object/class documentation, etc.
• Check out the screencast to learn about the IDE.
• See the end result in action in an AppExchange Test Drive

FYI – in case you didn’t know already, you can stay up to date on new Wiki pages via RSS.