CHAPTER 2
Quick Start
In this chapter ...
•
Prerequisites
•
Create the App
•
Set the App Location
This simple quick start shows you how to get started with Force.com Canvas by using the Heroku Quick
Start. The Heroku Quick Start creates a “hello world” app on Heroku in either Java or Ruby, depending on the template you select. At the same time, it creates a corresponding canvas app in Salesforce.
The Heroku app is a “hello world” Web page that calls the Force.com Canvas SDK to display information about the current user and lets you post to the current user’s Chatter feed.
SEE ALSO:
Prerequisites
Create the App
Set the App Location
11
Quick Start Prerequisites
Prerequisites
You need the appropriate access and tools to complete the quick start steps.
•
Access to a Developer Edition organization.
If you are not already a member of the Force.com developer community, go to developer.salesforce.com/signup and follow the instructions for signing up for a Developer Edition organization. Even if you already have Enterprise Edition, Unlimited
Edition, or Performance Edition, use Developer Edition for developing, staging, and testing your solutions against sample data to protect your organization’s live data. This is especially true for applications that insert, update, or delete data (as opposed to simply reading data).
If you have an existing Developer Edition organization, and, from Setup, you don’t see the menu item Canvas App Previewer, contact Salesforce.
•
“Customize Application” and “Modify All Data” user permissions. If you’re an administrator, you most likely already have these permissions. Otherwise, you need to add them so that you can see the Canvas App Previewer and create canvas apps.
•
A Heroku account. Go here to create a Heroku account: https://api.heroku.com/signup
.
•
Java version 1.6 or 1.7 to run the local instance of the “hello world” app that you create. (The Heroku instance of the app automatically downloads the correct version of Java.)
SEE ALSO:
Quick Start
Supported Salesforce Editions
Create the App
Create the App
In this step, you’ll create both the Heroku “hello world” app and the associated canvas app in your Salesforce organization.
1. In Salesforce, from Setup, enter
Canvas App Previewer
in the
Quick Find
box, then select Canvas App Previewer.
2. Click Heroku Quick Start.
3. In the
Template
field, select Java – Quick Start Template.
4. In the
Canvas App Name
field, enter a unique name of up to 30 characters.
5. In the
Heroku App Name
field, enter a unique name of up to 30 characters that begins with a letter and contains only lowercase letters, numbers, and dashes. The
newappName
must be unique across all Heroku apps. This name becomes part of the URL for your app, for example,
newappName.herokuapp.com
.
6. In the
Auth Type
field, select OAuth or API Key. Heroku OAuth initiates the Heroku OAuth flow or uses the Heroku token if you’re logged in to Heroku. Find the API key associated with your account on the Heroku
My Account
page.
7. Click Create. The app displays in the left navigation pane.
If you see an error like “Error [Read timed out] executing POST to Heroku clone REST service,” this means the operation has timed out trying to contact Heroku. You can check the status of Heroku at http://status.heroku.com
.
Note:
If you have two-factor authentication enabled and select OAuth, first enter your Heroku username and password and then your two-factor authentication information. Close the OAuth prompt and click Create again, and the app now displays in the navigation pane.
12
Quick Start Set the App Location
8. Click the link to your new app on the left.
The app appears and you’ll see the message
Hello
User.FullName
, as well as other information about the current user.
You just created a canvas app—congratulations! You’ll only be able to see your canvas app in the Canvas App Previewer until you set
the locations where it can appear by following the steps in Set the App Location
. This defines where a user sees your app after it’s installed in their organization.
Behind the scenes, the Heroku Quick Start sets the canvas app’s
Permitted Users
, which includes admin-approved users and your profile. For example, if your user profile is System Administrator, that profile is added to the canvas app you just created, and any users with that profile can access the canvas app.
We recommend that you inspect the code to see how the canvas app works. The source code for the app is available in public GitHub repositories for the Java app and Ruby app . Use the example code in these apps to learn how to decode and validate the canvas signed request in your app.
SEE ALSO:
Quick Start
Prerequisites
Force.com Canvas Limits
Set the App Location
Set the App Location
In this step, you’ll specify where your canvas app can display to a user in Salesforce.
1. In the Salesforce application, from Setup, enter
Apps
in the
Quick Find
box, then select Apps.
2. In the Connected Apps related list, click the app you just created and then click Edit.
3. In the Canvas Apps Settings section, in the
Locations
field, select where the canvas app can appear to the user. For this walkthrough, select Chatter Tab.
•
Chatter Feed—The canvas app appears in the feed. If this option is selected, you must create a CanvasPost feed item and ensure that the current user has access to the canvas app.
•
Chatter Tab—The canvas app appears in the app navigation list on the Chatter tab. If this option is selected, the canvas app appears there automatically.
•
Console—The canvas app appears in the footer or sidebars of a Salesforce console. If this option is selected, you must choose where the canvas app appears in a console by adding it as a custom console component.
•
Layouts and Mobile Cards—The canvas app can appear on a page layout or a mobile card. If this option is selected, you choose where the canvas app appears by adding it to the page layout.
•
Mobile Nav—The canvas app is accessible from the navigation menu.
•
Open CTI—The canvas app appears in the call control tool. If this option is selected, you must specify the canvas app in your call center’s definition file for it to appear.
•
Publisher—The canvas app appears in the Chatter publisher and action bar. If this option is selected, you must also create a canvas custom action and add it to the global publisher layout or to an object’s page layout.
•
Visualforce Page—The canvas app can appear on a Visualforce page . If you add an
<apex:canvasApp>
component to expose a canvas app on a Visualforce page, be sure to select this location for the canvas app; otherwise, you’ll receive an error.
4. Click Save.
13
Quick Start
Because you selected Chatter Tab, your canvas app now appears in the left navigation pane on the Chatter tab.
SEE ALSO:
Quick Start
Create the App
Where Canvas Apps Appear
Quick Start—Advanced
Set the App Location
14
