Salesforce

This is a short guide on how to create a robot which accesses Salesforce using the REST API and OAuth.

First, log into http://developer.force.com with your Salesforce account by clicking "DE LOGIN" at the top of the page. Create a new account if necessary.

On the home page of your account, take note of the "instance" on which your account runs. The instance is given in the server name part of the URL. In the case shown below, the instance is "na12".

Then choose "Remote Access" from the menu on the left. It can be found under "App Setup" >> "Develop".

Now, create a new Remote Access Application. This application will give access to the APIs of Salesforce through OAuth.

A configuration screen now appears for the new app. Fill in the form with relevant information. One of the fields is called "Callback URL". Write the OAuth callback URL in this field. Salesforce requires use of HTTPS so the callback URL is therefore directed to https://localhost:50443/OAuthCallback. As we will see in a moment, 50443 is the default port when setting up an embedded Management Console to use HTTPS.

After clicking save, a page with application details is opened. On this page it is important to take note of the Consumer Key and Consumer Secret which will be used in the Management Console later on.

To set up a local Management Console to use the HTTPS protocol, open up Settings. On Windows, Settings can be found in the Start Menu, in the same folder as Design Studio. In Settings, go to the Management Console tab, disable the HTTP protocol and enable HTTPS instead.

Click okay and start - or restart - the Management Console. Once started, open the Management Console. Make sure to open the Management Console at the URL specified for the app. That would be https://localhost:50443 for the information used above. Then navigate to the OAuth Repository and click "New Application".

Select a name for the new application and choose Salesforce as the service provider. Enter the Consumer Key and Consumer Secret noted earlier. The Callback URL should already be correctly stated. If you would like to specify the user permissions requested by the app, you may fill in the Scope field using the parameters given on https://help.salesforce.com/help/doc/en/remoteaccess_oauth_scopes.htm. Separate scope parameters with spaces.

After being saved, the application appears in the repository. Click on the icon under "Add User" to add a user to the application.

Choose a name for the user and click next.

Now, click the authorization link.

This will open a page where the app will request permission to access your Salesforce account, specifying any special permissions requested. The permissions shown below are requested by default.

Authorizing the app will forward you to the OAuth callback page of the Management Console. At present time there is a bug in the HTTPS version of the Management Console, which causes the callback page to be scrambled. This does, however, not affect the authentication process.

Close the OAuth callback page, returning to the Management Console. Click Next in the wizard and you will see the access token and refresh token granted for accessing Salesforce on the user's behalf. Copy these tokens into a notepad, since they will not be accessible later for security reasons.

After clicking Finish, you should now see a user in the Users section of the OAuth tab.

Now, open Design Studio and create a new robot or open the robot you would like to access the Salesforce API. For the robot to be able to use the Salesforce API, make sure that it has an input variable of the complex type "OAuthCredentials". The variable should have "Salesforce" as the service provider name. Also, input the access token and refresh token along with the consumer key and consumer secret noted earlier.

Then, make sure to configure the robot to use OAuth credentials.

The robot should now be able to access the Salesforce API. As an example try copying https://instance.salesforce.com/services/data/v20.0/query/?q=SELECT+Id%2C+Name%2C+Amount%2C+CloseDate+FROM+Opportunity+WHERE+Probability%3C100 into the address bar of the browser view, replacing "instance" with your instance determined earlier, and pressing Enter. This should return a JSON page with opportunities.

To learn more about the Salesforce REST API visit http://www.salesforce.com/us/developer/docs/api_rest/. Since Salesforce uses a REST API it is possible to access the API using the Call REST Web Service step. This is especially helpful since it becomes much easier to specify parameters such as the query used in the above example.

The query specified above is in the Salesforce Object Query Language (SOQL), which is very useful when accessing the Salesforce API. The documentation for SOQL is given at http://www.salesforce.com/us/developer/docs/soql_sosl/index_Left.htm. Once a robot has been built, it is possible to schedule execution of the robot in the Management Console.