Integration Workbook
Integration Workbook
Integration Workbook
names and marks. Other marks appearing herein may be trademarks of their respective owners.
Table of Contents
Table of Contents
Force.com Integration Workbook.........................................................................................................1
Before You Begin.................................................................................................................................2
Tutorial #1: Create a New Heroku Application......................................................................................3
Step 1: Clone the Github Project..............................................................................................................................................3
Step 2: Create a Heroku Project................................................................................................................................................3
Step 3: Test the Application......................................................................................................................................................4
Summary...................................................................................................................................................................................5
Tutorial #2: Connecting the Warehouse App with an External Service ...................................................6
Step 1: Create an External ID Field on Invoice........................................................................................................................6
Step 2: Create a Remote Site Record........................................................................................................................................6
Step 3: Create an Integration Apex Class..................................................................................................................................7
Step 4: Test the @future Method..............................................................................................................................................9
Step 5: Create a Trigger to Call the @future Method...............................................................................................................9
Step 6: Test the Complete Integration Path...........................................................................................................................10
Summary.................................................................................................................................................................................11
Intended Audience
This workbook is intended for developers new to the Force.com platform but have basic working knowledge in Java.
Tell Me More....
This workbook is designed so that you can go through the steps as quickly as possible. At the end of some steps, there is an
optional Tell Me More section with supporting information.
You can find the latest version of this and other workbooks at developer.force.com/workbooks.
To learn more about Force.com and to access a rich set of resources, visit Developer Force at
http://developer.force.com.
Navigate to http://heroku.com.
Click Sign Up.
Enter your email address.
Wait a few minutes for the confirmation email and follow the steps included in the email.
Navigate to https://toolbelt.heroku.com/.
Select your development platform (Mac OS X, Windows, Debian/Ubuntu) if it isnt already auto-selected for you.
Click the download button.
After the download finishes, run the downloaded install package on your local workstation and follow the steps to install.
2. Execute the following command to login to Heroku (followed by Heroku login credentials, if necessary):
heroku login
Heroku creates a local git repository as well as a new repository on its hosting framework where you can push applications,
and adds the definition for that remote deployment for your local git repository to understand. This makes it easy to leverage
git for source control, make local edits and then deploy your application to the Heroku cloud.
3
All application names on Heroku must be unique, so youll see messages like the following when Heroku creates a new
app:
Creating quiet-planet-3215... done
Important: The output above shows that the new application name is quiet-planet-3215. You may want
to copy and paste the generated name into a text file or otherwise make a note of it. Throughout this workbook
there are references to the application name that look like {appname} that should be replaced with your application
name. So, if your application name is quiet-planet-3215, when a tutorial step prompts you to enter a URL
with the format https://{appname}.herokuapp.com/_auth, you would use:
https://quiet-planet-3215.herokuapp.com/_auth.
4. To deploy the local code to Heroku, execute the following command:
git push heroku master
The process will take a while as it copies files, grabs any required dependencies, compiles, and then deploys your application.
5. Once the process is complete, you can preview the existing application by executing:
heroku open
Tell Me More...
Look carefully as the git push happens and youll see some magic. Early on, Heroku detects that the push is a Spring MVC
app, so it installs Maven, builds the app, and then gets it running for you, all with just a single command.
Summary
5. In the browser URL bar, select the invoice record ID, which is everything after salesforce.com in the URL. It should
look something like a01E0000000diKc. Copy the ID to your clipboard.
6. Return to the browser window or tab showing your Heroku application.
7. Paste the invoice record ID into the field under Id.
8. Click Create. An order is created with the Invoice ID. Your page looks something like:
Summary
Herokus polyglot Platform as a Service design lets you easily deploy your applications with industry-standard tools, such as
git. Normally, teams would use local development environments, like Eclipse, and in fact Heroku has released an Eclipse
plugin for seamless integration with Eclipse. You can also interact with Heroku on the command line and directly access logs
and performance tools for your applications.
Tell Me More...
Just for fun, you can skip Step 2 and create and test the callout in Step 3 and Step 4 below to observe the error message that
is generated when an app attempts to callout to a URL without permission. Don't forget to come back and add the remote
site record, though!
This small snippet of Apex code retrieves the ID for a single invoice and calls your @future method using this ID.
3. Click the Open Log checkbox.
4. Click Execute. You should see two entries appear in the logs. Double click the second line it should have Future
Handler as its operation and a status of Success.
5. Click the Filter checkbox under the Execution Log and type DEBUG as the filter text. Scroll down and double click the
last line of the execution log. You should see a popup with the response from the fulfillment Web service that looks
something like:
08:08:42:962 USER_DEBUG [58]|DEBUG|Fulfillment service returned
[{"order_number":2,"id":"a01E0000009RpppIAC"}]
Now that you have a functional @future method that can call the fulfillment Web service, it's time to tie things together
with a trigger.
3. Click Save.
The comments in the code explain what is happening. In particular, understand that Force.com triggers must be able to handle
both single row and bulk updates because of the varying types of calls that can fire them (single row or bulk update calls). The
trigger creates a list of IDs of invoices that have been closed in this update, and then calls the @future method once, passing
the list of IDs.
The following screen shows the Invoices tab before any changes have been made:
10
Summary
The following screen shows the Invoices tab after the asynchronous call has returned the new order ID:
Summary
Congratulations! Your app is sending invoices for fulfillment. You have successfully created an asynchronous Apex class that
posted invoice details to your fulfillment app hosted on Heroku. Of course, your external application could reside anywhere
11
Summary
as long as you have access via Web services. Your class uses open standards including JSON and REST to transmit data, and
a trigger on Invoices to execute the process.
12
13
The detail page for your remote access configuration will display a consumer key as well as a consumer secret (which you have
to click to reveal). You'll need these in later steps.
3. You need to set your Remote Access keys to your Heroku application. Enter:
heroku config:add OAUTH_CLIENT_KEY=PUBLICKEY OAUTH_CLIENT_SECRET=PRIVATEKEY
Replace PUBLICKEY with the Consumer Key from your remote access application you defined in Step 1. Similarly,
replace PRIVATEKEY with the Consumer Secret. It may be helpful to do this in a text editor before putting it on the
command line.
4. Execute the following command to push the local changes to Heroku:
git push heroku master
5. In a browser tab or window, navigate to https://{appname}.herokuapp.com to see the changes (refresh your browser
if needed).
14
By adding an OAuth flow to your app, your app can get a users permission to have session information without requiring the
third-party server to handle the users credentials. With this added to the project, the fulfillment application can use the
Force.com REST API to access information directly from the users instance.
Tell Me More...
You can review all of the changes brought in by this branch on github at:
https://github.com/sbob-sfdc/spring-mvc-fulfillment-base/compare/master...full. Notice that the
changes use the Force.com REST API to manipulate Invoice records. Look at InvoiceServiceImpl.java in particular
to see how it creates, queries, retrieves and deletes invoices. This tutorial only uses the findOrder() method. The others
add:
<h3>Invoice</h3>
<p>Number: <c:out value="${invoice.number}"/></p>
<p>Status: <c:out value="${invoice.status}"/></p>
7. Wait for the push to finish, and navigate to your fulfillment app in the browser (refreshing if necessary) to see the changes.
Notice that, given an ID, this code retrieves the corresponding invoice record. Because there might be mock ID's in the
database that are not in Force.com, the app handles the corresponding exception by showing default data. Adding the invoice
to the model makes it available to the view. Now when you test the fulfillment application, it will show the invoice information
currently in your Force.com instance by grabbing the information via the REST API using the record ID. Your order detail
page might look something like:
15
Summary
Tell Me More...
To really see the application in motion, you can edit information on Force.com (like the Description of the Invoice) and
see it represented the next time you load that order in your Heroku app.
Notice that the Web service call from Force.com to create orders is not secured. Securing this call goes beyond the scope of
this workbook, but a simple solution would be to set up a shared secret between the Force.com app and the fulfillment app.
The Force.com app would create an HMAC of the parameters in the request, using the secret, and the fulfillment app would
verify the HMAC.
Summary
Congratulations! With a combination of OAuth authentication, the REST API, Apex triggers, @future callouts and the
polyglot framework of the Heroku platform you have created and deployed a bi-directional integration between two clouds.
This workbook touches upon just one example of the many ways to integrate your applications with Salesforce. One integration
technology not touched upon in this workbook is the Streaming API that lets your application receive notifications from
Force.com whenever a user changes Salesforce data. You could use this in the fulfillment application to monitor when the
user updates invoices and automatically update the application pages accordingly. Make sure to visit
http://developer.force.com to learn more about all the different ways you can integrate your application with Force.com.
16