HomeGuidesRecipesAPI
HomeGuidesAPILog In

Salesforce Connector

Salesforce is a cloud-based Customer Relationship Management (CRM) tool. The Salesforce Connector’s purpose is to unlock the data within this repository for use in SmartIQ. This connector focusses on treating Salesforce as a core system of record allowing processes to read and write information.

Here's a guide on how to install the Salesforce Extension to get started. This article will also provide a walkthrough on how to upgrade from your current Salesforce Connector to the compatible Salesforce Extension.

If you want to learn more about Salesforce, please refer to the Salesforce website.

Extension Components

Action

Data Source

  • Picklist
  • All Picklists for an Object
  • Salesforce Object

Features

  • Query Salesforce Objects
  • Retrieve Salesforce Object Picklists
  • Create new Objects in Salesforce
  • Update existing Objects in Salesforce
  • Store documents in Salesforce

Creating a Salesforce Sandbox

  1. Create a new account here
  2. You'll receive a confirmation email, click "Verify Account".
  3. Change Password.

At this point, you have successfully created a Sandbox that you can use to develop and test your SmartIQ projects.

Where do I find my User Token?

You are given a security token the first time you log into Salesforce. If you cannot locate the token you can reset it by:

  1. Logging into Salesforce as the relevant user
  2. Click on your username in the top right corner
  3. Choose Settings from the menu
  4. Click My Personal Information
  5. Click Reset our security token and follow the steps provided.

How to Generate a Consumer Key and Consumer Secret

The Salesforce Connector needs to access Salesforce data remotely. To grant access to this data, Salesforce requires a “Connected App” be configured for remote access.

  1. Log into Salesforce as the relevant user.
  2. Click on Setup in the top right corner.
  3. Using left menu, click on App Manager under Apps section.
  4. Click on New Connected App.
  5. Enter the required basic information (Connected App Name, API Name and Contact Email).
  6. Select Enable OAuth Settings.
  7. Enter a Callback URL. Depending on which OAuth flow you use, this is typically the URL that a user’s browser is redirected to after successful authentication. Most of the time this is <https://login.salesforce.com/services/oauth2/token>.
  8. Add all supported OAuth scopes (Full access (full) is recommended) OAuth scopes to Selected OAuth Scopes.
  9. Click Save.

Once you click save, the page will refresh with a Consumer Key and Consumer Secret. Take note of both as you'll need them for the connector settings.

For more information, please click here.

Configuring the Connector Settings

The Salesforce Connector exposes a number of connector settings which provide system-wide values to control behavior or context.

  1. Go to Manage > Settings > Salesforce Connector.

  1. Review and update the settings as required. The settings are described in the table below.
SettingDescription
User NameThe Salesforce.com username who will have sufficient rights to Query, Create and Update Objects in the chosen Salesforce instance.
PasswordPassword corresponding to the provided username
User Token (Security Token)API User Token supplied by Salesforce which makes the Username given.
Authentication URLThe OAuth2 endpoint which the system will use the provided credentials (username etc.).
Consumer KeyThe OAuth Id Consumer Key for the SmartIQ Application
Consumer SecretCorresponding Consumer Secret for the Consumer Secret
Schema Cache ExpirationData source's schema cache duration in seconds. By default, this is set to 60 seconds.
Debug Mode [true or false]Debug Mode set to true will log each field mapping and tasks being performed by the Actions on execution. The messages will be found in the Manage > Management Log for a given generation/submission.

📘

Notes

  • These Connector Settings, apart from "Schema Cache Expiration", only apply to the Actions, they do not apply to the configuration of a Data source.
  • All of the settings are required to be filled for the Connector to operate.
  1. (Optional) For multiple accounts:
    1. Click the New Set button to create additional accounts. For example, Sandbox and Production.
    2. Click the Set as Default button to change the default connector set. If the previous Default was set in Design, SmartIQ will now use the new Default connector values.
  2. Click Save.

🚧

Note

To reduce the chance of unexpected downtime, it’s advisable that the Salesforce username being used in the Connector Settings be set to Never Expire.

Create Salesforce Object Action

Responsible for creating a new Objects in Salesforce, features include:

  • Creating a new Standard or Custom Salesforce Object
  • Field and picklist population including custom fields
  • Upsert support based on a Salesforce defined external key
  • Repeating Section Support

Using the Action in Design

Start a new or open an existing SmartIQ Project that requires the Create Salesforce Object functionality. It is best to get the form flow and business logic finished first so it is easily identifiable fields and logic need to be applied to the Action.
Once you’ve added the Create Salesforce Object Action to your project, either on the Finish page or on a workflow transition, use the following table to configure any action attributes that you require.

📘

Mandatory Fields

Mandatory action attributes are donated with a *. Use the table below to apply any action attributes that are appropriate.

Attribute

Description

Object Type*

The API name for the Object you are creating in Salesforce.
Eg. Account

Upsert Check Field Name

Optional
API Field name that corresponds to an External Id field. This can be used to allow forms to be re-entrant in that they will look for the Check Field Name and Check Field Value as a key. If not found a new Record will be created, if found the record will be updated.

Upsert Check Field Value

Optional
Unique value for the external id

Field

Provided as name=value pairs where the name is the API name for the field you wish to set a value for.
These are specified as name-value pairs separated by an equals sign.
E.g FirstName=John

The Action produces a single output which is the “ObjectId” which on success is populated with the unique identifier of the new or updated object in Salesforce.

Create Salesforce Document Action

Responsible for storage of documents from the SmartIQ generation into Salesforce. All documents passed to this action will be stored with their generated filenames against the defined object based on the attributes configured; features include:

  • Storage of generated documents in Salesforce as ContentDocument Objects with their associated ContentVersion Object
  • Population of ContentDocument fields
  • Ability to set Sharing and Visibility attributes
  • Automatically relating the documents to an Object
  • Repeating Section Support

Using the Action in Design

Start a new or open an existing SmartIQ Project that requires the Create Salesforce Document functionality. It is best to get the form flow and business logic finished first so it is easily identifiable fields and logic need to be applied to the Action.
Once you’ve added the Create Salesforce Document Action to your project, either on the Finish page or on a workflow transition, use the following table to configure any action attributes that you require.

📘

Mandatory Fields

Mandatory action attributes are donated with a *. Use the table below to apply any action attributes that are appropriate.

Attribute

Description

Object Id to Link to*

The id of the Object that the documents will be associated to. For example, if the document should be displayed on the ACME Inc Account Object then the Id of ACME Inc should be passed as the attribute.
E.g 001O0000013FNQiIAO

Document Visibility

Salesforce visibility setting for the documents being stored.
Default: AllUsers

Document Share Type

Salesforce Share Type setting for documents being stored.
Default: V

Field

Provided as name=value pairs where the name is the API name for the field you wish to set a value for.
These are specified as name-value pairs separated by an equals sign.
E.g FirstName=John

Update Salesforce Object Action

Responsible for modifying an existing Object in Salesforce; features include:

  • Set and Update fields including custom fields on the Object
  • Repeating Section Support

Using the Action in Design

Start a new or open an existing SmartIQ Project that requires the Update Salesforce Object functionality. It is best to get the form flow and business logic finished first so it is easily identifiable fields and logic need to be applied to the Action.
Once you’ve added the Update Salesforce Object Action to your project, either on the Finish page or on a workflow transition, use the following table to configure any action attributes that you require.

📘

Mandatory Fields

Mandatory action attributes are donated with a *. Use the table below to apply any action attributes that are appropriate.

Attribute

Description

Object Type*

The API name for the Object you are creating in Salesforce.
Eg. Account

Object Id*

The id of the Object to be updated.
E.g 001O0000013FNQiIAO

Field

Provided as name=value pairs where the name is the API name for the field you wish to set a value for.
These are specified as name-value pairs separated by an equals sign.
E.g FirstName=John

The Action produces a single output which is the “ObjectId” which on success is populated with the unique identifier of the updated object in Salesforce.

Salesforce Datasource

Responsible for querying information from a Salesforce instance; features include:

  • Searching on standard and custom fields using Salesforce native query
  • Ability to restrict which fields are queried and returned
  • Retrieve picklist and dependent picklists for an Object
  • Retrieve all picklists for a given object in a single call to enable reusability in the form

Configuring the Data Source

After installation, the Datasource type “Salesforce” will be available in Manage. Create a new Datasource of type “Salesforce" to reveal the configuration options.
The connection string is structured as a key=value pair separated by a semi-colon.
The possible keys are:

Attribute

Description

url

Authentication URL for the OAuth Id Flow.
Defaults to “https://login.salesforce.com/services/oauth2/token”

consumerkey

The OAuth Id Consumer Key for the SmartIQ Application

consumersecret

Corresponding Consumer Secret for the Consumer Secret

token

API User Token supplied by Salesforce which makes the Username given.

username

Optionally used if the Credentials Area of the Datasource is not populated.

password

Optionally used if the Credentials Area of the Datasource is not populated.

url=https://test.salesforce.com/services/oauth2/token;consumerkey=keyHere;consumersecret=codeHere;token=tokenHere

The Credentials area of the Connector settings is used to specify the username and password instead of using the name/value pair within the Connection String.

Click "Test Connection" button, a "Connection successful" message should

📘

Note

Refer to How to Generate a Consumer Key and Consumer Secret within this article if you’re unsure of the consumer key or consumer secret. Refer to Where do I find my User Token? for help finding and resetting the token value.

Adding Data Objects

The Datasource Provider employs Object Types to split the different functions available. Here are the Object Types included:

Object Type

Description

Filter Fields

Salesforce Object

Option 1. To retrieve all fields on an object
By adding the Object Type name to the Data Object Name the Connector will retrieve all fields for and object as key fields and display fields.
E.g Account

All fields for the object type

Salesforce Object

Option 2. To selectively retrieve fields on an object
By adding an object name and then a bracket enclosed, pipe separated list of API field names for that Object type the connector will only make those fields available for searching and display.
E.g Account[Id|Name|Education_Level__c]

Only the fields specified between brackets in the data Object Name

Salesforce Object

Option 3. To selectively retrieve fields on an object
By adding object name and then manually choose a subset of entire list of API/schema fields for that Object type from "Available Schema Fields", the connector will only make those fields available for display.

All fields for the object type

Picklist

Retrieves all possible values for a specific picklist on a specific object type. This is expressed using the dot notation to separate the object name and the picklist name. Both names are given as the Salesforce API name. Eg. Account.Education_level__c

active
defaultValue
label
value
controllerLabel
controllerValue

All Picklists for an Object

Given an Object type by it’s API name this Data Object will retrieve all picklists associated with this Object type as a hierarchical datasource. At runtime all values will be loaded once. This Data Object can provide a performance improvement when the same picklists are reused throughout a complex Object Type. E.g retrieving Account.Countries once and reusing it across 10 other account fields that require a countries list, saving 9 calls to the database cache or Salesforce itself

none

🚧

Important

Salesforce enforces a limit on the query length which SmartIQ can generate. This can mean that for Object Types with many field names the generated query may become too long, be truncated and return no data. This will typically occur with Account, Lead and Opportunity but could apply to any other Object type or Custom Object type.