Connecting to the Salesforce REST APIs with Spring Boot and Java

Broadly speaking there are two types of integrations with Salesforce, either a system-to-system integration or a user interface integration. One of the primary ways to do these integrations is by using the Salesforce REST API. When using the Salesforce REST API you need to obtain an access token that identifies who is making the requests. OAuth 2 provides an HTTP interface to obtain a Salesforce access token.

When using the Salesforce OAuth 2 API there are three options for obtaining an access token:

  1. Use the Web Server Flow where a Salesforce user in a traditional web app is asked to authorize a third party application which then allows the web server to obtain an access token.
  2. Use the User Agent Flow where a Salesforce user in a mobile or JavaScript web app is asked to authorize a third party application which then allows the client side application (native mobile, JavaScript, etc) to obtain an access token.
  3. Use the Username and Password Flow where stored credentials for a system-to-system integration user are exchanged for an access token.

The OAuth Web Server Flow can seem tricky to implement by hand because there are a number of necessary steps but luckily this flow is pretty standard so many libraries have done the hard work for us. In the case of a Java Spring application the hard work has all been done by the Spring Security OAuth library. And Spring Boot makes it super easy to setup a new application that has everything needed for the OAuth Web Server Flow.

Let’s walk through the different pieces of a simple web application which has the OAuth stuff, fetches Accounts from the Salesforce REST API, and renders them in a web page via JavaScript. (Note: You can skip straight to the completed project if you just want to deploy the app on Heroku or get it all running locally.)

First we need a build system to manage dependencies, run the app, and assemble the app for deployment. I’ve chosen Gradle so here is my build.gradle:

buildscript {
    repositories {
        mavenLocal()
        mavenCentral()
        maven {
            url 'https://plugins.gradle.org/m2/'
        }
    }
    dependencies {
        classpath 'org.springframework.boot:spring-boot-gradle-plugin:1.4.2.RELEASE'
    }
}
 
apply plugin: 'java'
apply plugin: 'org.springframework.boot'
 
repositories {
    mavenLocal()
    mavenCentral()
}
 
dependencies {
    compile 'org.springframework.boot:spring-boot-starter-web:1.4.2.RELEASE'
    compile 'org.springframework.boot:spring-boot-devtools:1.4.2.RELEASE'
    compile 'org.springframework.boot:spring-boot-starter-security:1.4.2.RELEASE'
    compile 'org.springframework.security.oauth:spring-security-oauth2:2.0.12.RELEASE'
    compile 'org.webjars:salesforce-lightning-design-system:2.1.4'
    compile 'org.webjars:jquery:3.1.1'
}

There you can see dependencies on the Spring Boot stuff, the Spring Security OAuth library and a few WebJars for the UI.

Now we need to set some properties for the Spring Security stuff. There are a few different ways to set these and you should make sure that your OAuth client id and secret don’t end up in SCM. At a minimum you will need these settings:

security.oauth2.client.client-authentication-scheme = form
security.oauth2.client.authentication-scheme = header
security.oauth2.client.grant-type = authorization_code
security.oauth2.client.access-token-uri = https://login.salesforce.com/services/oauth2/token
security.oauth2.client.user-authorization-uri = https://login.salesforce.com/services/oauth2/authorize
security.oauth2.resource.user-info-uri = https://login.salesforce.com/services/oauth2/userinfo
security.oauth2.client.client-id = YOUR_SALESFORCE_CONNECTED_APP_CLIENT_ID
security.oauth2.client.client-secret = YOUR_SALESFORCE_CONNECTED_APP_CLIENT_SECRET

I put all of the settings except the client id and secret in a src/main/resources/application.properties file. For the other settings you can use environment variables or config settings on Heroku. Spring Boot automatically will look for the client id and secret in environment variables named SECURITY_OAUTH2_CLIENT_CLIENT_ID and SECURITY_OAUTH2_CLIENT_CLIENT_SECRET.

Next we need a Spring component that will handle the REST communication with Salesforce including the query for Accounts and deserialization from JSON. Here is my src/main/java/com/example/Force.java code:

package com.example;
 
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.security.oauth2.client.OAuth2ClientContext;
import org.springframework.security.oauth2.client.OAuth2RestTemplate;
import org.springframework.security.oauth2.client.resource.OAuth2ProtectedResourceDetails;
import org.springframework.security.oauth2.provider.OAuth2Authentication;
import org.springframework.stereotype.Component;
 
import java.util.HashMap;
import java.util.List;
import java.util.Map;
 
@Component
public class Force {
 
    private static final String REST_VERSION = "35.0";
 
    @Bean
    private OAuth2RestTemplate oAuth2RestTemplate(OAuth2ProtectedResourceDetails resource, OAuth2ClientContext context) {
        return new OAuth2RestTemplate(resource, context);
    }
 
    @Autowired
    private OAuth2RestTemplate restTemplate;
 
    @SuppressWarnings("unchecked")
    private static String restUrl(OAuth2Authentication principal) {
        HashMap<String, Object> details = (HashMap<String, Object>) principal.getUserAuthentication().getDetails();
        HashMap<String, String> urls = (HashMap<String, String>) details.get("urls");
        return urls.get("rest").replace("{version}", REST_VERSION);
    }
 
    public List<Account> accounts(OAuth2Authentication principal) {
        String url = restUrl(principal) + "query/?q={q}";
 
        Map<String, String> params = new HashMap<>();
        params.put("q", "SELECT Id, Name, Type, Industry, Rating FROM Account");
 
        return restTemplate.getForObject(url, QueryResultAccount.class, params).records;
    }
 
    @JsonIgnoreProperties(ignoreUnknown = true)
    public static class Account {
        public String Id;
        public String Name;
        public String Industry;
        public String Rating;
    }
 
    @JsonIgnoreProperties(ignoreUnknown = true)
    private static class QueryResult<T> {
        public List<T> records;
    }
 
    private static class QueryResultAccount extends QueryResult<Account> {}
 
}

There is some plumbing to setup the Spring REST Template which makes it easy to make the REST requests. The accounts method takes an OAuth2Authentication so that the URL can be determined. Finally there are some classes to represent the results from the query and the Account, which are created from the JSON data returned from the REST API.

For Spring Boot we need an application which will be run on the web server (or local machine for development). In this example the application will also contain our REST API implementation which will be used by a JavaScript UI. Here is the code for the src/main/java/com/example/SpringSalesforceApplication.java file:

package com.example;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.security.oauth2.client.EnableOAuth2Sso;
import org.springframework.security.oauth2.provider.OAuth2Authentication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
 
import java.util.List;
 
@SpringBootApplication
@RestController
@EnableOAuth2Sso
public class SpringSalesforceApplication {
 
    @Autowired
    private Force force;
 
    @RequestMapping("/accounts")
    public List<Force.Account> accounts(OAuth2Authentication principal) {
        return force.accounts(principal);
    }
 
    public static void main(String[] args) {
        SpringApplication.run(SpringSalesforceApplication.class, args);
    }
 
}

This does all the magic to create a Spring Boot web application which uses the Spring Security OAuth stuff, the Force component, and a REST controller. There is a single REST controller method in this application that handles requests to /accounts, does the query to Salesforce using the Force component, deserializes the results, then reserializes them as JSON. In this little example we aren’t seeing why we’d want to proxy the Salesforce REST API in this way since we are not doing any aggregation or transformation of data. But that would be straightforward to do if needed.

The final piece of this application is a web UI that uses the Spring Boot app’s /accounts REST method to get and then display the accounts. In this case I’m using jQuery to do that. Here is the code for the src/main/resources/static/index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
 
    <title>Hello Spring Salesforce</title>
 
    <link rel="stylesheet" type="text/css" href="webjars/salesforce-lightning-design-system/2.1.4/assets/styles/salesforce-lightning-design-system.min.css"/>
 
    <script type="text/javascript" src="webjars/jquery/3.1.1/jquery.min.js"></script>
    <script>
        $(function() {
          $.get("/accounts", function(data) {
            $("tbody").empty();
            $.each(data, function(i, account) {
              var tr = $("<tr>");
              tr.append($("<td>").text(account.Id));
              tr.append($("<td>").text(account.Name));
              tr.append($("<td>").text(account.Industry));
              tr.append($("<td>").text(account.Rating));
              $("tbody").append(tr);
            });
          });
        });
    </script>
</head>
<body>
    <header class="slds-global-header_container">
        <div class="slds-global-header slds-grid slds-grid--align-spread">
            <div class="slds-global-header__item">
                <div class="slds-text-heading--large">Hello Spring Salesforce</div>
            </div>
        </div>
    </header>
 
    <div class="slds-container--center slds-container--medium" style="margin-top: 60px;">
        <div class="slds-text-heading--medium">Salesforce Accounts</div>
 
        <table class="slds-table slds-table--bordered slds-table--cell-buffer">
            <thead>
                <tr class="slds-text-title--caps">
                    <th scope="col">
                        <div class="slds-truncate" title="Id">Id</div>
                    </th>
                    <th scope="col">
                        <div class="slds-truncate" title="Id">Name</div>
                    </th>
                    <th scope="col">
                        <div class="slds-truncate" title="Id">Industry</div>
                    </th>
                    <th scope="col">
                        <div class="slds-truncate" title="Id">Rating</div>
                    </th>
                </tr>
            </thead>
            <tbody>
            </tbody>
        </table>
    </div>
</body>
</html>

With this application running locally when I visit http://localhost:8080 in my browser, Spring Security notices that I don’t yet have an access token so it walks through the OAuth Web Server Flow with Salesforce and once complete renders the index.html page. The JavaScript on that page makes the REST request to /accounts which does the query to the Salesforce REST APIs and then returns the JSON back to the browser. Finally, the data is rendered in the table on the web page. Here is what it looks like:

In total there were only five pretty small files needed to have an end-to-end Salesforce REST API integration with a web application. Hopefully that gets you started! For full instructions on Heroku deployment of this application or to get the app running locally, check out the complete project on GitHub.

Let me know how it goes!

Quick & Easy ETL from Salesforce to MySQL with Workflow & Heroku

While sometimes unfortunate it is often necessary to have data silos that share data. The Extract, Transform, and Load (ETL) pattern has been around for a long time to address this need and there are tons of solutions out there. If you just need a quick and easy way to copy new & updated records in Salesforce to an external data source, a simple Heroku app and Salesforce Workflow might be the quickest and easiest solution. I’ve put together a sample Node.js application for this: https://github.com/jamesward/salesforce-etl-mysql

Check out a demo:

This sample app uses a Salesforce Workflow that sends created and updated Contact records to an app on Heroku, which inserts or updates those records in a MySQL database. A simple transform JavaScript function makes it easy to customize this app for your own use case. To setup this app for your own uses, check out the instructions in the GitHub repo: https://github.com/jamesward/salesforce-etl-mysql

Let me know how it goes!

Pulling Go Code Colorado Data into Salesforce

This weekend I’m at the Go Code Colorado Challenge Weekend event in Durango. The purpose of Go Code Colorado 2016 is for teams to build something useful for businesses using one or more of the Colorado Public Datasets. Some teams are using Salesforce for the back-office / business process side of the app they are building. So I decided to see if I could pull a Colorado Public Dataset into Salesforce. Turns out it’s super easy! Just follow these steps:

  1. Sign up for a Salesforce Developer Edition
  2. Create a new External Data Source with the following field values:

    External Data Source = Colorado Public Data
    Name = Colorado_Public_Data
    Type = Lightning Connect: OData 2.0
    URL = https://data.colorado.gov/OData.svc
    Special Compatibility = Socrata

    new_external_data_source

  3. Save the new External Data Source and then hit “Validate and Sync” to fetch the metadata for the services.
  4. Select one or more tables from the list. A good table to test with is the “Occupational Employment Statistics” dataset.
    validate_and_sync
    Sync the table and you should see a new “External Object” in the list of External Objects.
    external_objects
  5. The data is now available in Salesforce. An easy way to see the dataset is to create a tab in the Salesforce UI. On the Custom Tabs Setup page create a new Custom Object Tab for the “Occupational Employment Statistics” object and select a Tab Style:
    new_custom_object_tab
    Complete the creation of the tab (select Next, Next, Save).
  6. Select the “Occupational Employment Statistics” tab (which might be in a drop-down menu depending on the width of your browser:
    custom_tabs
    Next to the View – All selector, hit “Go!” to fetch the data from the Colorado Public Data source. You’ll now see the records:
    records
    Note: The columns displayed in this view can be customized in the External Object’s Search Layout.
    Selecting a record’s ID will display the record details:
    record_details

That’s it! Now you can build all sorts of business processes and other employee-facing interactions around the public data.

Good luck to all of the Go Code Colorado teams!

Quick Force Java – Getting Started with Salesforce REST in Java

Recently I blogged about a toolchain that quickly gets you going with the Salesforce REST APIs. I believe developers should be able to get started with new technologies without having to install tons of stuff and struggle for days. That blog used Quick Force Node for those who want to use JavaScript / Node.js. I’ve had a number of requests for a Java version of this toolchain so I created Quick Force Java.

Check out a screencast that shows how to start with nothing, deploy a Salesforce REST app on Heroku, setup OAuth, setup a local dev environment, make & test changes to the app, and then deploy those changes back to the cloud (all in under 12 minutes):

Try out Quick Force Java and let me know how it goes!

Salesforce REST APIs – From Zero to Cloud to Local Dev in Minutes

When getting acquainted with new technologies I believe that users shouldn’t have to spend more than 15 minutes getting something simple up and running. I wanted to apply this idea to building an app on the Salesforce REST APIs so I built Quick Force (Node). In about 12 minutes you can deploy a Node.js app on Heroku that uses the Salesforce REST APIs, setup OAuth, then pull the app down to your local machine, make and test changes, and then redeploy those changes. Check out a video walkthrough:

Ok, now give it a try yourself by following the instructions in Quick Force (Node)!

I hope this will be the quickest and easiest way you’ve gotten started with the Salesforce REST APIs. Let me know how it goes!

FYI: This *should* work on Windows but I haven’t tested it there yet. So if you have any problems please let me know.

Dreamforce 2015 Video: Tour of Heroku + Salesforce Integration Methods

This year at Dreamforce I presented a session that walked through a few of the ways to integrate Heroku apps with Salesforce. Here is the session description:

Combining customer-facing apps on Heroku with employee-facing apps on Salesforce enables a whole new generation of connected and intelligent experiences. There are four primary ways to do this integration: Heroku Connect, Canvas, Apex / Process Callouts, and the Salesforce REST APIs. Using code and architectural examples, we’ll walk through these different methods. You will walk away knowing when you should use each and how to use them.

Check out the video recording of the session.

To dive into these methods here are the “Further Learning” resources for each method:

I hope this is helpful. Let me know if you have any questions.

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!

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.