Salesforce Module Basics

Using the Salesforce Module

Salesforce has more than one API for developers to use for interacting with their data in Salesforce.  The primary two API systems are:

1. SOAP API
2. REST API

The Decisions Salesforce module uses the REST API because the Salesforce SOAP API is unique for each customer.  The SOAP API provides concrete access to all of a customer’s custom types and extensions and is therefore a good candidate for a comprehensive Salesforce integration. 

SOAP

Integrating with the SOAP API is the same process you would use for any SOAP based WebService: http://decdocs3x.wpengine.com/integrating-an-internal-web-service-wsdl-within-a-flow/

For Instructions on getting your company’s custom WSDL please refer to Salesforce Developer documentation:

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

REST

The Decisions Salesforce module is a set of prebuilt steps that use the Salesforce REST API and OAuth for security to communicate with Salesforce.  The module provides steps for interacting with the following datatypes:

1. Account
2. Asset
3. Campaign
4. CampaignMember
5. Case
6. Contact
7. Contract
8. Idea
9. Lead
10. Opportunity
11. OpportunityProduct
12. PriceBookEntry
13. Product
14. Quote
15. User
16. Task

Each of these 16 types can be found, accessed, edited, and saved using the out of the box steps in Decisions. 

Installing the Salesforce Module

If you cannot find any of the steps or capabilities in this document you may need to install the Salesforce module.  To install Salesforce Module navigate to the System > Administration > Modules folder, locate Decisions.Salesforce module, right-click it and select Install Module action.

Note: to install Module in Decisions 3.5 or newer, please read the following document.

Using the Salesforce Steps

Using any of the pre-built salesforce steps requires an OAuth token.  OAuth is a standard mechanism for providing security to communicate with a webservice.  In Decisions you must establish an Oauth token which represents a user that will be used to run the REST API and interact with your data in Salesforce. 

There are two types of tokens for interacting with Salesforce:

1. Authorization Token
2. Access Token

Authorization Token

This token must be setup one time and requires communication between Decisions and Salesforce with a user signing into the Salesforce page and retrieving a token to store in Decisions.  Once you setup an authorization token it should not expire.

Access Token

The access token is created using the authorization token, but will expire periodically and needs to be refreshed.  This can be done automatically in your flows using flow steps

Creating an Authorization Token

Creating an authorization token as a first step is important to be able to use any of the Salesforce steps in the salesforce module.  OAuth tokens can be created in /System/Integrations/OAuth/Tokens.  Note: in Providers you will find provider configurations and if you want to customize the application definition for your Decisions installation and Salesforce you can create your own “Application” in Salesforce and then modify the provider data.

1. Click ‘Create Token’

2. Create token will prompt you with a warning if your BaseURLToPortal is not configured to an externally addressable IP or FQDN. This will NOT prevent you from creating a token, but you will have a manual step because Salesforce will not be able to redirect traffic back to your Decisions installation. If you see the warning below you can safely ignore it and continue to follow the instructions below.

3. Fill in the following form and press “Request Token”

            Token Name: This is a name for you to select later in a flow.  Give the token a meaningful name that you will remember.

            Provider: Select “SalesForce.com”

Once you press “Request Token” you will be redirected in a pop up window to Salesforce.com. NOTE: Popup blocking applications and add-ons may prevent this from working correctly.  Please disable them and try to request a token again.

4. After logging into Salesforce.com you will be asked to permit Decisions to interact with Salesforce.com

5. When you finish logging into Salesforce, there is a token created by Salesforce that will be ‘sent back’ to your browser. Your browser will likely redirect to something on your server, or a blank page showing an error. This is acceptable as long as you can copy the URL that is shown in the browser address bar.

In the screenshot below the URL that is important is shown in the Internet Explorer window at the bottom of the screen.  Press “Set access token manually”

6. Copy this URL into the textbox that appears and press ‘Ok’

If successful the Status should change to “Authorization Success” or an error message.

7. Once complete you will see your new token in the list and it will be available for use in flow steps.

Using the Steps

Using the Salesforce steps is like using any other step in Decisions.  One of the properties in all Salesforce steps provided by Decisions is the tokenId.  If you set your input mapping to “Constant” you will have a drop down of tokens as shown below.  You can also use “Select Value” and lookup the correct token to pass to all steps in your flow. 

The Salesforce data types that are provided out-of-the-box by Decisions have simple properties that you can map data into or specify.  For custom fields you will find a property called “Custom Fields” which is an array of custom fields. 

In the screenshot below you will see the Mapping Editor opened to create a Salesforce Case object from Decisions.  The Custom Fields property is set to “Build Array” which lets the workflow designer create a new custom field array to send to Salesforce.  In the screen shot below you will notice that the Field Name is empty.  In Salesforce I have a custom field that happens to be named “Decisions Folder Id” that is a part of my Case screen.  If I want to set this value I need to know what the Salesforce API name for this field is. 

 

Finding Salesforce API Field Name

In the Develop Menu in Salesforce you will find all data types.  If you select a data type, as shown below, you will be able to find custom fields and you will see the API name of the field as highlighted.  “Decisions Folder Id” is actually called “Decisions_Folder_Id__c” by the Salesforce API so this is the name that I need to use in Decisions when editing or setting that custom field.

Here is the completed mapping in the Decisions Mapping Editor for the custom field.

Advanced Salesforce Steps

The steps provided in the Salesforce module do not accommodate all Salesforce data types, or custom data types introduced by your company into your Salesforce environment.  These types can be found using the SOAP version of the API, or you can use the Advanced Salesforce steps in the Toolbox.

Salesforce uses a SQL like query language called SOQL to query objects. 

Run SOQL Query – this step lets you run a query that does not necessarily return data.

Run SOQL Query Get Json – runs a query and gives you a result in Json that you can manipulate using other steps in your flow. 

You can use the Text Merge.Plain mapping for the SOQL query to combine flow data and a query in a step to get or set the correct data in Salesforce. 

SOQL

 

To learn more about SOQL or to refine your queries, login to Salesforce and use the Developer Console.  This is the best environment for tuning the queries you need to make your flow work with Salesforce and once perfected you can paste these queries into your flow steps and substitute the variables that you want to make dynamic.

Dealing with the Json Return

When you use SOQL and get Json data back you can use the steps below in the Toolbox to manipulate the Json and make use of it in the flow.

 

 

 

 

 

Additional Resources

• Using the Mapping Editor
• Using Text Merge in Flow