Saturday, 13 January 2018

Building My Own Learning System - Part 1

Building My Own Learning System

Learn

Introduction

Before I get started on this post, I want to make one thing clear. This is not Trailhead. It’s not Bob Buzzard’s Trailhead. It’s not a clone or wannabe of Trailhead. While it would be fun to build a clone of Trailhead, all it would be is an intellectual exercise to see how close I could get. So that’s not what I did. I didn’t build my own Trailhead. Are we clear on that? Nor is it MyTrailhead, although it could be used in that way. But again, I’m not looking to clone an existing solution, even if it is still in pilot and likely to stay there for a couple of releases. I’m coming at this from a different angle, as will hopefully become clear from this and subsequent blog posts. Put the word Trailhead out of your mind.

All that said, I was always going to build my own training system. Pretty much every post I’ve written about Trailhead had a list of things I’d like to see, and I can only suppress the urge to write code in this space for so long. This might mean that I moderate my demands, realising how difficult things really are when you have to implement them rather than just think about them in abstract form.

The Problem

Trailhead solves the problem of teaching people about Salesforce at scale, with content that comes from the source and is updated with each release. MyTrailhead is about training/onboarding people into your organisation. The problem I was looking to solve was somewhat different, although closer to MyTrailhead. I wanted a way to onboard people from inside and outside my organisation onto a specific application or technology, but without sending everyone through the same process.

For example, regular readers of this blog or my medium posts will know that I run product development at BrightGen, and that we have a mature Full Force solution in BrightMedia. We also have a bunch of collateral and training material around BrightMedia that I’d like to surface to various groups of people:

  • Internal BrightGen sales team
  • Internal BrightGen developers
  • External customer users

I don’t particularly want a single training system, as this would mean giving external users access to internal systems. It’s also likely that I’ll have a bunch of training information that isn’t BrightMedia specific, and I don’t really want to colocate this with everything else.

Essentially what I’m looking for is a training client that can connect to multiple endpoints, each endpoint containing content specific to a product/application/team. That, and a way to limit who can access the content, allows me to colocate the content with the application, potentially in the packaging org that contains the application.

The First Stirrings of the Solution

Data Model

As the client won’t be accessing data from the same Salesforce org, or potentially any Salesforce org, my front end is backed by a custom apex class data model rather than sObjects:

Screen Shot 2018 01 13 at 18 12 00

I’ve deliberately chosen names that are different to Trailhead, because as we all know this isn’t Trailhead. I was very tempted to use insignia rather than badge, as I think that gives it a somewhat British feel, but in the end I decided that would confuse people. Each path has topics associated with it so that I can see how strong a candidate is in a particular field. The path and associated steps are essentially the learning template, while the candidate path/step tracks the progress of a candidate through the path. A path has a badge associated with it and once a candidate completes all steps in the path they are awarded the badge. The same(isn) data model as myriad training systems around the globe.

The records that back this data model live in the content endpoint. Thus the candidate doesn’t have a badge count per se, instead they have a badge count per functional area. In the BrightGen scenario they will have a badge count for BrightMedia, and a separate badge count for other product areas. The can also have multiple paths in progress striped across content endpoints.

User Interface

I created the front end to work against these custom classes as a single page application. As the user selected paths and steps the page would re-render itself to show the appropriate detail. I’m still tweaking this so I’ll cover the details in the next post in the series.

Show me the Code

I don’t plan to share any code in these posts until the series is complete, at which point I’ll open source the whole thing on github, mainly because it isn’t ready yet. I’m pretty sure I’ve got the concepts straight in my head, but the detail keeps changing as I think of different ways of doing things.

 

Sunday, 24 December 2017

SFDX and the Metadata API Part 3 - Destructive Changes

SFDX and the Metadata API Part 3 - Destructive Changes

Chuck

Introduction

In Part 1 of this series, I covered how you can use the SFDX command line tool to deploy metadata to a regular (non-scratch) Salesforce org, including checking the status and receiving the results of the deployment in JSON format. In Part 2, how to combine the deploy and check into a node script that shows the progress of the deployment.

Creating metadata is only part of the story when implementing Salesforce or building an application on the platform. Unless you have supernatural prescience, it’s likely you’ll need to remove a component or two as time goes by. While items can be manually deleted, that’s not an approach that scales and you are also likely to get through a lot of developers when they realise their job consists of replicating the same manual change across a bunch of instances!

It’s just another deployment

Destroying components in Salesforce is accomplished in the same way as creating them - via a metadata deployment, but with a couple of key differences.

Empty Package Manifest

The package.xml file for destructive changes is simply an empty variant that only contains the version of the API being targeted:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>41.0</version>
</Package>

Destructive Changes Manifest

The destructiveChanges.xml file identifies the components to be destroyed - it’s the same format as any other package.xml file, but doesn’t support wildcards so you need to know the name of everything you want to deep six. Continuing the theme in this series of using my Take a Moment blog post as the source of examples, here’s the destructive changes manifest to remove the component:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>TakeAMoment</members>
        <name>AuraDefinitionBundle</name>
    </types>
    <version>40.0</version>
</Package>

Destroy Mode Engaged

For the purposes of this post I’ve created a directory named destructive and placed the two manifest files in there. I can then execute the following command to remove the app from my dev org.

> sfdx force:mdapi:deploy -d destructive -u keirbowden@googlemail.com -w -1

Note that I’ve specified the -w switch with a value of -1, which means the command will poll the Salesforce server until it completes. As this is a deployment it can also be handled by a node script in the same way that I demonstrated in Part 2 of this series. 

The output of the command is as follows:

619 bytes written to /var/folders/tn/q5mzq6n53blbszymdmtqkflc0000gs/T/destructive.zip using 25.393ms
Deploying /var/folders/tn/q5mzq6n53blbszymdmtqkflc0000gs/T/destructive.zip...

=== Status
Status:  Pending
jobid:  0Af80000003zYCfCAM
Component errors:  0
Components deployed:  0
Components total:  0
Tests errors:  0
Tests completed:  0
Tests total:  0
Check only: false


Deployment finished in 2000ms

=== Result
Status:  Succeeded
jobid:  0Af80000003zYCfCAM
Completed:  2017-12-24T17:14:02.000Z
Component errors:  0
Components deployed:  1
Components total:  1
Tests errors:  0
Tests completed:  0
Tests total:  0
Check only: false

and the component is gone from my org. If I’ve deployed it to a bunch of other orgs, I just need to re-run the command with the appropriate -u switch.

Related Posts

 

 

 

Tuesday, 19 December 2017

SFDX and the Metadata API Part 2 - Scripting

SFDX and the Metadata API Part 2 - Scripting

Introduction

In Part 1 of this series, I covered how you can use the SFDX command line tool to deploy metadata to a regular (non-scratch) Salesforce org, including checking the status and receiving the results of the deployment in JSON format. In this post I’ll show how the deploy and check can be combined in a node script to allow you to show the progress of the deployment. The examples below are for MacOS - if that isn’t your operating system you may have to do some tweaking, although as I’m not using directory names I don’t think that will be the case. These examples also assume that you are in the directory that you cloned the repository into in Part 1.

Needs Node

You’ll need Node.js installed in order to try out the example - you can download it here. You’ll also need the SFDX CLI, but I’m sure everyone has that from the first post in this series, right?

Node has a built-in module, named child_process, that allows you to execute an application on your local disk.  While most things Node and JavaScript are asynchronous, the authors of child_process have given us synchronous versions too. These block the node event loop until the application has finished executing and then return the output of the application as the result. Perfect for scripting.

Executing SFDX

The function that we are interested in is execFileSync, which takes the name(or path) of the application to execute and an array of parameters. In the previous post, my command to execute the deployment was:

> sfdx force:mdapi:deploy -d src -u keirbowden@googlemail.com

To carry out the same operation via the execFileSync function:

child_process.execFileSync('sfdx',
                           ['force:mdapi:deploy', '-d', 'src',
                            '-u', 'keirbowden@googlemail.com]);

Processing the Results

By default the results of the deploy will be returned in a human-readable text format, but supplying an additional parameter of ‘—json’ turns it into JSON format,  (note this is much redacted output!):

{
  "status": 0,
  "result": {
      ...
    "id": "0Af80000003ynf6CAA",
    "status": "Succeeded",
    "success": true
  }
}

which JavaScript can easily parse into an object - this is the main reason that I script tools like this in node - parsing JSON in bash scripts is way more difficult.

var jsonResult=child_process.execFileSync('sfdx',
                               ['force:mdapi:deploy', '-d', 'src',
                                '-u', 'keirbowden@googlemail.com]);
var result=JSON.parse(jsonResult);
console.log(‘Status = ‘ + result.result.status);

Outputs ‘Status = Succeeded’.

Polling the Deployment

The result from the execution of the deployment contains an id parameter:

    "id": "0Af80000003ynf6CAA"

which can be used to request a deployment report from the org. 

child_process.execFileSync('sfdx’,
                           ['force:mdapi:deploy:report',
                           '-i', result.result.id,
                            '-u', ‘keirbowden@googlemail.com', '--json’]);

the results of which are again returned in JSON format and can be processed easily through JavaScript.

All together now

Based on the above learning, here’s the sample node script that executes a deployment and then polls the org until it has completed, successfully or otherwise:

#!/usr/local/bin/node

var child_process=require('child_process');
var username='keirbowden@googlemail.com';

var deployParams=['force:mdapi:deploy', '-d', 'src',
                  '-u', username, '--json'];

var resultJSON=child_process.execFileSync('sfdx', deployParams);
var result=JSON.parse(resultJSON);
var status=result.result.status; while (-1==(['Succeeded', 'Canceled', 'Failed'].indexOf(status))) { var msg='Deployment ' + status; if ('Queued'!=status) { msg+=' (' + result.result.numberComponentsDeployed + '/' + result.result.numberComponentsTotal + ')' } console.log(msg); var reportParams=['force:mdapi:deploy:report', '-i', result.result.id, '-u', username, '--json']; resultJSON=child_process.execFileSync('sfdx', reportParams); result=JSON.parse(resultJSON); status=result.result.status; } console.log('Deployment ' + result.result.status);

Breaking this up a little, the child_process module is included and the name of my user assigned to a variable as I’ll be using it it in a few places:

var child_process=require('child_process');
var username='keirbowden@googlemail.com';

The deployment is then executed and the results parsed:

var deployParams=['force:mdapi:deploy', '-d', 'src',
                  '-u', username, '--json'];

var resultJSON=child_process.execFileSync('sfdx', deployParams);
var result=JSON.parse(resultJSON);

Then the code enters a loop that continues until the deployment has completed:

var status=result.result.status;
while (-1==(['Succeeded', 'Canceled', 'Failed'].indexOf(status))) {

Next I generate a message to display to the user - the status of the deployment and, if it isn’t queued, the number of components deployed and the total number:

var msg='Deployment ' + status;
if ('Queued'!=status) {
    msg+=' (' + result.result.numberComponentsDeployed + '/' +
                result.result.numberComponentsTotal + ')'
}
console.log(msg);

Then I execute the report on the status of the deployment and assign the results to the existing variable - as far as I’ve been able to tell the results of the deploy and deploy report are the same, but this doesn’t appear to be documented anywhere so may be subject to change:

var reportParams=['force:mdapi:deploy:report', '-i', result.result.id,
                          '-u', username, '--json'];
        resultJSON=child_process.execFileSync('sfdx', reportParams);
        result=JSON.parse(resultJSON);
        status=result.result.status;

and round the loop it goes again.

Executing this script generates the following output:

> node deploy.js
Deployment Queued
Deployment Pending (0/0)
Deployment Pending (0/0)
Deployment Pending (0/0)
Deployment InProgress (0/1)
Deployment Succeeded

Conclusion

This script just scratches the surface of what can be done with the results - for example, if any of the components fail it can raise the alarm in the org or elsewhere. It also polls continuously, which I wouldn’t recommend for a large number of components - I typically sleep for a few seconds in between each request. It also doesn’t do much with the final result aside from writing it to the screen. 

The SFDX force:mdapi:deploy command does have a ‘-w’ option to wait a specified period of time for the deployment to complete, which if set to -1 reports the progress at regular intervals in a very similar way until the deployment completes. This is fine if you are happy to wait until the end before taking any further action, but I like this granularity so that I can take action as soon as something happens. You should use what works for you.

Related Posts

 

Friday, 15 December 2017

Santa Force is Coming to Town

Santa Force is Coming to Town

Santa

Introduction

This post comes all the way from Lapland, from the workshop of Santa Force. a long time Salesforce user. This Salesforce instance has received some enhancements to help with the unique problems of this unique non-profit, which we’ll take a closer look at.

Customisations

There are a few additional fields on user, which don’t necessarily make a lot of sense when viewed in isolation:

Screen Shot 2017 12 15 at 09 59 47

However, they are vital for a formula field :

 

Screen Shot 2017 12 15 at 10 01 33

 

So as you can see, you’d better watch out, not pout and not cry. This might seem an odd requirement, but the help text tells you why:

 

Screen Shot 2017 12 15 at 10 02 06

 

 

On to Santa Force now, he’s making a list view. The elves created one a few days ago, but there’s some issues with it - the name doesn’t look right and there’s a few fields missing.

 

Screen Shot 2017 12 15 at 10 37 42

 

Santa Force clones the list view, renames it and adds the required fields:

 

Screen Shot 2017 12 15 at 10 36 55

 

This is much better - he’s making a list view, he’s checked it twice and can now see who has been naughty or nice.

 

There’s also a process builder that works off another custom field on the contact record - a checkbox field labelled Asleep?

 

Screen Shot 2017 12 15 at 10 41 39

 

So Santa Force knows if you are sleeping, and knows if you are awake, because it is posted to his chatter feed:

Screen Shot 2017 12 15 at 10 17 35

 

 

Finally, there’s one more field on contact - Goodness.  Santa Force can look at this field and determine if you’ve been good or bad - there’s also some useful help text that will guide a contact’s behaviour if they view this though the community.

 

Screen Shot 2017 12 15 at 10 19 03

 

Why?

The key question is what is all this information being gathered for? Checking the calendar, we can see that it’s for an event scheduled for 24th December:

 

Screen Shot 2017 12 15 at 10 22 16

 

As you can see, Santa Force is Coming to Town!

Happy Christmas everyone and thanks for reading the Bob Buzzard Blog.

 

Tuesday, 12 December 2017

SFDX and the Metadata API

SFDX and the Metadata API

Introduction

SFDX became Generally Available in the Winter 18 Release of Salesforce and I was ready for it. However, my use case was our BrightMedia appcelerator which is mostly targeted at sandboxes and production orgs, where scratch orgs wouldn’t really help that much. The good news is that the SFDX CLI has support for metadata deploy/retrieve operations via the mdapi commands in the force topic.

What you need

In order to deploy metadata you need the directory structure and package.xml manifest - if you’ve used the Force.com migration tool (ant) or the Force CLI, this should be familiar. For the purposes of this blog I’m using the GITHUB repository from my Take a Moment blog post, which has the following structure:

src/
src/package.xml
src/aura/
src/aura/TakeAMoment
src/aura/TakeAMoment/TakeAMoment.cmp
src/aura/TakeAMoment/TakeAMoment.cmp-meta.xml
src/aura/TakeAMoment/TakeAMoment.css
src/aura/TakeAMoment/TakeAMomentController.js
src/aura/TakeAMoment/TakeAMomentHelper.js
src/aura/TakeAMoment/TakeAMomentRenderer.js

What you do

The first thing I do is clone the repo to my local filesystem and navigate to the directory created:

 > git clone https://github.com/keirbowden/TakeAMoment.git
Cloning into 'TakeAMoment'...
remote: Counting objects: 20, done.
remote: Total 20 (delta 0), reused 0 (delta 0), pack-reused 20
Unpacking objects: 100% (20/20), done.
> cd TakeAMoment

I then set this up as an SFDX project:

> sfdx force:project:create -n .
create sfdx-project.json
conflict README.md
force README.md
create config/project-scratch-def.json

Next I login to one of my dev orgs:

> sfdx force:auth:web:login
Successfully authorized keirbowden@googlemail.com with org ID …..
You may now close the browser

(For the purposes of this blog my login is ‘keirbowden@googlemail.com’ - substitute your username in the commands below)

Everything is now set up and I can deploy to my dev org:

> sfdx force:mdapi:deploy -d src -u keirbowden@googlemail.com
2884 bytes written to /var/folders/tn/q5mzq6n53blbszymdmtqkflc0000gs/T/src.zip using 36.913msDeploying /var/folders/tn/q5mzq6n53blbszymdmtqkflc0000gs/T/src.zip...
=== StatusStatus:  Queuedjobid:  0Af80000003ynf6CAA
The deploy request did not complete within the specified wait time [0 minutes].To check the status of this deployment, run "sfdx force:mdapi:deploy:report"

Sometimes the deployment completes immediately, but most of the time it takes a bit longer and I have to query the status via the command that the SFDX CLI helpfully gives me in the output:

> sfdx force:mdapi:deploy:report
=== Result
Status: Succeeded
jobid: 0Af80000003ynf6CAA
Completed: 2017-12-12T16:28:39.000Z
Component errors: 0
Components checked: 1
Components total: 1
Tests errors: 0
Tests completed: 0
Tests total: 0
Check only: true

And that’s it - my deployment is done!

Why would you do this?

That’s a really good question. For me, the following reasons are good enough:

  1. The SFDX CLI, unlike the Force Migration Tool, uses oauth to authorise operations, so I don’t need to specify the password in plaintext. It also means that the rest of my team don’t need to learn ANT.
  2. The SFDX CLI, unlike the Force CLI, allows me to fire the deployment off and query the status later, plus it gives me a lot of information in the report.

It’s also clear to me that SFDX is the future, so aligning myself with the SFDX CLI seems a sensible move.

It also allows me to get the status of the deployment as JSON:

> sfdx force:mdapi:deploy:report --json

which gives me a ton of information:

{
  "status": 0,
  "result": {
    "checkOnly": false,
    "completedDate": "2017-12-12T16:28:39.000Z",
    "createdBy": "00580000001ju2C",
    "createdByName": "Keir Bowden",
    "createdDate": "2017-12-12T16:28:09.000Z",
    "details": {
      "componentSuccesses": [
        {
          "changed": "true",
          "componentType": "AuraDefinitionBundle",
          "created": "true",
          "createdDate": "2017-12-12T16:28:36.000Z",
          "deleted": "false",
          "fileName": "src\/aura\/TakeAMoment",
          "fullName": "TakeAMoment",
          "id": "0Ab80000000PEGWCA4",
          "success": "true"
        },
        {
          "changed": "true",
          "componentType": "",
          "created": "false",
          "createdDate": "2017-12-12T16:28:38.000Z",
          "deleted": "false",
          "fileName": "src\/package.xml",
          "fullName": "package.xml",
          "success": "true"
        }
      ],
      "runTestResult": {
        "numFailures": "0",
        "numTestsRun": "0",
        "totalTime": "0.0"
      }
    },
    "done": true,
    "id": "0Af80000003ynf6CAA",
    "ignoreWarnings": false,
    "lastModifiedDate": "2017-12-12T16:28:39.000Z",
    "numberComponentErrors": 0,
    "numberComponentsDeployed": 1,
    "numberComponentsTotal": 1,
    "numberTestErrors": 0,
    "numberTestsCompleted": 0,
    "numberTestsTotal": 0,
    "rollbackOnError": true,
    "runTestsEnabled": "false",
    "startDate": "2017-12-12T16:28:29.000Z",
    "status": "Succeeded",
    "success": true
  }
}

Having the results in JSON also means that I can easily process it in JavaScript, which I’ll cover in my next post.

Related Posts

 

Monday, 20 November 2017

Animated Lightning Progress Bar

Animated Lightning Progress Bar

Introduction

The Salesforce Lightning Design System has a progress bar component, which can be used to communicate how far through a process the user is, or how close to achieving their target audience they are in BrightMedia. Typically this will be wired up to an attribute so that it updates automatically when the attribute value changes, for example:

<aura:application extends="force:slds" >
    <aura:attribute name="value" type="Integer" default="25" />
    <div class="slds-m-around_small">
        <div class="slds-text-heading_large slds-m-bottom_small">Progress Bar Demo</div>
        <div class="slds-m-bottom_large">
            <label>Enter value : <ui:inputNumber value="{!v.value}"/></label>
        </div>
        <div>
            <div style="width:25%" class="slds-progress-bar slds-progress-bar_circular slds-progress-bar_large"
                    aria-valuemin="0" aria-valuemax="100" aria-valuenow="{!v.value}" role="progressbar">
                <span class="slds-progress-bar__value" style="{! 'width:  ' + v.value + '%;'}">
                    <span class="slds-assistive-text">{!'Progress: ' + v.value + '%'}</span>
                </span>
                <div class="slds-text-align--center"><ui:outputNumber value="{!v.value}"/>
                   /
                <ui:outputNumber value="100"/></div>
            </div>
        </div>
    </div>
</aura:application>

which jumps the progress bar to the specified value:

while this works fine , it's not the greatest user experience. When a progress bar updates I prefer to see an animated version where it gradually makes it's way to the final value. There's no difference functionality-wise, but it just looks better to me.

The Animator

Animating a progress bar in JavaScript is simply a matter of making small changes to move between the current and desired value, typically via a timer that fires a function every ’n’ milliseconds to advance the value by a small amount. When using Lightning Components this is a little more tricky as the function executed by the timer is modifying the component outside of the framework lifecycle. In the revised app, when the user changes the desired value this is stored in a separate attribute and a controller function is executed:

<aura:application extends="force:slds" >
    <aura:attribute name="value" type="Integer" default="25" />
    <aura:attribute name="inputVal" type="Integer" default="25" />
    <aura:attribute name="timeoutRef" type="object" />
    <div class="slds-m-around_small">
        <div class="slds-text-heading_large slds-m-bottom_small">Progress Bar Demo</div>
        <div class="slds-m-bottom_large">
            <label>Enter value : <ui:inputNumber value="{!v.inputVal}" change="{!c.valueChanged}" /></label>
        </div>
        <div>
            <div style="width:25%" class="slds-progress-bar slds-progress-bar_circular slds-progress-bar_large"
                 aria-valuemin="0" aria-valuemax="100" aria-valuenow="{!v.value}" role="progressbar">
                <span class="slds-progress-bar__value" style="{! 'width:  ' + v.value + '%;'}">
                    <span class="slds-assistive-text">{!'Progress: ' + v.value + '%'}</span>
                </span>
                <div class="slds-text-align--center"><ui:outputNumber value="{!v.value}"
                    /
                >/<ui:outputNumber value="100"/></div>
            </div>
        </div>
    </div>
</aura:application>

following best practice, the controller method simply delegates to the associated helper

({
	valueChanged : function(component, event, helper) {
        helper.valueChanged(component, event);
	}
})

which does the actual work :

({
    valueChanged : function(cmp, ev) {
        var times=0;
        var current=cmp.get('v.value');
        var final=cmp.get('v.inputVal');
        var increment=1;
        if (final<current) {
            increment=-1;
        }
        var self=this;
        var timeoutRef = window.setInterval($A.getCallback(function() {
            if (cmp.isValid()) {
                var value=cmp.get('v.value');
                value+=increment;
                if (value==final) {
                    window.clearInterval(cmp.get('v.timeoutRef'));
                    cmp.set('v.timeoutRef', null);
                }
                cmp.set('v.value', value);
            }
        }), 100);
        cmp.set('v.timeoutRef', timeoutRef);
    }
})

the first part of the helper function simply captures the start and end values and figures out if we need to increment or decrement from the current value.  Next the timer is set up to repeat every 100 milliseconds. As the function executed by the timer changes the app component attributes, I have to wrap it in a $A.getCallback function call, which ensures that the lightning components framework rerenders the markup. Once the current value equals the desired final value, the timer is cleared otherwise it will fire forever more.

Change values with care

Refreshing the app now animates the progress bar to apply the changed value. Incrementing by 1 is probably overkill, especially if you are dealing with values of hundreds of thousands for example. In this situation I’d simply decide how many “jumps” I wanted to apply to the progress bar, divide the difference between the current and desired value by the number of jumps and then add the result to the value each time the timer fired.

Related posts

 

Saturday, 21 October 2017

Programming against Apex Interfaces

Programming against Apex Interfaces

Interfaces

Introduction

In the dim and distant past (getting on for 10 years ago now), when I was a Java programmer working in the systems integration and financial services space, the majority of the programming that I did was against interfaces rather than concrete class instances. This isn’t something that I see very often in the Salesforce world (at least on the SI side - I’d imagine ISVs go in for it a lot more) for a variety of reasons including:

  • Lots of Salesforce work is a point solution on an existing implementation, so it doesn’t always merit abstraction via interfaces.
  • Customers don’t want to the extra cost and accept that additional development effort may be required in future.
  • Many people have ended up as Salesforce developers through non-traditional routes and haven’t been exposed to interfaces.

Simply put, programming against interfaces means that rather than identifying the specific class that carries out an operation in your code, you identify an interface and rely on there being a class that implements that interface at run time. This allows your code to focus on what the operation needs to do rather than how it is accomplished.

Why?

Programming against interfaces introduces flexibility. You can change the implementation of the interface without affecting any of the code that uses the interface. Thus you could start out with a faker implementation that simply returns canned data to allow you to develop the real world interface implementation and the consuming code in parallel. It also means you can have multiple implementations of an interface inside a single system and swap them around via configuration.

Code me. Now.

The scenario for the example is calculating the discount due to an account. The customer has told us that at the moment it is a flat 10%, but this is an area that they will want to change in the future to take into account the account’s industry. This is a classic use case for an interface as we know that we will need to swap out the implementation in the future, and if it changes once it is like to change again in the future.

Concrete classes

My initial implementation of the class to calculate the discount is as follows:

public class SimpleAccountDiscount {
	public double getDiscount(Id accountId) {
        return 10;
    }
}

and I can use this directly in code:

double discount=new SimpleAccountDiscount().getDiscount('00124000004N1TfAAK');
System.debug('Discount = ' + discount);

producing the following output:

07:02:45:045 USER_DEBUG [2]|DEBUG|Discount = 10.0

all well and good. Next I create the more complex version which takes the industry into account - yes, complex is probably over-egging it a bit, but all things are relative.

public class ComplexAccountDiscount {
    public double getDiscount(Id accountId) {
        // default value
        Double discount=10;
        Account acc=[select id, Industry
                     from Account
                     where id=:accountId];

        if (acc.Industry=='Apparel’) {
            discount=15;
        }
        else if (acc.Industry=='Consulting’) {
            discount=5;
        }
        
        return discount;
    }
}

And I can use this in code just as easily :

System.debug('Discount for Burlington (apparel) = '
             + new ComplexAccountDiscount().getDiscount('00124000004RIGFAA4'));

System.debug('Discount for Dickenson (consulting) = '
             + new ComplexAccountDiscount().getDiscount('00124000004RIGHAA4'));

produces the output:

17:14:25:078 USER_DEBUG [1]|DEBUG|Discount for Burlington (apparel) = 15.0
17:14:25:081 USER_DEBUG [4]|DEBUG|Discount for Dickenson (consulting) = 5.0

However, when the customer is ready to move to the more complex version, I need to carry out a deployment in order to start using my new class. Plus if it turned out that a downstream system wasn’t ready for the change, I’d have to carry out another deployment to revert to the simple version. 

Implementing an interface

The following Apex interface reflects the method that must be exposed by any discount implementation:

public interface AccountDiscountInterface
{
    double GetDiscount(Id accountId);
}

Note that I don’t specify an access modifier for the method - as an interface reflects the public interface, the methods in the interface are implicitly public. I then modify may classes (only the complex version shown):

public class ComplexAccountDiscount implements AccountDiscountInterface {

I can then use the interface in place of a concrete class:

AccountDiscountInterface adi=new ComplexAccountDiscount();
System.debug('Discount for Burlington (apparel) = '
             + adi.GetDiscount('00124000004RIGFAA4'));

So my code that gets the discount doesn’t care about the implementation, but the previous line that instantiates the concrete class does. A partial success at most.

Dynamically instantiating a class

The final piece of the puzzle is dynamically instantiating a class based on configuration. If I can do this, my customer can switch implementations simply by changing a custom setting. Dynamical instantiation consists of two parts. First Type.forName() is used to get the type of the Apex class. Then the newInstance() method of the resulting Type is executed to create an instance of the named class. I’ve placed the name of the implementing class into an instance of the Account_Discount_Setting__c custom setting named ‘Default’. This has a field called Implementing_Class__c that I’ve set to ‘ComplexAccountDiscount’:

Account_Discount_Setting__c setting=
    Account_Discount_Setting__c.getInstance('Default');

Type impl = Type.forName(setting.Implementing_Class__c);
AccountDiscountInterface adi=
    (AccountDiscountInterface) impl.newInstance();

System.debug('Discount for Burlington (apparel) = '
             + adi.GetDiscount('00124000004RIGFAA4'));

Now my code has no knowledge of the class that is implementing the discount calculation, it simply creates whatever class has been configured and uses that. If my customer wants to switch the implementation, it’s as simple as changing a field in a custom setting. It also allows me to set up a different version for testing - unit tests should be as simple as possible so if I have a genuinely complex discount implementation I probably don’t want to use that when testing the consuming code in case it has a side effect that my test isn’t expecting - I’d still test that implementation, but in it’s own unit tests.

So these should be used always?

As I mentioned earlier, you don’t always need an interface. They do add a little overhead, as I now have an additional custom setting and interface to create and deploy. If the implementation is never likely to change then there’s no point in abstracting it away like this. We use them a lot in BrightMedia as it allows us to have a selection of implementations for services that customers can chose between.