Salesforce Via Jive Connects

Version 2

    Introduction

    This document describes the steps required to set up a Jive Connects service entry for the SalesForce.com REST API, and access it in a Jive application.

     

    Setup Steps

     

    Before you can establish a connection, you need some setup:

    • Set up an account at SalesForce's developer site (http://developer.force.com)
    • App Setup under Build > Create > Apps > Connected Apps.
    • Click the New button
    • Create a new "Remote Access" application entry.  At a minimum, you'll need the application name and a callback URL that should be your Jive instance's SSL URL, followed by "/api/connects/v1/oauth2/access".  For me, the entire URL becomes "https://craig.example.com/api/connects/v1/oauth2/access".
      • That's right ... SFDC goes beyond the OAuth spec and requires that the callback URL use SSL (and it also has to match exactly, instead of being just a prefix).
    • Note the Consumer Key and Consumer Secret assigned to you by SalesForce; you'll need them to configure the service below.

     

    Now, go to the admin console of your Jive instance (System --> Settings --> App Services, although this will change soon), and click New App Service.  Enter the following values:

    • Name -- SalesForce.Com (or whatever you want)
    • Authorization -- OAuth 2.0 (Draft 10) -- this will trigger display of five additional properties specific to OAuth 2.0.
    • Client ID -- the Consumer Key assigned by SalesForce.
    • Client Secret -- the Consumer Secret assigned by SalesForce.
    • Authorization Scope -- not required for SalesForce.
    • Authentication URL -- https://login.salesforce.com/services/oauth2/authorize
    • Access Token URL -- https://login.salesforce.com/services/oauth2/token
    • Redirect Base URL -- an SSL URL pointing to your Jive instance.  This must match the first part of the Callback URL that you entered at SalesForce when registering.
    • Tags -- jive:service://salesforce.com/api?version=1
    • Service URL -- https://login.salesforce.com

     

    Finally, in your application, declare that you need the Jive Connects feature, configured for a connection to the SalesForce REST API.  This is done by including the following snippet in your app.xml file:

     

            <Require feature="jive-connects-v1">             <Param name="alias:salesforce|title:Salesforce.Com REST API">jive:service://salesforce.com/api?version=1</Param>         </Require>

     

    Two example applications that use a connection like this is in our GitHub examples repository at:

     

    Initial Execution

    The first time you actually run such an application, Jive Connects will kick off the usual 3-legged OAuth dance:

    • A new window will be opened by SalesForce itself (via browser redirect).
    • If you are not currently logged in to SalesForce in this browser, you will be asked to do so.
    • You will be asked to grant access permission for the application you just set up (which basically represents your Jive instance).
    • The window will close and the app will display some sample account data from the database in your developer sandbox account.

     

    Subsequently, the access token that was returned by SalesForce (and stored for you in the Credentials Vault) will be used on subsequent requests.

     

    Programming Notes

    The SalesForce API does a nice job of obeying the "hypermedia constraint" of REST by always including URIs that point to various resources.  The interesting thing to note is that these URIs are relative to the server that SalesForce pointed you to (which is, again, outside the OAuth spec ... but Jive Connects handles this for you).  This just happens to be exactly the value you would pass in as the "href" parameter on the Jive Connects calls to get or post data.

     

    Good starting point for documentation on the SalesForce REST API:

    http://developer.force.com/REST

    API Reference is at:

     

     

    http://wiki.developerforce.com/images/c/c9/Api_rest.pdf