Salesforce Canvas Quick Start for Java Developers

Salesforce provides a variety of different ways to integrate external apps into the Salesforce UI. Canvas is an iframe-based approach for loading externally hosted UIs into pages on Salesforce. The nice thing about Canvas versus a plain iframe is that Canvas has a JavaScript bridge which enables secure communication between the external iframe and Salesforce. This communication happens in the context of the Salesforce user and doesn’t require the typical OAuth handshake. Because Canvas apps live outside of Salesforce they can be built with any language and run anywhere, including Heroku.

I’ve put together a quick start Canvas app that uses Java and Play Framework to get you going in minutes. You can either run this app on Heroku or on your local machine. The fewest steps to get everything setup is with Heroku so I’ll cover that first.

Deploying a Canvas App on Heroku

Heroku is an app delivery platform that works with a variety of back-end programming languages and frameworks. I’ve created a Canvas-ready Java app using Play Framework and set it up for instant deployment. To get started, signup for a free Heroku account (if needed), then launch your own copy of the salesforce-canvas-seed app.

Once the app has been deployed, open / view the app and follow the instructions to complete the setup process. You will create a new Connected App on Salesforce that is used to identify the external app. Once you’ve completed the instructions you will now have a fully functional Canvas app, running on Heroku, and written in Java.

Running a Canvas App Locally

Cloud deployment with Heroku is quick and easy but if you want to make changes to your app you should setup a local development environment. To do that, download the salesforce-canvas-seed Activator bundle, extract the zip, and from a command line in the project’s root directory, run (on Windows, omit the ./):

./activator -Dhttps.port=9443 ~run

This will start the app with HTTPS enabled. Connect to the app: https://localhost:9443
Your browser may give you a warning about the certificate not being valid, which you should ignore / approve the connection. Then you will see instructions for setting up a new Connected App on Salesforce which will be used for local development. After following those instructions you will have a Canvas app running locally. Now you can begin making changes to the app.

The app/assets/javascripts/index.js file contains the client-side application while the app/views/index.scala.html file contains the HTML content for the application. The app you’ve just setup should just be displaying the logged in user’s name. That is happening using some jQuery and the Canvas SDK. The HTML file contains:

<h1>Hello <span id='username'></span></h1>

The index.js file contains:

Sfdc.canvas(function() {
  // Save the token
  Sfdc.canvas.byId('username').innerHTML = window.signedRequestJson.context.user.fullName;

This JavaScript sets up the OAuth token for the Canvas SDK. Then the contents of the username tag are replaced with the current user’s name.

That should be everything you need to get started building against the Canvas SDK. For more information on that check out the Canvas Docs.

Let me know how it goes!

Introducing Force WebJars: Add JavaScript Libs to Salesforce With a Click

The typical method of adding JavaScript and CSS libraries (e.g. jQuery, Bootstrap, and AngularJS) to Salesforce environments is to locate a library’s download, download it, then upload it to Salesforce, then figure out the structure of the files so that you can use them from Visualforce. Using WebJars as a basis, I’ve created an easy way to add libraries to Salesforce, called Force WebJars.

Here is a quick demo:

Give it a try and let me know how it goes!

BTW: The source is on GitHub.

Dreamforce 2014: Wearables, Engagement Apps, $1M Hackathon

Dreamforce 2014 is quickly approaching and this year is going to be amazing! I’ll be presenting a few sessions and helping at the $1 Million Hackathon. Here are my sessions:

  • Integrating Clouds & Humans with the Salesforce Wear Developer Packs

    As smart watches and other human-integrated devices make their way into the mainstream, developers will need to quickly ramp up to these new paradigms and interaction models. Integrating these new wearable devices with Salesforce connects users to their businesses and customers in new ways. Join us as we use code and examples to dive into the architecture and patterns for developing wearable Salesforce apps with the Salesforce Wear Developer Pack for Android Wear.

  • Architecting Engagement Apps

    Modern systems are composed from all sorts of pieces, like back-office systems, legacy systems, mobile apps, JavaScript web UIs, third-party services, relational data, NoSQL data, and big data. Effective user engagement requires an architecture that brings all of these pieces together instead of the traditional siloed approach. Join us to learn about the Engagement Architecture and how it can be used to create modern composition-oriented systems.

This year at the $1M Hackathon there will be 35 different prizes including prizes for building apps on Heroku and prizes for open source projects!

Hope to see you there!

An Architects Guide to the Salesforce1 Platform was initially created as a Sales Force Automation (SFA) / Customer Relationship Management (CRM) application in the cloud but has evolved over the years into a modern platform for all types of enterprise applications. Now the Salesforce name is a legacy artifact of that past. This is like the name Frigidaire which is still the name for a company that now produces much more than Frigidaires (i.e. Refrigerators). The Salesforce1 Platform still provides the SFA & CRM applications but is also a foundation for building modern systems.

Pricing & Additions

The Salesforce1 Platform comes in many editions and packages, like the Sales Cloud edition for CRM and the Platform edition for anything. The edition you choose will enable different features and provide a different foundation to start with. Check out the full list of editions to see the pricing and features for each option. The Developer Edition provides a free platform for developers.

Now lets go through the many different components of the Salesforce1 Platform from the 30,000 foot perspective.

Metadata-Driven Data Model

At the core the Salesforce1 Platform is a cloud database. That database is customized and configured via metadata. The metadata that defines the data model can be modified via XML definitions and via a point-and-click UI. The metadata for a tenant environment, known as an ‘organization’, or ‘org’, is versionable, packageable, and testable. An object or table is called an SObject and provides a bunch of out-of-the-box features:

  • Custom Fields
  • Validation Logic
  • Field-level Security
  • Relationships & Pick-Lists
  • Derived Values

All SObjects automatically provide:

  • Basic CRUD-ish UIs
  • Mobile CRUD-ish UIs via the Salesforce1 mobile app
  • Indexed Search

Fields on SObjects can be any of the following types:

  • Auto Number
  • Formula
  • Roll-Up Summary
  • Lookup Relationship
  • Master-Detail Relationship
  • Checkbox
  • Currency
  • Date & Date/Time
  • Email
  • Geolocation
  • Number & Percent
  • Phone
  • Picklist & Picklist Multi-Select
  • Text, Text Area, Encrypted Text
  • URL

New organizations on the platform come with a number of out-of-the-box SObjects which differ depending on which edition of the platform you are using. For instance, new organizations using the Sales Cloud edition come with SObjects including Contact, Lead, and Opportunity.

Built into the Salesforce data model are essential security features like change auditing and field-level security.

Managed Runtime for Programmatic Customizations & Extensions

A system on the Salesforce1 Platform can be built entirely using the Metadata-driven Data Model. But there are use cases when programmatic logic is needed for things like custom UIs, triggers, and scheduled jobs. The programming languages used to write programmatic logic on the platform are:

  • Visualforce – Server-side templating language for custom UIs that run inside of your Salesforce system
  • Apex – Programmable logic for triggers, Visualforce controllers, & scheduled jobs
  • SOQL – Domain Specific Language (DSL) for database queries

Visualforce uses a JSP-like syntax for creating custom HTML pages that are rendered inside of and can also be rendered in the Salesforce1 mobile app. Pages in Visualforce use the traditional server-side MVC architecture where the Visualforce page is the View, an Apex class is the controller, and the model is SObjects. Visualforce pages can include any JavaScript and can use JavaScript Remoting and/or RESTful JSON services. Here is a simple Visualforce page:

    hello, world

Apex has a Java-like syntax and runs on Salesforce in a managed, sandboxed, and secure runtime. There is both an Eclipse plugin and a web-based Developer Console for writing Apex. Apex triggers attach to SObject events like update, create, and delete. Batch jobs and scheduled jobs are also written in Apex. Here is a simple Apex trigger:

trigger Foo on Contact (after insert) {
    for (Contact newItem : {
        System.debug('Contact Created: ' + newItem.Name)

SOQL queries can be run in the Developer Console and can also be easily embedded in Apex, for instance:

Contact contact = [SELECT Id FROM Contact LIMIT 1];

Apex includes a JPA/Hibernate-like database access syntax called DML. This makes it easy to create, update, and delete SObjects in Apex. For example:

Contact c = new Contact(LastName='Bar');
insert c;
c.FirstName = 'Foo';
update c;
delete c;

Like SObject metadata, all of the programmatic code in Salesforce is versioned, packageable, and testable. Unit testing and code coverage are built into the Apex runtime and 75% code coverage is required in order to deploy code into a production Salesforce system. This code coverage requirement helps maintain stability across major platform upgrades because Salesforce uses customer tests to detect regressions and breakages.

Instead of writing Apex many approval processes and business rules can be created declaratively using Workflow. Just like SObject metadata, Workflows can be created with a point-and-click web interface, the Visual Workflow editor. Under the covers all workflows are just metadata which can be versioned and packaged like all of the other platform extensions and customizations.

The UIs, Salesforce1 Mobile App, Apex runtime and Workflow systems are for back-office, employee-facing interactions. For customer-facing interfaces that interact with data on Salesforce, the Heroku service (part of the Salesforce1 Platform) enables developers to easily create, deploy, and scale custom web apps, mobile apps, and web / REST services. Heroku apps can be written in any language (Java, Ruby, Node.js, etc) and are deployed on a fully managed system that provides the infrastructure developers would normally have to assemble and manage on their own. For instance, services like load balancing, failover, centralized logging, continuous delivery pipelines, and instant scalability are provided out-of-the-box on Heroku.

Integration and ETL

The Salesforce1 Platform provides a variety of ways to integrate with other systems and perform data migrations & synchronization. The major interfaces for these types of data integrations are:

  • Heroku Connect – A standard, high-performance SQL interface to the data on Salesforce.
  • SOAP APIs – Schema-rich web services.
  • REST APIs – Simple JSON web services.
  • Streaming APIs – Event-driven messaging service.
  • Data Import & Export – Numerous tools, wizards, and web services provide easy access to import and export Salesforce data.
  • Email Notifications – Apex and Workflow can be used to send email notifications from Salesforce.
  • Mobile Notifications – Mobile notifications are built into the Salesforce1 mobile app and custom notifications are also supported.
  • OAuth 2.0 – The Salesforce web services use OAuth 2.0 to handle authenticating users so that integrated applications can make API requests on their behalf.
  • SAML – Enterprise Single Sign-On.
  • Mobile SDKs – Native, Hybrid, and HTML5 SDKs for custom mobile apps.
  • Integration Platform Vendors – Many integration platform vendors like InformaticaBoomiCast Iron, and MuleSoft have out-of-the-box support for integrating with Salesforce.

Massive Ecosystem

There is a massive galaxy of services, apps, frameworks, and libraries around the Salesforce1 Platform. Here are some of those:

The Platform You Can Trust

Because the Salesforce1 Platform is your foundation for business-critical data and apps, the foundation of Salesforce must be Trust. In large enterprise systems there are many aspects to Trust, like transparency of system uptime & responsivenessmulti-tier security, and privacy & certifications.

Get Started

Ready to dive in? The best way to dip your toes in the water and starting building something on the Salesforce1 Platform is by going through the Salesforce Developer Workshop. It won’t cost you anything except time and will help you to understand many of these components by using them. Let me know how it goes!

Salesforce Gradle Plugin

As part of the Salesforce Wear Developer Pack for Android Wear I created a Gradle plugin that fetches and deploys Salesforce code (Apex). Gradle is the default build tool for Android but it can also be used with many other languages. For instance, here is an example build.gradle file for a project that fetches all of the Apex classes and Visualforce pages:

buildscript {
    repositories {
    dependencies {
        classpath 'com.jamesward:force-gradle-plugin:0.1'
apply plugin: 'force'
repositories {
force {
    username = forceUsername
    password = forcePassword
    unpackagedComponents = ["ApexPage": "*", "ApexClass": "*"]

The unpackagedComponents definition uses the Salesforce Metadata Types and pulls everything specified down into the src/main/salesforce/unpackaged directory when you run the forceMetadataFetch Gradle task. The forceMetadataDeploy Gradle task deploys everything in the src/main/salesforce/unpackaged directory to Salesforce.

Try this out:

  • Install Gradle
  • Create a new project directory containing the build.gradle above
  • In your project directory create a new file named containing your Salesforce username & password:
  • Fetch your Salesforce Metadata:

    gradle forceMetadataFetch
  • Make a change and deploy the Metadata:

    gradle forceMetadataDeploy

For a complete example check out the Visualforce + AngularJS + Bootstrap project.

All of the code for the Salesforce Gradle Plugin is on GitHub:

Let me know what you think. Thanks!

Create Webhooks on

Webhooks are the modern, web-oriented way for servers to receive notifications from other servers. For instance, when an event happens on a server, like, your own custom application can receive the event via a web request.

Salesforce already has a built-in way to handle events called Triggers which run on Salesforce via Apex code. However, you may want to receive these events in your own custom application. In Salesforce it is pretty easy to write the Apex to do this but why not automate that process? I built the Salesforce Webhook Creator to do just that. Here is a short demo:

If you want to test it out, use my Echo Webhook app by entering a URL like:

All of the code is on GitHub – contributions welcome!

Let me know what you think!

Cross-Origin Resource Sharing (CORS) for

By default browsers limit access to cross-origin resources. For instance, if a JavaScript app is loaded from then it isn’t allowed to access content from because this would be a significant security hole. Cross-Origin Resource Sharing (CORS) is the way to workaround this limitation in modern browsers. has a great REST api but unfortunately it doesn’t yet have native CORS support (but you can vote for this feature). Having CORS support comes in handy with JavaScript UIs on top of the Salesforce REST APIs. Luckily you can easily workaround this by proxying the API requests through the server that is serving the JavaScript UI so that the REST requests are not cross-origin. But it is tedious to set this up for every app, so I created a generic Salesforce CORS proxy.

For demo purposes the CORS proxy is available at:

So you can just replace your Salesforce domain name with to use the CORS proxy. Here is an example:

$ curl -i -H 'Authorization: Bearer YOUR_SESSION_ID'
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *

The HTTP Response contained the necessary CORS header on the GET request. An OPTIONS request also returns the right response headers to allow the request.

This app is open source so you can easily deploy it on your own Heroku app or in your own environment for production usage.

One of the other nice features of this proxy is that it figures out which Salesforce instance to connect to. So you no longer need to specify something like – instead just use one domain name for all of your apps and instances.

I hope this is useful for you. Let me know if you have any questions or feedback.

Integrating Clouds & Humans with Salesforce and Android Wear

Right out of the gate in my new job at and I have been working on a pretty exciting new project to integrate clouds and humans using and Android Wear. This week Salesforce launched six new open source developers packs for wearables. I created the Salesforce Wear Pack for Android Wear to help developers start building cloud-driven wearable apps for emerging devices like smart watches. Check out a short demo of the sample app I built:

All of the code and instructions for getting this application running in your development environment are in the QuoteDiscountApproval sample app.

This project was a ton of fun and I’ve learned a bunch of new things about Android, Gradle, and which will provide some great fodder for upcoming blogs. So check out the Salesforce Wear Pack for Android Wear and stay tuned for more blog posts on these topics.

New Adventures for a Technology Adventurer

Over the past year and a half I’ve had the great privilege of working with some really amazing people and projects at Typesafe. I’m a huge fan of the Typesafe Platform and I’ve really enjoyed being part of Activator, Play Framework, Akka, Scala, Slick, and the Reactive Manifesto. But at heart I’m a Technology Adventurer who loves to learn and create new things. Now it is time for me to embark on a new adventure at where I will be helping create something new.

I’ve been doing IT & Ops since ’97 and been writing code for over 20 years. I joined Typesafe because I knew the future of software development would be built around a stellar developer experience that didn’t sacrifice the servers’ experiences. The Typesafe Platform is the best-in-class platform, optimizing for both of these. I will not just continue to be a user of these technologies but also an enthusiastic evangelist.

The Typesafe technologies are really taking off and I’m incredibly privileged to have been a part of that explosion. I’m definitely saddened that I won’t be directly involved in the next phase of that adventure but I’m also excited for the adventure that lies ahead at where things like Heroku, GoInstant, and Salesforce1 are providing new and exciting ways for developers to build engaging apps.

I’m really looking forward to this new adventure! Stay tuned!