Promises Redux.

When I first released the Promise library, there was a small bug. Apex wasn’t reseting the DML context between promise steps. To get around this, Promise fired off each promise step through an @future method. This worked around the problem, but it did have an impact on execution time. Salesforce resolved this issue in winter ’17. In repsonse, I spent some time refactoring the library. Today I’m happy to announce Promises 2.0; the AwesomeSauce edition. You can find the code, and installation instructions here:

The good (what changed?)

The library no longer executes promise steps via an @future method. This can have a dramatic, positive, effect on execution times. The first version required promises to accept and return JSON Serializable objects. This new version, no longer requires anything more specific than an Object. You can pass around and return sObjects, primitives, and custom Apex objects. The biggest refactor comes from naming conventions. I established two classes in the first version: PromiseBase and Promise. I’ve refactored away the need for PromiseBase. Now the library, apart from examples and tests, is a single class. Additionally, I’d received some feedback suggesting ‘promiseStep’ needed a better name. After some discussion with other developers, I settled on ‘Deferred’. Classes implementing the Deferred interface execute code via Queueable Apex. Because of this, the system defers their execution until it has resources.

The bad (Sorry, I made a few breaking changes)

The refactoring I mentioned above meant that the API has changed. V1 and V2 are not compatible with each other. Yet, the gains provided by the changes justify the need to refactor existing promise code. To migrate to version 2, you’ll need to do two things:

  1. Change the interface your promise classes use. From Promise.PromiseStep to Promise.deferred.
  2. Remove references to SerializableData. Either by passing specific object types, or by accepting and returning generic Objects

Below is a full example class that uses promises v2.0 – AwesomeSauce Edition

* Promise v2.0 – Kevin Poorman
* Thanks to Chuck Jonas!
* This class exists to demonstrate the usage of the Promise library.
Public Class Demo_PromiseUse {
// This execute method optionally accepts a string param that is used to pass data into
// the intial promise step.
Public Void execute(String param) {
new Promise(new Demo_PromiseStep())
.then(new Demo_PromiseStep_Two())
.error(new Demo_PromiseError())
.done(new Demo_PromiseDone())
} else {
new Promise(new Demo_PromiseStep())
.then(new Demo_PromiseStep_Two())
.error(new Demo_PromiseError())
.done(new Demo_PromiseDone())
// This method intetntionally creates a divide by zero error so we can test handling an exception
// note that there is no error handler defined here. The .Error() method is optional. Without it, the error
// is just logged.
// Note! in dev and sandbox orgs the Queuable Apex queue depth is 1! as such, you're only really testing the first
// promise step. The associated test for this method, needs to have the error occur in step 2, so thats the first
// step we list.
Public Void executeWithException() {
new Promise(new Demo_PromiseStep_Two(0))
.done(new Demo_PromiseDone())
// Like the previous method, this execution method is setup to cause a division by zero error in our
// Demo_PromiseStep_Two's resolve method. The constructor for that class accepts a divisor, in this
// case 0. However, this method includes an error handler. The test for this method, ensures that
// the exception handler is invoked.
Public Void executeWithExceptionWithHandler() {
new Promise(new Demo_PromiseStep_Two(0))
.error(new Demo_PromiseError())
.done(new Demo_PromiseDone())
// ____ __ _ ____ _
// | _ \ ___ / _| ___ _ __ _ __ ___ __| |/ ___| | __ _ ___ ___ ___ ___
// | | | |/ _ \ |_ / _ \ '__| '__/ _ \/ _` | | | |/ _` / __/ __|/ _ \ __|
// | |_| | __/ _| __/ | | | | __/ (_| | |___| | (_| \__ \__ \ __\__ \
// |____/ \___|_| \___|_| |_| \___|\__,_|\____|_|\__,_|___/___/\___|___/
Public Class Demo_PromiseStep implements Promise.Deferred {
Private Integer checkInteger; // helpful for testing. not generally needed.
// this is the required method for a PromiseStep class.
Public Object resolve(Object incomingObject) {
// Do some aysnchronous work, in this case, we'll pretend it's in
// our helper method:
checkInteger = exampleHelperMethod();
return checkInteger;
// helper methods
// I put this in a helper method not out of neccessity but because it illustrates that
// this is a normal class, and you can have multiple methods and architect this class
// in a way that code is easily testable, and isolated.
private Integer exampleHelperMethod() {
return Crypto.getRandomInteger();
Public Class Demo_PromiseStep_Two implements Promise.Deferred {
Private Integer dataPassedIn;
Private Integer slowAsyncWork;
Private Integer divisor;
Public Demo_PromiseStep_Two() {
// this constructor exists to facilitate testing. By accepting an integer
// i can later cause a division by zero error that is used to test error
// handling in the framework.
Public Demo_PromiseStep_Two(Integer divisor) {
this.divisor = divisor;
// This is the required interface method for a PromiseStep
Public Object resolve(Object incomingObject) {
// Do some aysnchronous work, in this case, we'll pretend it's in our helper method:
if (incomingObject != null) {
this.dataPassedIn = (Integer) incomingObject;
//intentionally setup to cause a divide by 0 error
if (this.divisor != null) {
Integer thrown = 1 / this.divisor;
slowAsyncWork = exampleHelperMethod();
return slowAsyncWork;
// helper methods
private Integer exampleHelperMethod() {
return Crypto.getRandomInteger();
// _ _ _ _ ____ _
// | | | | __ _ _ __ __| | | ___ _ __ / ___| | __ _ ___ ___ ___ ___
// | |_| |/ _` | '_ \ / _` | |/ _ \ '__| | | |/ _` / __/ __|/ _ \ __|
// | _ | (_| | | | | (_| | | __/ | | |___| | (_| \__ \__ \ __\__ \
// |_| |_|\__,_|_| |_|\__,_|_|\___|_| \____|_|\__,_|___/___/\___|___/
public class Demo_PromiseDone implements Promise.Done {
// This is used to demonstrate the use of a class instance var populated by a constructor
// Because this is an installable package i'm using an account.
Private Account internalAccount;
Private string completed;
// Constructors
public Demo_PromiseDone() {
} // No op constructor
public Demo_PromiseDone(Account incomingAccount) {
this.internalAccount = incomingAccount;
// This is the main method that the Promise.done interface requires.
// you could use this to persist a record, or to write a log.
Public Void done(Object incomingObject) {
// we could do nothing here – NOOP but we could also do something with the incomingObject
if (incomingObject != null) {
// do something here. Maybe save a record?
// this is a helper assignment to do testing of the library
completed = 'completed';
Public Class Demo_PromiseError implements Promise.Error {
private String errorMessage;
public Demo_PromiseError() {
// This is the main interface method that you must implement
// note that it does have a return type, and in this case I'm using the
// promise.serializableData type. This will pass the 'error occured' string to the done handler
public Object error(Exception e) {
//for now, just dump it to the logs
system.debug('Error Handler received the following exception ' + e.getmessage() + '\n\n' + e.getStackTraceString());
//Make the error available for testing.
this.errorMessage = e.getMessage();
//Alternatively, you could do any number of things with this exception like:
// 1. retry the promise chain. For instance, if an external service returns a temp error, retry
// 1a. Use the flow control object to cap the retry's
// 2. log the error to a UI friendly reporting object or audit log
// 3. Email the error report, and related objects to the affected users
// 4. post something to chatter.
return e;

view raw
hosted with ❤ by GitHub

Straight up now tell me, if you’re using this lib!

Since I released the library I’ve talked to many developers who are using it. They’ve discovered a few new use cases that I’d not thought of. For instance, one developer is using Promises in Sandbox startup scripts. This helps his company ensure the order of sandbox data creation. They have many address validations, callouts and integrations during the creation of accounts. Creating those accounts, and processing the integrations must finish first. Until then, creating dependent objects will fail. Another developer is using promises to automate a SAAS company’s billing. Harnessing promises, she was able to write a single chain of steps. Promises enables them to retry callout steps when an integration stops responding. Steps exist to create a case when the payment processor declines a card. When finished, the process sends the customer an receipt. Super cool. If you’re using Promise, or have an interesting use case for promises, drop me a line.


Installation instructions here:

A framework for using the promise pattern in Apex

Writing instructors tell you to answer the five W’s: who, what, where, when and why. Mine even instructed me to answer them in that particular order. But today we’re talking about asynchronous code execution and promises. That means it might be easier to write this post a bit out-of-order:


I’ve always understood the hardest thing in computer science to be naming things. Followed immediately by cache invalidation and asynchronous execution, of course. Writing, debugging and maintaining asynchronous (and/or multi-threaded) code is hard.

The joke, in fact, has always been ‘hard, asynchronous is, debug to.’

One way to think about this problem is ask ‘when should I execute this code?‘ The answer, of course, is simple: When I have all the data I need to execute it. Which leads itself to another question. ‘how do I know when I have all the data without stopping and waiting every time I have a long-running method?‘ There are at least two answers to that question. If you’ve ever written Javascript, you’ve likely hit upon the first answer: callbacks. Callbacks are functions passed as parameters into a long-running asynchronous method. The callback then executes at the very end of your method. Callbacks solve the ‘when’ problem by defining the ‘what’ before execution starts. Another solution to this is Promises.


Promises get their name because they represent the promise of an eventual value. A Promise is a state machine with three states: Pending, Resolved and Error. (These states may have different names depending on the implementation.)

An image describing the state machine of promises


A promise starts its life in Pending status. As the code completes, it either succeeds and becomes Resolved, or fails and ends up in Error status. Promises solve the ‘when’ problem by introducing a method, .then(). This attaches the passed concluding code to the initial method. Promises do this by adding to, and executing methods from a stack. Every invocation of .then() adds to the stack. Executing the promise causes the stack’s methods to run in order.

The state machine, combined with a stack make Promises easy to describe (in English). (I, the developer) promise the system that this method will return some data. When it does, ‘then’ do this other work I’ve described.

One of the stellar features of Promises is their ability to return not only data, but a new Promise. This allows you to chain promises together into processes. For example, a developer might need to pull some data from a third party API. However, before she can access the data, she has to authenticate. In practice means making a callout to authenticate and retrieve an oAuth token. Token in hand, a second call retrieves the data. With Promises this can described as a single process:

Login() // this method must return a promise!
// the promise login() returns the oAuth token and dependency injects it into the resolve method of our fetchData() class
new fetchData()

view raw
hosted with ❤ by GitHub

Why Promises? (another? promise library for Apex?)

All this talk about promises has been empty theory until recently. With the release of Winter ’15, Salesforce gave us QueueableApex. QueueablexApex is the interface that enables the implementation of Promises in Apex. Last year at Dreamforce I gave a talk on the Promise pattern and how to implement it in Apex. Unfortunately, none of the example code had that beautifully simple syntax using .then(). After my talk, Chuck Jonas, (Developer extraordinaire) wrote a promises implementation called Apex-Q. Chuck’s library is amazing, but I wanted something a bit simpler. Apex-Q includes two types of Promises. One that facilitates HTTP Callouts, and one that doesn’t. The trade-off needed to make all Promises HTTP callout safe, however, is pretty minimal. Namely, the data passed between promises must be JSON serializable. Today I’m happy to release Promise an alternative implementation for Promises in Apex.

How (do I use it)?

With the Promise framework, you’ll create classes that represent each ‘step’ of your promise chain. These classes simply implement the Promise.promiseStep interface and look like this:

Public Class Demo_PromiseStep implements Promise.PromiseStep{
Public Promise.SerializableData resolve(object incomingObject) {…}

view raw
hosted with ❤ by GitHub

The promiseStep interface requires only the resolve method. The resolve method must return a SerializableData object. Each resolve method accepts the output of the previous step. The output of the previous step is dependency injected into the next resolve method.

Once you’ve implemented each of your promiseSteps, you can execute a promise chain like this:

new Promise(new Demo_PromiseStep())
.then(new Demo_PromiseStep_Two())
// Add as many .then(new someClass()) calls as you need
.error(new Demo_PromiseError())
.done(new Demo_PromiseDone())

view raw
hosted with ❤ by GitHub

Note: while this example has two demo steps, if your process had, say 5 steps, you’d simply add 3 more .then(new someClass()) calls.

Under the covers, the .then() method populates a List of promises. The execute() framework method pops the first promise step off the list and executes it. If there are other steps on the list, it enqueues the next step by calling an @future annotated method. If the execution of a step throws an error, the framework invokes the error handler. The framework’s .error() method allows you to specify the error handling class. Finally, the .done() handler is always run! The done handler, is a great place for notifications and any other wrap-up work you need to do.


You can find Promise here: You can install it in your sandbox or production orgs using the deploy button at the bottom of the readme. Promise includes a test class. Additionally, Promise includes some example classes demonstrating use of the framework. The tests provide nearly 100% coverage. However, they rely on the included example classes. They are too functional for my taste. For now, please note that deleting the example classes from your org will cause the tests to fail.


If you’ve ever written code to make several sequential HTTP callouts… If you’ve wondered how to ensure one batch process completes before the next starts… Promise can help. Promise is for Apex developers who develop, debug and maintain asynchronous code. Promise is not only for doing integration work with external services. In fact, anytime you need to attach code execution to the completion of other code, Promise can help!

Or how Trailhead taught my Grandma about Salesforce:

salesforce_advantage_apps_newRecently I found myself in the position of trying to explain to my Grandma what Salesforce is. As it turns out, this is a really easy thing to answer, if you’re talking to someone who’s used computers all their life. For my grandma, however, there were just too many hurdles to overcome. To her, CRM was her job, not a tool she used for her job. As the front office manager for a beauty school in small town Indiana, she called, wrote and spoke with hundreds of clients a week. The idea of needing a computer to remember and record that information… well, she’d rather use her address book and her sharp-as-a-tack mind. It’s true, as they say, that they don’t make them like they used to.

She came around to the idea of CRM eventually. Then I had to explain why Salesforce, as a CRM, is better than her old school, (and flat out old) address/notebook. Way to put me on the spot grandma! Explaining metadata is actually a tall order. Especially since I smarted off that Metadata was just data about data! To which my grandmother said “isn’t data about data just data?”

Uh, yes. But… Trailhead to the rescue (Again)

Thankfully, Trailhead has come to my rescue. There’s a new trail that breaks down exactly what Salesforce is, what makes it special, and why it’s better than ye-olde-notebook. Called The Salesforce Advantage the trail walks you through not only what Salesforce is, but the technology behind it — including metadata and the cloud.

This isn’t a technological deep dive into the how of Salesforce, but it does discuss the what of Salesforce at a nice introductory pace. It’s perfect for my Grandma. More importantly, it’s perfect for managers and executives, new admins and developers to learn the strategic advantages of Salesforce. If you’ve never done Trailhead, or if you’re new to Salesforce — hell, if your Grandma asks what you do for a living … climb this trail! Especially if you’re trying to explain to Grandma!

Almost 20 years ago my father answered the phone as we ate a late family dinner. He was mightily confused because the man on the other end of the call was asking him questions he had no idea how t answer. After a few moments of confusion, my father told the man, he was pretty sure he wanted his son, Kevin, not him.

On the other end waited Ian Murdock. He’d taken the time to call me up to do my Debian maintainer identity interview. It was, and is, a big deal, from a security standpoint, to verify the identity of new Debian maintainers. But the task is tedious, calling up new maintainers and talking to them for half an hour. Imagine my surprise, when, the man doing my interview was *the* Ian from deb*ian*. One of the co-founders of the entire project had taken the time to call me. I was Impressed.


Years later, I got to meet Ian in person at an ExactTarget conference, and I thanked him for calling a nerdy high school kid to verify his identity. He not only confirmed my identity for security purposes, but he affirmed that I mattered, and could help. At the time, I don’t think he remembered the call, and I don’t think I was sufficiently able to convey what his call meant to me.

Last Monday, Ian Murdock was found dead in his home. The details are few, the speculation rampant. Police may or may not be involved. The proximate cause might have been Suicide. Was his Twitter account hacked? Regardless of the details, I’m reminded that all too often our culture judges people by their actions in the worst moments of their life. Those who have killed are forever murderers branded by their actions at the worst moments of their life. We don’t seem to have a cultural construct for good people who made mistakes. Not where suicide or the police are concerned. I’ve already started to see Ian eulogized not for his contributions to the world, but as a “crazy” and someone who gave up. I don’t know how Ian died, it’s likely you don’t either. It doesn’t matter; Ian was more, is more, than the unknown actions at the end of his life. He was also the kind of man who’d not only call and verify my identity, but reaffirm an insecure high school nerd’s ability to meaningfully contribute to the world at large.

To Ian, Thank you for all that you were and did.

Login History without Manage Users permissions

Recently someone asked me how to expose the login history without giving the individual users the manage users permission. The goal was to allow the internal support team to view the login history of portal users. Off the top of my head, I thought this would be the perfect use case for illustrating the power of the ‘without sharing’ Apex keywords. So after a few minutes we had built an Apex controller and Visualforce page we thought would work. Initial testing, as System Administrator users was promising. Loading the Visualforce page showed us the last 25 login history records for the User we specified. Unfortunately, loading that same page as a support user yielded 25 blank lines!

All was not lost, however, as we refactored the controller more in line with best practices. Moving our login history data to a wrapper class allowed the data to be visible to users who had permission to access the controller and page! Here’s the final product:

2015-09-30 at 10.06 PM



And here’s the code:

public without sharing class UserLoginHistory{
public class loginHistoryWrapper {
public DateTime LoginTime {get;set;}
public String Status {get;set;}
public String LoginURL {get;set;}
public String LoginType {get;set;}
public String Application {get;set;}
public String Browser {get;set;}
public ID UserId {get;set;}
public loginHistoryWrapper(DateTime lt, String statuss, String LR, String ltype, String app, String brow, ID uid){
LoginTime = lt;
Status = statuss;
LoginURL = LR;
LoginType = ltype;
Application = app;
Browser = brow;
UserId = uid;
private Map<String, String> UrlParameterMap;
private User pU {get; set;}
public User u {
if(pU == null){
pU = [SELECT name FROM User WHERE ID = :UrlParameterMap.get('userId')];
return pU;
public List<LoginHistoryWrapper> Records {get; set;}
public UserLoginHistory(){
UrlParameterMap = ApexPages.currentPage().getParameters();
List<LoginHistory> lRecords = [
SELECT LoginTime, Status, LoginURL, LoginType, Application, Browser, UserId
FROM LoginHistory
WHERE UserId= :UrlParameterMap.get('userId')
Records = new List<LoginHistoryWrapper>();
For(LoginHistory lh : lRecords){
Records.add(new LoginHistoryWrapper(lh.loginTime, lh.status, lh.loginURL, lh.LoginType, lh.Application, lh.Browser, lh.UserId));

view raw
hosted with ❤ by GitHub

The secret sauce here is our wrapper object. Converting the loginHistory objects to our wrapper object allows the data to be seen by users without the Manage Users Permission.

<apex:page controller="UserLoginHistory">
<apex:pageBlock title="Login History for {!u.Name}">
<apex:pageBlockTable value="{!Records}" var="Record">
<apex:column >
<apex:facet name="header">User's Name</apex:facet>
<apex:outputText value=" {!}"/>
<apex:column >
<apex:facet name="header">Login Time</apex:facet>
<apex:outputText value=" {!Record.LoginTime}"/>
<apex:column >
<apex:facet name="header">Status</apex:facet>
<apex:outputText value="{!Record.Status}"/>
<apex:column >
<apex:facet name="header">Login Type</apex:facet>
<apex:outputText value="{!Record.LoginType}"/>
<apex:column >
<apex:facet name="header">Client Type</apex:facet>
<apex:outputText value="{!Record.Application}"/>
<apex:column >
<apex:facet name="header">Browser</apex:facet>
<apex:outputText value="{!Record.Browser}"/>
<apex:column >
<apex:facet name="header">Login URL</apex:facet>
<apex:outputText value="{!Record.LoginURL}"/>

view raw
hosted with ❤ by GitHub

Viola! a safe way to expose login history with internal users without giving them ManageUsers permission!


Trailhead is by far and away my favorite learning tool for Salesforce development. The combination of guided tutorials with hands-on, in-org development is unbeatable. On top of this, the guided tutorials have built-in direct feedback to help. Until recently, the state of the art for teaching programming languages was books. The best we had for checking our work was compiler and interpreter errors. I’ve waxed philosophical about Trailhead before, but it’s unparalleled as a teaching tool. Recently a Lightning Dev week participant asked me what my favorite Trailhead module was? After some consideration, I think my favorite module is…

Apex Testing.

trailhead_apexTestingI spend a lot of time on the developer forums and Salesforce Stack Exchange. I think it’s safe to say that the majority of questions are about testing. There’s the classic “will you write my tests for me.” The philosophical “why must I write unit tests?” But my favorite is still, how can I increase my test coverage for this code? Trailhead’s Apex Testing module, while it doesn’t cover everything, is a great start.

The module’s components.

The Apex Testing module has three components that build on each other. First, it starts with an overview of unit testing basics like assertions. This component tops off with a practical test — write a unit test for a given class. To pass the challenge, you have to meet 100% test coverage. The challenge of 100% test coverage reinforces several core ideas. Most importantly it enforces the practice of testing all the logical paths in your code.

Unit Testing Apex Triggers.

Because Triggers execute in response to DML events, unit tests for triggers have to contain assertions and DML statements. While orgs have to maintain 75% aggregate average code coverage, all triggers have to have some coverage. This has the practical effect of a many more testing questions related to Triggers. Learning to test triggers in Trailhead serves not just to train developers but to advance the community. It does this by decreasing the number of routine “how do I write a test for this trigger?” questions on the forums.

Creating Test Data.

Of all the components in the Trailhead Apex Testing module I find the last one most valuable. In this last component readers learn why it’s important to create your own test data. This is more than just a practical matter and the key to why this is a hidden gem. Testing your code is arguably more important than actually writing it. While a majority of us wouldn’t neglect objects or other code dependencies; Data dependencies are often overlooked. Learning to write proper tests means learning to write code that fulfills all dependencies. By fulfilling all the dependencies and writing proper tests, developers gain the confidence that their test is valid not only today, but next week and next release!

A good three base hit.

Trailhead’s Apex Testing covers three of the most important aspects of unit Testing. While Trailhead takes the time to teach the basics of unit testing I believe it misses two key facets. First, and most importantly, it doesn’t address the importance testing different users and scenarios. Specifically, I want Trailhead to teach developers to write tests that:

  1. Test the “expected” behavior — so-called “positive” test cases. These tests pass in expected input and test for expected output. One positive test case for each logical branch.
  2. Test expected Exceptions — so-called “Negative” test cases. These tests pass in invalid or otherwise faulty data into the unit of code. Negative tests assert that the code threw an exception. Bonus points for tests that assert a specific type of exception and it’s message.
  3. Test the code with various user roles and permissions. Can the code handle execution with a non-sysadmin?

Each of these test types safeguards against common exception cases. By testing more of these common cases, we gain more confidence in the robustness of our code. Perhaps Trailhead will expand to teach these three test types. (Dear Trailhead team, if you’d like help with that, tweet me!)

Secondly, I wish Trailhead also discussed HTTP callout tests. More and more of our work as Salesforce developers involves integrations. These integrations often take the form of api integrations through HTTP callouts. Testing callouts requires knowledge of the HttpCalloutMock interface and using the Test.startTest() and Test.stopTest() methods.

Regardless of these two sticky bits, I think this module is the best one out there. Testing is one of those key skills that every Salesforce developer has to master. Trailhead provides not only knowledge transfer but skill practice and evaluation — a combination that can’t be beat — especially for testing.

Salesforce Communities sometimes have to be Debugged.

Recently I had the opportunity to do some communities work. On the whole, I love the communities product. From an end-user perspective it can’t be beat. As a developer, but, I’ve hit a few snags debugging Visualforce pages in communities. During normal Visualforce development, you can rely on the platform to surface errors. Usually this takes the form of a nice ugly error message. Now ugly error messages are the epitome of terrible user experiences. So it’s understandable that Salesforce would prevent them from appearing to users.

Debugging Communities with uglyErrorMessage

Behold, an ugly error message in it’s uninformative native habitat!

Unfortunately, Salesforce replaces Visualforce errors with a different, but far less informative error message. This error displays only for Visualforce errors – not Apex errors. In fact, two conditions must be met for this kind of error. First, a page’s controller or controller extension(s) must instantiate without error. Secondly, there must be some kind of rendering error. What do I mean by “rendering error”? Well, in my case it was a view state size error. When these types of errors happen, Salesforce hides the error behind this lovely message.

When I first started experiencing this bug, I started with the usual debugging techniques. I tried a few different users. I tried adding users to debug logs. I made sure that logs were appearing in the dev console and read every line. I saw my controller firing up and completing without a single error. Yet the error page plagued me. After some discussion with the IRC #salesforce community I discovered a method on the PageReference class called getContent. getContent() returns the rendered content of the page, including error messages. Most importantly, getContent() returns errors rendered at the Visualforce level. This allows us to capture the error before Salesforce neatly hides our error. It’s possible to construct a page that attempts to render the content of any other Visualforce page in a try/catch block. When the page catches an error, it’s displayed.

Debugging Communities with a Visualforce wrapper

To help others with debugging communities based Visualforce errors, I’ve developed a reusable Visualforce page called CommunityDebugger, and its corresponding controller CommunityDebbugerCtrl. Here’s the controller code:

public with sharing class CommunityDebuggerCtrl {
public String failingPageResponse { get; set; }
String toLoad {get; private set;}
Map<String, String> params {get; private set;}
String queryString = '?';
public CommunityDebuggerCtrl() {
params = ApexPages.currentPage().getParameters();
toLoad = (String) params.get('page');
system.debug('params' + params);
boolean first = true;
for (String key : params.keyset()) {
queryString = queryString + key + '=' + params.get(key);
first = false;
queryString = queryString + '&' + key + '=' + params.get(key);
public void fetchFailingPage() {
try {
system.debug('Loading this url: ' + toLoad + queryString);
PageReference fail = new PageReference('/' + toLoad + queryString);
failingPageResponse = fail.getContent().toString();
} catch (Exception e) {
failingPageResponse = e.getTypeName() + ' : ' + e.getMessage() + ' : ' + e.getStackTraceString();

And the Visualforce page:

<apex:page controller="CommunityDebuggerCtrl" action="{!fetchFailingPage}" showHeader="false" sidebar="false" >
<apex:outputText id="failingPageResponse" escape="false" value="{!failingPageResponse}" />

To use this page to debug a community page:

  1. Deploy the controller and page to your sandbox or developer org. You shouldn’t deploy this to production.

  2. Visit your silently failing Community url, say

  3. Prepend “CommunityDebugger?page=” before the your failing page. Like this:

  4. When the page loads, your error will be rendered for you to see, like this:

System.VisualforceException : Id value is not valid for the User standard controller : Class.CommunityDebuggerCtrl.fetchFailingPage: line 23, column 1

And that, my fellow developers, is an error message you can act on. For the record, the bug that started this all? My view state was too big. Transient FTW.

I’m a PC. I’m a Mac. I’m Linux

Back in the day there were really on two or three holy wars that coders inevitably got dragged into. First there is the war of the editors: Vi(m) V. Emacs. (Sublime FTW.) Then there’s Windows V. Mac V. Linux V. *BSD. Finally, it seems that everyone has their own post on why their favorite programming language is better than X.

After my last post, I received a number of responses on twitter and here via comments about naming things like classes, objects and methods. After some conversation with other developers, I’ve discovered a new (cold) holy war among developers — Naming conventions.

A Rose Method by any other name…

There are a few well-known naming conventions for variables – Hungarian variable notation comes to mind. There are several frameworks and languages that have specific conventions as well. Rails (well, more specifically Active Record) has class and model conventions describe how you name objects and their controllers. In both cases, the conventions are there to help developers understand the meaning and purpose behind what their referring too. Hungarian notation prefixes a logical type identifier to the variable name. Rails’ conventions illustrate whether you’re dealing with an object, a database table or a model. In Salesforce, however, it seems we’re much more loosey-goosey with our naming schemes. I polled a number of developers I respect about how they named classes and method and by far, the most thought out answer I received was:

Carefully. ~Akrikos

To be honest, at first I thought his answer was a bit flippant, but he followed up by saying: “Every time I’ve named something poorly I’ve regretted it. Especially in the Salesforce world where there’s such a high cost to changing the name of something.” He’s right, of course, that there’s a high price to pay for renaming a class in Salesforce. The platform demands integrity and renaming something means touching everywhere it’s used. So then, what’s in a name?

What’s in a name?

It stands to reason then, that regardless of what conventions you adopt, you should strive to enforce them 100% consistently.

Naming a method or a class is all about assigning meaning. Conveying meaning in a limited number of characters is all about conventions. Conventions provide consistency that enable at-a-glance understanding. It stands to reason then, that regardless of what conventions you adopt, you should strive to enforce them 100% consistently. Here are some conventions — in no particular order, that I think you should adopt:

  1. Filenames should have standardized endings. This helps you quickly show the purpose of the file, and its class
    1. Test classes end in Tests.
    2. Custom Visualforce Controllers end in Ctrl
    3. Custom Visualforce Controller Extensions end in CtrlExt
  2. Bias towards longer descriptive names and not shorter ones: ThisMethodDescribesWhatItDoes() v. magic()
  3. Put reusable utility code in a utils or lib class. i.e. “CommonContactUtilities”
  4. Group related code together with an “internal namespace”. For instance, if you’ve developed a set of Visualforce pages and Extensions for feature XYZ internally namespace them like:
    1. XYZ_CustomAccountDemoCtrlExt
    2. XYZ_VisualForcePageOfAwesome
    3. XYZ_CustomAccountDemoCtrlExt_Tests
  5. Async classes should include in their name the class they’re scheduling or batching

Homage to Sandi Metz

Sandi Metz, Ruby Hero and Author of Practical Object Oriented Design in Ruby

A year or so ago, Ruby Hero and author of Practical Object-Oriented Design in Ruby Sandi Metz gave us her four rules of Ruby Development. As stated, her four rules are:

  1. Classes can be no longer than one hundred lines of code.
  2. Methods can be no longer than five lines of code.
  3. Pass no more than four parameters into a method. Hash options are parameters.
  4. Controllers can instantiate only one object. Therefore, views can only know about one instance variable and views should only send messages to that object (@object.collaborator.value is not allowed).

While her rules are rather specific to Ruby development, I believe the ideas behind them are fairly universal and useful. With that in mind, here are a set of rules for Apex development, along with the rationalization behind it.

My highly opinionated rules for Apex SimplicityastroSays2

  1. Classes can be no longer than 300 lines of code. — I took three classes from production Apex projects and ported the code to idiomatic Ruby. Each of my Apex classes used aproximately three times the number of lines that the Ruby code took, hence 300 lines. Putting a cap on the number of lines has a number of benefits, but perhaps the biggest is found by enforcing a clarity of purpose on the class. Recently, I had the opportunity to work with a 2k line class “Coupon”. It handled five types of discounts. Breaking those five discounts into five classes helps convey what class had responsibility for what.
  2. 20 lines per method — This is easily the most contentious rule. The primary benefit of following this rule is that your code will necessarily be simpler. Nested if statements, and long blocks of code for edge cases are now tucked away in other, more tightly focused — and more easily tested — methods. Like Thoughtbot’s implementation of Metz’s rules, I think this could use some explaination though, as not everything makes sense as a ‘line’. Conditional logic keywords like if/else each count as a line. The line constraint will also likely reduce your use of else if() constructs keeping your code simpler as well! So why 20 lines? Well Ruby has an implicit return structure, whereas Apex requires explicit return statements adding at least one extra line per method. Couple that with a generally more verbose language and I felt like 20 was the sweet spot. It’s a fairly arbitrary choice, I admit but in some testing I’ve found that I can usually get my methods into 20 lines (not counting comments. You are commenting right?)
  3. Only four method arguments per method — First, let me state an exception to this rule. Factory methods for producing test data are immediately exempt from this rule. For instance, a factory method for returning an Order may require passing in: a User, an Account, a Contact, an Opportunity as well as… well you get the idea. Unlike test methods, most ‘live’ methods accept parameters for one of two reasons: direct manipulation of data or conditional logic. Again, simplicity is the real reason and winner here. Limiting each method to no more than four incoming parameters forces you to have different methods for different conditional branches making your methods are short, concise and tightly focused.
  4. Visualforce Controllers can only talk to a single instance variable. I admit, I have a hard time following this one. The idea here, is to expose the entirety of your data through a single wrapper object. This forces architectural changes on down the line. Your controller or controller extension becomes focused not on gathering data, but preparing it for the view. This has a number of benefits, but code simplicity and testability are the best. Note, this doesn’t include controller methods, just the data being exposed on the page.

If you’re sensing an underlying theme to these, it’s simplicity – keeping the code as simple as possible. These rules help enforce simplicity. Of course sooner or later we’ll hit a class with 350 lines and no good refactoring path. And thats ok too, Break the rules when you have to, not just because you can.