Getting Started on Heroku with Heroku Connect

Introduction

This tutorial will show you how to deploy and manage an application in minutes. Unlike other Heroku Getting Started guides, this guide doesn’t require a local developer environment, so you don’t have to install a local development language or use the command line interface.

This tutorial demonstrates the Heroku platform, including Heroku Dashboard, Heroku Button and Heroku Connect. You will deploy an application to the web, view the running application, connect the database of the application to a Salesforce Developer Edition org, sync data, and modify the application to retrieve the data from the database.

The tutorial assumes that you have a free Heroku account and a free Salesforce Developer Edition environment.

Deploy the app

In this step, you will deploy a simple application. It’s an application written in the Ruby language, but the specifics of the application don’t matter too much in this tutorial.

You’re going to deploy it using a Heroku Button, which will:

• Automatically fetch the source code for the application.
• Deploy the application.
• Configure external services it uses. In this case, the Heroku Postgres database.
• Provide it with a domain name so that it’s accessible over the web.
• Make it available to you.

Click this button to install the app:

Once you’ve pushed the Deploy to Heroku button, you will be presented with the “New App” screen in your Heroku Dashboard, which displays details about the app and its configuration.

Scroll down the page and then, click “Deploy for Free” to deploy your application.

If your Heroku account hasn’t been verified yet, you will be asked you to verify your account by entering billing information. This information is needed to prevent platform abuse.

Look at the App Name field and take note of your app’s name. The name of the app used in this tutorial is gentle-thicket-9392. Your app will have a similar, automatically-generated name.

After the build finishes, click the View link at the bottom of the page to navigate to your running app. Alternatively, type your app’s domain name into your web browser. For example, if your app is called gentle-thicket-9392 then your app will be available at https://gentle-thicket-9392.herokuapp.com/.

You should see a page that says, “Getting Started on Heroku with Heroku Connect”

In this step, you deployed an application. It’s a simple step, but it resulted in a real, running application out there on the web, without you having to think about routers and domains and hardware. The source code for the app you deployed is open source, and soon you’ll learn how to modify the app and deploy your own changes.

Navigating Dashboard

The Heroku Dashboard makes it easy to manage your apps.

To open the Dashboard, navigate to https://dashboard.heroku.com/apps.

To view your apps, click Personal Apps in the column on the left.

In the list of apps, click the app you just created. The resources for your app are displayed.

At the top of this page, there are tabs to access other settings:

• Resources — Scale your app and manage add-ons.
• Deploy — Set options, including Heroku Git, GitHub or Dropbox.
• Metrics — View application-level metrics for your app.
• Activity — View the activity feed for your app.
• Access — Manage collaboration settings.
• Settings — Rename your app, view config vars, see info, transfer ownership or delete your app.

Dashboard provides a user interface for managing sets of applications, and the details of particular applications. As the rest of this tutorial demonstrates, it can be used to scale apps, set up add-ons, as well analyze app performance and monitor app activity.

Use Heroku Connect to Sync with Salesforce

In this step, you will set up Heroku Connect, which will sync data from a Salesforce Org to the Heroku Postgres database, which is attached to your app.

Visit your app on the web, and click the “Connect with your Salesforce Org” button. Your app will now open in Dashboard.

Click on the Heroku Connect add-on, listed in the Resources section.

The Heroku Connect “Setup Connection” screen will show.

Click “Next”.

You now need to authorize Heroku Connect to access your Salesforce Org.

Click “Authorize”, log in to Salesforce and authorize your app. If you don’t have a Salesforce org, sign up for a free Developer Edition account.

During authorization you’ll be asked to trust Heroku Connect. Click “Allow”.

You’ve now authorized Heroku Connect and established a connection between the Salesforce Org and your Heroku Postgres database. Now, create a mapping that instructs Heroku Connect on which Salesforce Objects to sync to Heroku Postgres, and whether the sync is bi-directional or not.

Scroll down to the mappings section and click “Create Mapping”:

In the list of Salesforce Objects, select “Contact”.

In the “Mapped Field” list, select the following 3 fields in addition to the default fields that Heroku Connect automatically requires:

• “Email”
• “Firstname”
• “Lastname”

Click “Save”.

The Heroku Connect panel will now show you a successful sync:

In this step, you configured Heroku Connect to create a uni-directional sync that maps Contact data in your Salesforce org, to a table in the Heroku Postgres database attached to your app. You could, for example, use this kind of mapping to expose Salesforce org data on a public web site. Setting up a bi-directional mapping would allow you to create new records in the Heroku app, and have those automatically sync across to your Salesforce org.

Create a Heroku Postgres Dataclip

In this step, you will create a Heroku Dataclip. Dataclips let you easily share the results of SQL queries on a Heroku Postgres database. Because your app now syncs Salesforce data to a Heroku Postgres database, you can make use of Dataclips to easily create multiple public or private views of the data.

Select your app in the Heroku Dashboard, and choose the “Resources” tab. You’ll see the add-ons for your application listed:

Click the disclosure buttons on the right hand side of the Heroku Postgres add-on, and then click “Create Dataclip”.

In the title field, type “All contacts”, and for the SQL query, copy this text, and then, click the “Create Dataclip” button.

SELECT
  firstname, lastname, email
FROM
  salesforce.contact
ORDER BY
  systemmodstamp DESC;

Heroku Dataclips runs the query and displays the results.

In this step, you ran your SQL query against data that originated in Salesforce. Dataclips can be shared, or embedded in other apps such as Google Docs. Heroku Postgres has many other features, including the ability to create a follower database, or to fork a database (useful when wanting to create a developer snapshot).

Deploying a change through GitHub

In this step, you will change the source code for the application and deploy that change using one of the easiest Heroku app deployment methods, GitHub integration. GitHub is a web-based source code management hosting service and it can be configured to automatically deploy code changes to Heroku.

To start, navigate to github.com, create a free account and log in. To clone the source code for the application, visit the source code repository at https://github.com/heroku/no-local-dev-getting-started and click “Fork” near the top right. This will create your personal copy of the source code for the app.

Now you’re ready to set up automatic deploys to Heroku.

In the Heroku Dashboard, navigate to your app and click the “Deploy” tab:

Click “Connect to GitHub”. After authorizing, you’ll be able to search for the app that you just forked:

Click “Connect” to connect the GitHub repo to the application. In the “Automatic deploys” section, click “Enable Automatic Deploys”:

You now have source code for the application in your own GitHub repository, and you’ve connected it to Heroku for automatic deployment whenever anything changes in that source code.

Try it out:

1. In GitHub, navigate to the views directory in the application source code repository.
2. Click home.erb.
3. Click the edit icon (the little pencil).
4. Change the text, “Getting Started on Heroku with Heroku Connect” to say, “Hello World” and then, click the “Commit changes” button.
5. In the Heroku Dashboard, click the “Activity” tab for your application. You’ll see a notice that the build is in progress. Hit refresh after a minute to see that it deployed.
6. Navigate to your application on the web and you’ll see the change that you made.

This was a small configuration change, but a powerful one. You enabled a continuous integration pipeline that lets you (or other developers) automatically push application changes to your source code repository, and have those changes automatically deployed to Heroku.

Modify app to list records

In this step, you’re going to modify the application by writing some code that will query the database, and display the results. This is how you could, for example, display Salesforce data that has been synced using Heroku Connect to the Postgres database.

1. Navigate to your cloned version of the app in GitHub. (The same way you did in the “Deploying a change through GitHub” step).
2. Click on app.rb.
3. Click the edit icon.

4. Ensure the following code is present:

   class Contact < ActiveRecord::Base
     self.table_name = 'salesforce.contact'
   end
   

5. Find and uncomment the following code (remove the leading # symbols from each line) which should appear just after the code above:

   get "/contacts" do
     @contacts = Contact.all
     erb :index
   end
   

Click “Commit Changes”. After 30 seconds, a new version of your app will have been deployed.

This code adds a new route to your app, /contacts, and configures the app to map a Ruby object Contact to a table in the Postgres database, salesforce.contact. When you navigate to the new route, it will grab all the records (Contact.all) and use a view template to display them (index.erb).

Navigate to your app’s domain on the web, then add /contacts to the URL so that the new code is invoked. For example, if your app is at https://foo-bar-1212.herokuapp.com/ then visit https://foo-bar-1212.herokuapp.com/contacts

You will now see the contacts listed:

In this step, you extended your Heroku application to interact with Heroku Postgres data. It’s all dynamic, so if you go and modify your Contact data in the connected Salesforce org, and then navigate to your new /contacts route, you’ll see the change (after the default sync period). Extending your app in other ways (adding, removing or editing records) is just as easy.

Scale the app

Right now, your app is running on a single web dyno. Think of a dyno as a lightweight container that runs the command specified in the Procfile. The container is managed by Heroku - including security updates to the operating system and the language interpreters and compilers.

You can check how many dynos are running on the “Resources” tab of your app detail page. In this example, we are running a single dyno:

By default, your app is deployed on a free dyno. Free dynos will sleep after a half hour of inactivity (if they don’t receive any traffic). This causes a delay of a few seconds for the first request upon waking. Subsequent requests will perform normally. Free dynos also consume from a monthly, account-level quota of free dyno hours - as long as the quota is not exhausted, all free apps can continue to run.

To avoid dyno sleeping, you can upgrade to a hobby or professional dyno type as described in the Dyno Types article. For example, if you migrate your app to a professional dyno, you can easily scale it by running a command telling Heroku to execute a specific number of dynos, each running your web process type.

Provision an add-on

Add-ons are third-party cloud services that provide out-of-the-box additional services for your application, from persistence through logging to monitoring and more. There are over 150 add-ons in the add-on marketplace.

The app you deployed already has two add-ons: Heroku Postgres and Heroku Connect.

The Heroku Postgres add-on provides a Postgres SQL database as a backing service - a way to store data outside of the running dynos. The Heroku Connect add-on provides sync capabilities between Heroku Postgres and a Salesforce org.

In this step, you will provision a logging add-on, which lets you view the application logs and set up alerts.

By default, Heroku stores 1500 lines of logs from your application. However, Heroku makes the full log stream available as a service, and several add-on providers have written logging services that provide things such as log persistence, search, and email and SMS.

In this step you will provision one of these logging add-ons, Papertrail.

Provision the papertrail logging add-on.

1. Select your app in Heroku Dashboard and click the Resources tab.
2. In the add-on section, click “Get more addons”.
3. In the search bar, type “papertrail” and then click the matching Papertrail add-on that is found. The Papertrail add-on page opens.
4. Scroll down to the Plans section.

To attach the add-on to your application:

1. Select your app name.
2. Click “Add Choklad for Free”, which provisions the free version of the add-on.

Navigate to the Resources tab of your app in Dashboard and click Papertrail in the Add-ons section. It will open the Papertrail web console, showing the latest log events. The interface lets you search and set up alerts.

To help with abuse prevention, provisioning an add-on requires account verification. If your account has not been verified, you will be directed to visit the verification site.

To see the add-on in action, navigate to your app on the web, refresh the page, and then navigate back to the Papertrail console to see the log messages. The logs of your visits to the app will be displayed in the Papertrail console.

In this step, you provisioned one of over 150 add-ons. These add-ons provide considerable value to your application - and make it very easy to extend your application with complex functionality with little developer effort.

Summary

In this tutorial you learned a lot about deploying and managing apps and data on Heroku, and connecting those apps to Salesforce orgs with Heroku Connect so that data can easily be synced between the app’s database and the org.

In particular, you learned that:

• Deploying apps to the web can be as simple as pushing a button
• The Heroku Dashboard provides a great interface for managing apps
• Scaling, horizontally or vertically, is easily accomplished
• It is easy to integrate your app deployment with other services, such as GitHub
• 150 add-ons are available—third party cloud services that you can provision with a click of a button in order to extend your app’s functionality
• Heroku Connect can be easily configured to sync data between a Salesforce Object and a Heroku Postgres table
• Heroku Postgres provides dataclips for creating public or privately shareable queries against your database
• Apps are at the core of the Heroku platform

Next steps

You now know how to deploy an app, change its configuration, view logs, scale, and attach add-ons.

Here is some recommended reading:

• Read How Heroku Works for a technical overview of the concepts you’ll encounter while writing, configuring, deploying and running applications.
• Read one of the Getting Started with Heroku guides to dive into the developer experience for a particular language.
• Read the Heroku Connect documentation to learn more about how the product works.
• See the Nibs Loyalty Program Sample App for a much larger sample app that uses Heroku Connect.