• Introduction
• Getting Credentials
• Using the Code
• How it works
• More Information

Introduction

This channel shows a the usage of a salesforce.com adapter for Iguana. This example allows you to connect to a salesforce.com account, and can be easily be adapted to your own requirements.

Internally we use salesforce.com for our customer relationship management system (CRM). We use this adapter with Iguana to perform all the integrations we have with salesforce.com and other applications used to run our internal operations.

The salesforce.com adapter is also an example of best practices when developing your own adapter for your own web API through the techniques it illustrates.

If you have any questions please contact us at support@interfaceware.com.

Getting Credentials [top]

To access the salesforce.com API you have to set up a salesforce.com application and use it to obtain values for the following:

• consumer_key
• consumer_secret

The adapter uses the simple password based authentication technique. This works fine as a method of authenticating an internal integration rather than trying to publish an application in the salesforce.com application store.

Salesforce.com does support some ways to make an application like connection to it such that the user grants permission only to specific resources via the OAuth protocol. This adapter uses the simple password based authentication technique. If you need to use a different authentication mechanism then please contact us at support@interfaceware.com.

The screens in the current form of salesforce.com may vary but the workflow should be similar.

If you do not have a pre-existing salesforce.com account set up you can set up a free developer account. Go to: https://developer.salesforce.com/signup for the signup:

1. Authenticate your email address, using the initial screen:
2. Click the link in the confirmation email to open the Getting Started screen.
3. Salesforce have changed to a new “Lightning Experience Interface” with different looking screens, though the same functions are still available. You can choose Salesforce Classic for screens that are similar to the screenshots below.
   • Click your profile icon at the top right of the screen and choose Switch to Salesforce Classic option:
     
4. You may need to switch to the Setup home page:
   • Click Setup on the top right of the Salesforce Classic interface – you should see the setup page similar to step 6 below:
     
     
   • Or choose Setup from the Gear menu on the top right in the new interface – the setup page will look different but works similarly:
     
   • You can use Quick Find in the left column to find things like “Oauth” for example:
     
5. Open the Administer>Security Controls>OAuth and OpenID Connect Settings and enable Allow OAuth Username-Password Flows:
   
   
6. Expand the Create option in the Build menu at the lower left, then click on Create>Apps:
   
7. Click on the New button for Connected Apps at the bottom center of the page:
   
8. Fill out the first two sections only, Basic Information and API (Enable OAuth Settings).
   • Use similar information to that shown below.
   • Notice the dummy “Callback URL”? The screen requires it even though we are not actually using the OAuth callback URL in this adapter.
     Note: You need to use a secure URL “https://” rather than “http://”
   • I selected full access for the adapter to make development easier (you can add restrictions later).
   • When you have filled out the fields, click the Save button at the top of the form.
     
9. Click on the Continue button, in the New Connected App screen:
   
10. Now we need to relax the IP restrictions on who can connect to the API.
    • Click the Manage button, to manage your app:
      

      Tip: If you went exploring after point 6, and got lost trying to get back the page with the Manage button (like I did).

      Then do the following to manage your app: Click the Setup link (top right on all screens), choose Build>Create>Apps from the menu at the left bottom of the screen, then click on the Manage link to manage your app.
      
      
      You can can also click the Connected App Name link to get back to the exact same screen with the [Edit], [Delete] and [Manage] buttons.
      

      Alternatively: Go to the list in Administer>Manage Apps>Connected Apps and click on the Master Label link which takes you directly to the Manage screen for the App.
      

    • Click the Edit button so we can change the “IP Relaxation:” setting:
      
    • Select Relax IP restrictions from the drop down, then click Save:
      
11. We’re almost done. The last thing to do is to get the “consumer key” and “consumer secret” – our prize!
    • Click the the Back to List: Custom Apps link:
      
    • Then click on the link for your App in the Connected Apps panel at the bottom of the page:
      

      Tip: If you get lost trying to find the above page (like I did), do the following: Click the Setup link (top right on all screens), the choose Build>Create>Apps from the menu at the left bottom of the screen.
      
      

      Note: There is a similar list in Administer>Manage Apps>Connected Apps but this link in this list takes you to the wrong place (i.e., the Manage page not the Apps page).

    • By default the consumer secret is hidden, just Click to reveal as suggested:
      
    • Now you can see the Consumer Key and the Consumer Secret, we will need both of these to connect to Salesforce:
      

So at this point we have what we need – the consumer_key and consumer_secret. This is what we need to plugin to our adapter.

Using the Code [top]

• Import the Salesforce.com Adapter channel from the CS team iguana-channels repository
• The salesforce adapter module uses require to return a single function which is used to create a salesforce connector. Also because it uses the net.http.cache module it does modify the global namespace by adding caching to the built in net.http.* calls
• The channel makes use of the encrypt.password module to avoid the need to hard code the credentials for salesforce.com in the channel
• Use the SalesforceConnect{} function to create an salesforce.com connection
• You will need to setup the channel to use your consumer_key and consumer_secret:
  • The first step to make the code work is to uncomment each line for each of the values for:
    • Username
    • Password
    • consumer_key
    • consumer_secret
  • Enter the real value for each item
  • Re-comment out the line
  • Remove the real value – don’t forget this step – the idea here is to avoid saving your credentials within the channel source code and in the GIT repo for the Iguana instance
  • At this point the example should work
• Interactive scripting help is included for this module

This is the github code for the main module:

How it works [top]

The adapter is using a number of techniques to generate the salesforce API. There are two documents which go into detail explaining the design of the adapter and how it is implemented:

1. The original salesforce.com adapter (Iguana 5 documentation) article.
2. The Mk II salesforce.com adapter explains further enhancements which we in this version of the adapter.

These are recommended reading especially if you would like to develop a similar adapter for your own application.

There are two examples given in the channel. One example is fetching a list of users, the other is creating and deleting an account for an imaginary company.

The ShowUsers file shows querying the salesforce users and generates a list of them.

The MakeJiffyAccount shows using a WHERE clause to query for a specific record in sales force. The code tries to find the account called “Jiffy Dry Cleaning”. If it can find it then it update that account. If not we create a new empty account record.

The next screen shot shows how nice the annotations are with this adapter. The call to accountModify has the “live” flag set to true to indicate that the action will be run live within the editor:

To make sure the code will work with a generic instance of salesforce we avoid using custom fields in the example. However the adapter picks them up no problem. We keep the __c postfix to keep the interface similar to what salesforce.com displays within it’s own API. This screenshot shows the Account record with empty columns displayed:

The salesforce.com data module is very large. By default the adapter only generates methods for some of the main objects. This screenshot shows a few of the methods – as you can see auto-completion makes the adapter very convenient to use:

If we need objects that are not included in the default it is easy to add them. Just edit the list parsed into the objects value in the function used to make the connector to salesforce. The valid names for salesforce objects are documented on the salesforce website:

https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_list.htm

This screen shot highlights the relevant part of the code to alter:

The adapter will automatically generate the apis required to handle each object type. This is about it for what you need to know to use the salesforce adapter. The adapter makes it possible to implement both simple and very complex integrations with salesforce.

More information [top]

• Source code for the main module on github
• Source code for the salesforce.lua module on github
• Source code for the store2.lua module on github
• The store2 module documentation.
• The encrypt.password module documentation
• The http caching module documentation
• Mk II salesforce.com adapter article
• List of objects in salesforce.com