Monday, April 14, 2014

Integrate External App with Salesforce using Canvas API

If you are using Salesforce extensively and also other internal/external applications to aggregate all the information to take a decision, Salesforce's Canvas API is one of the best ways to ensure, your people have all the data available at their disposal in a single interface rather juggling with several systems and arrive at a decision. 
Force.com Canvas is a mechanism for consuming third-party applications within Salesforce. Its goal is to connect applications at a UI level instead of just an API level

A little background... 
Canvas framework is a set of tools and JavaScript APIs that can be used to expose an application (written in virtually ANY language) as a canvas app. This means you can take your new or existing applications and make them available to your users as part of their Salesforce experience. However, the external application needs to follow two guidelines:
1. It must be a web application.
2. It must be https compliant.


External App embedded within Salesforce using Canvas
Fig: External App embedded within Salesforce using Canvas

Setup
To start you would need following: 
1. Access to Developer Edition organization: If you are not already a member of the Force.com developer community, go to http://developer.force.com/join and follow the instructions for signing up for a Developer Edition organization.
2. Get Force.com Canvas SDK: Get the Canvas SDK by going to https://github.com/forcedotcom/SalesforceCanvasFrameworkSDK and clone the project by clicking Zip and downloading the .zip file.
  • Extract all the files from the zip file locally into a directory called c:\SalesforceCanvasFrameworkSDK. Alternatively, you can download the project by using the Git command line and issuing this command: git clone git@github.com:forcedotcom/SalesforceCanvasFrameworkSDK.git.
  • Open a command window and navigate to c:\SalesforceCanvasFrameworkSDK
  • Enter the command git submodule init.
  • Enter the command git submodule update. This adds other projects into the current project. The file c:\SalesforceCanvasFrameworkSDK\.gitmodules shows you which projects are included as submodules.
  • After you clone the project, the c:\SalesforceCanvasFrameworkSDK directory should contain a subdirectory named src, as well as files like pom.xml and README.md.
3. A Heroku account: Go here to create a Heroku account: https://api.heroku.com/signup.

Get Started
Step 1 : Create the App on Heroku
  • Canvas SDK downloaded from github comes with a sample code which can be integrated with Salesforce using Canvas API. This code we will deploy on heroku and then will integrate with Salesforce.
  • If you haven’t already, log into Heroku and install Heroku Toolbelt.
  • Open a command window, navigate to c:\SalesforceCanvasFrameworkSDK, and enter the following command: git init. This re-initializes the directory as a Git repository.
  • Enter heroku create command in command window. This will create a new app on heroku. The console will show the name of the app created. For our blog, lets consider the name as princess-castle-2824.herokuapp.com
  • Add the entire SalesforceCanvasFrameworkSDK into heroku's git repository by firing the command git add -A
  • Commit the code using the command: git commit -m "Checking Comments"
  • Deploy the code onto heroku dyno using command: git push heroku master
  • Access the app at url https://princess-castle-2824.herokuapp.com/examples/hello-world/index.jsp. You should see a message that says, “This App must be invoked via a signed request!” This is an indication that the app is running in Heroku. This message appears because the app is designed to receive a signed request from Salesforce, therefore, the app won’t run outside of the Salesforce canvas environment.

Step 2 : Create the Canvas App in Salesforce
Now we have a web app running on https. This is a pre-requisite for integrating with Salesforce using Canvas. Below steps needs to be followed to create a canvas app in Salesforce:
  • In Salesforce, from Setup, click Create | Apps.
  • In the Connected Apps related list, click New.
  • In the Connected App Name field, enter Hello World.
  • Accept the default API Name of Hello_World. This is the internal name of the canvas app and can’t be changed after you save it.
  • In the Contact Email field, enter your email address.
  • In the Logo Image URL field, enter https://princess-castle-2824.herokuapp.com/images/salesforce.png. This is the default salesforce.com “No Software” image. This image appears on the installation screen and on the detail screen for the app.
  • In the Icon URL field, enter https://princess-castle-2824.herokuapp.com/examples/hello-world/logo.png. This is the default salesforce.com “No Software” image.
  • This is the image that appears next to the app name in the user interface. If you leave this field blank, a default cloud image appears next to the app name.
  • In the API (Enable OAuth Settings) section, select the Enable OAuth Settings field.
  • In the Callback URL field, enter https://princess-castle-2824.herokuapp.com/sdk/callback.html.
  • In the Selected OAuth Scopes field, select Access your basic information.
  • In the Canvas App Settings section, select Force.com Canvas.
  • In the Canvas App URL field, enter https://princess-castle-2824.herokuapp.com/examples/hello-world/index.jsp.
  • In the Access Method field, select Signed Request (Post).
  • In the Locations field, select Chatter Tab.
  • Click Save. After the canvas app is saved, the detail page appears.
  • On the detail page for the canvas app, next to the Consumer Secret field, click the link Click to reveal. The consumer secret is used in the app to authenticate.
  • Copy the customer secret value into the index.jsp on line String yourConsumerSecret="4888155445018149063";
  • Checkin and Redeploy the updated index.jsp on heroku dyno.

   Step 3 : Grant access rights to Canvas App in Salesforce
  • In Salesforce, from Setup, click Manage Apps | Connected Apps.
  • Click the Hello World app, and then Edit.
  • In the Permitted Users field, select Admin approved users are pre-authorized. Click OK on the pop-up message that appears.
  • Click Save. This is where you define who can see your canvas app. This can be done using profiles and permission sets. In this example, we assume that your profile is System Administrator.
  • In the Profiles related list, click Manage Profiles.
  • Select the System Administrator profile and click Save.
  • In Salesforce, from Setup, click Canvas App Previewer. You can use the Canvas App Previewer to test out your canvas app before publishing it.
  • Click the Hello World link on the left. The app appears and you’ll see the message Hello User.FullName. The canvas app works in this context because when you click the app name in the previewer, the signed request is sent to the endpoint https://princess-castle-2824.herokuapp.com/examples/hello-world/index.jsp
  • After configuring access, you can see the canvas app in the Canvas App Previewer and on the Chatter tab in your development organization.
   
Step 4 :  Query data from Salesforce and display on the page
Now let's try to access data from Salesforce and present it on our page index.jsp  which     is currently displaying logged in username. Below steps will pull data from leads tab of         Salesforce and present it on our page.
  • Update Sfdc.canvas() javascript function as below. This function forms a query url to fetch leads data from salesforce and construct a html to present on the page.
  • Sfdc.canvas(function() {
       var sr = JSON.parse('<%=signedRequestJson%>');
       // Save the token
       Sfdc.canvas.oauth.token(sr.oauthToken);
       Sfdc.canvas.byId('username').innerHTML = sr.context.user.fullName;
                
       //Prepare a query url to query leads data from Salesforce
       var queryUrl = sr.context.links.queryUrl+"?q=SELECT+id+,+name+,+company+,+phone+from+Lead";
                
       //Retrieve data using Ajax call
       Sfdc.canvas.client.ajax(queryUrl, {client : sr.client,
                     method: "GET",
                     contentType: "application/json",
                     success : function(data){
                        var returnedLeads = data.payload.records;
                        var optionStr = '<table border="1"><tr><th></th><th>Id</th><th>Name</th><th>Company</th><th>Phone</th></tr>';
                        for (var leadPos=0; leadPos < returnedLeads.length; leadPos = leadPos + 1) {
                          optionStr = optionStr + '<tr><td><input type="checkbox" onclick="setCheckedValues(\''+returnedLeads[leadPos].Name+'\',\''+returnedLeads[leadPos].Phone+'\');" name="checkedLeads" value="'+returnedLeads[leadPos].Id+'"></td><td>'+ returnedLeads[leadPos].Id + '</td><td>' + returnedLeads[leadPos].Name + '</td><td>' + returnedLeads[leadPos].Company + '</td><td>' + returnedLeads[leadPos].Phone + '</td></tr>';
                       } //end for
                       leadStr=leadStr+'</table>';
           
                       Sfdc.canvas.byId('leaddetails').innerHTML = leadStr;
                     }}); //end success callback
       });  //end ajax call
    
    
    
  • Create a leaddetails html element. The above JS function, after constructing lead data into html, displays it in span.
  • Deploy this changes to heroku.
  • Access our canvas app from Chatter tab in Salesforce and leads data will be displayed as below in index.jsp.
  • Fig: Leads queried from Salesforce displayed on Hello World page 
Final round up...
Canvas API turns out to be a very powerful tool which provides a seamless access to external application maintaining high quality user experience. For example, a company has Java/Spring applications running inside a Tomcat web server. Without touching existing code, one can mesh it up, simply through adding CSS layout / Javascript files and provide access within Salesforce.

5 comments:

  1. I tried this idea for salesforce to salesforce integration using canvas app but no luck. Can you suggest on it?

    ReplyDelete
  2. Hi Dharmveer, I implemented everything as mentioned above...but i am getting error at step:3 at this line "Click the Hello World link on the left. The app appears and you’ll see the message Hello User.FullName" as HTTP ERROR 500

    Problem accessing /examples/hello-world/index.jsp. Reason:

    secret is null, did you set your environment variable CANVAS_CONSUMER_SECRET?

    Please help me where exactly i done a mistake

    ReplyDelete
    Replies
    1. This comment has been removed by the author.

      Delete
    2. Hi Kiran,
      You got to set the consumer secret. There are many ways of doing that. However the easiest way is to add a Config Variables in Heroku.

      CANVAS_CONSUMER_SECRET= ***********************

      Delete
  3. Hello, I want to send data like opportunity id from salesforce canvas app to heroku node js application. How can i do this?

    ReplyDelete