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.oauth.token(window.signedRequestJson.oauthToken);
  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!