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 visit:

What's New

  • Leveraging Action Inputs Key/Value type

The new Salesforce Action Input let you define Salesforce properties using the Action Input UI, which helps reducing syntax errors often seen in the previous version of the Salesforce Extension.

  • Data Source Selectable Schema Fields

The new Data Source Selectable Schema Fields feature lets you choose a subset of the entire list of schema fields to use. The Salesforce data source extension can then be optimized to just select these fields instead of returning everything

  • Data Source Schema Cache Expiration

To improve performance, the previous version of the Salesforce Data Source caches the results of the schema query for 60 seconds so that if other data source use the same Salesforce object we don't need to call the database for this information. The expiration time for this data source schema cache is now exposed under Salesforce Connector Setting to let you define Data source's schema cache duration in seconds.

Extension Components

Action

  • Create Salesforce Object.
  • Create Salesforce Document.
  • Update Salesforce Object.

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.

Installation Requirements

Before installing this extension you must consider the following requirements:

  • You must have administrator/elevated permissions to the SmartIQ web server, including the ability to copy and replace files in the SmartIQ installation folder. This is usually c:\inetpub\wwwroot\<<productname>> however may vary from system to system.

  • You must have the following installation files:

  • Salesforce.Common.dll

  • Salesforce.Force.dll

  • SalesforceExtension.dll

  • Ensure you have a compatible version of the connector with your current SmartIQ system (Connector and SmartIQ should match versions)

👍

Remember

Changes to the configuration may cause interruptions to users in forms.
Before installing this Connector in a production environment, ensure the environment is backed up.
It is recommended that this installation is tested in a non-production environment first, and installed during scheduled downtime.

Installation and Configuration

Use the instructions below to install the connector. If you are upgrading the extension from a previous version, refer to the section Upgrading the Connector.

Note that [<<productname>> Produce Path] refers to the installation path on the web server running SmartIQ where the Produce site has been installed. By default this is c:\inetpub\wwwroot\<<productname>>\produce however may vary from environment to environment. Equally, [<<productname>> Manage Path] refers to where the Manage site has been installed, and [<<productname>>Scheduler Path] refers to the where the Scheduler service has been installed.

How to install the Salesforce Connector

  1. Copy the files listed above into the following folder on the SmartIQ web server:
    [<<productname>> Produce Path]
  2. Using a text editor such as Notepad, open the following file:
    [<<productname>> Produce Path]\appsettings.json

📘

Note

Ensure you have elevated privileges when opening the appsettings.json file, otherwise you may not be able to save in the current folder.

  1. Locate the <Extensions> section of the appsettings.json file and add the following entries:
"SalesforceExtension.CreateSalesforceObjectAction, SalesforceExtension",
"SalesforceExtension.UpdateSalesforceObjectAction, SalesforceExtension",
"SalesforceExtension.CreateSalesforceDocument, SalesforceExtension",
"SalesforceExtension.SalesforceDatasource, SalesforceExtension"

Produce appsettings.json file should look like:

{
  "Extensions": [
    "Intelledox.Extension.DatasourceBuiltin.OleDbDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.SqlServerDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.CsvDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.OdbcDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.WebserviceDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.XmlDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.InfinitiDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.JsonDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.RestDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.ActionBuiltin.FileAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.SQLServerAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.DownloadPageMessageAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.RedirectAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.EmailAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.PrintAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.UserAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.WebhookAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.RESTAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.OracleAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.PushNotificationAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.EscalationBuiltin.EmailEscalation, Intelledox.Extension.EscalationBuiltin",
    "Intelledox.Extension.EscalationBuiltin.ReassignmentEscalation, Intelledox.Extension.EscalationBuiltin",
    "Intelledox.Extension.EscalationBuiltin.PushNotificationEscalation, Intelledox.Extension.EscalationBuiltin",
    "Intelledox.Extension.ActionBuiltin.LogMessageAction, Intelledox.Extension.ActionBuiltin",
    "Intelledox.Extension.ActionBuiltin.SQLProjectResultsAction, Intelledox.Extension.ActionBuiltin",
    "SalesforceExtension.CreateSalesforceObjectAction, SalesforceExtension",
    "SalesforceExtension.UpdateSalesforceObjectAction, SalesforceExtension",
    "SalesforceExtension.CreateSalesforceDocument, SalesforceExtension",
    "SalesforceExtension.SalesforceDatasource, SalesforceExtension"
  ],
  "Authentication": {
    "Settings": {
      "CookiePrefix": "infiniti",
      "Timeout": "30"
    }
  }
}

A similar process has to be done to configure Salesforce data source in manage.

  1. Copy the files listed above into the following folder on the SmartIQ web server:
    [<<productname>> Manage Path]
  2. Using a text editor such as Notepad, open the following file:
    [<<productname>> Manage Path]\appsettings.json
"SalesforceExtension.SalesforceDatasource, SalesforceExtension"

Manage appsettings.json file should look like:

{
  "Extensions": [
    "Intelledox.Extension.DatasourceBuiltin.OleDbDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.SqlServerDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.CsvDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.OdbcDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.WebserviceDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.XmlDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.InfinitiDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.JsonDatasource, Intelledox.Extension.DatasourceBuiltin",
    "Intelledox.Extension.DatasourceBuiltin.RestDatasource, Intelledox.Extension.DatasourceBuiltin",
    "SalesforceExtension.SalesforceDatasource, SalesforceExtension"
  ],
  "AppSettings": {},
  "Authentication": {
    "Settings": {
      "CookiePrefix": "infiniti",
      "Timeout": "30"
    }
  },
  "Styles": {
    "Well": {
      "appliesto": "question,layout",
      "class": "well"
    },
    "Jumbotron": {
      "appliesto": "question,layout",
      "class": "jumbotron"
    },
    "Alert (success)": {
      "appliesto": "question,layout",
      "class": "alert alert-success"
    },
    "Alert (info)": {
      "appliesto": "question,layout",
      "class": "alert alert-info"
    },
    "Alert (warning)": {
      "appliesto": "question,layout",
      "class": "alert alert-warning"
    },
    "Alert (error)": {
      "appliesto": "question,layout",
      "class": "alert alert-danger"
    },
    "Label (default)": {
      "appliesto": "question",
      "class": "labelIx label-default"
    },
    "Label (primary)": {
      "appliesto": "question",
      "class": "labelIx label-primary"
    },
    "Label (success)": {
      "appliesto": "question",
      "class": "labelIx label-success"
    },
    "Label (info)": {
      "appliesto": "question",
      "class": "labelIx label-info"
    },
    "Label (warning)": {
      "appliesto": "question",
      "class": "labelIx label-warning"
    },
    "Label (error)": {
      "appliesto": "question",
      "class": "labelIx label-danger"
    }
  }
}

Using a web browser, navigate to the SmartIQ roduce and SmartIQ Manage applications to allow the system to register the Connector.

The Salesforce Connector should now be installed ready for configuration and usage.

Installation to Scheduler

If the target environment is using the Scheduler, it is best practice to always install connectors and accelerators to this service at the same time as the installation in I<<
Produce application. If this is not installed to the Scheduler there may be errors if any projects are executed from the scheduler that refers to this connector.

To install any connector to the Scheduler, follow the instructions in this guide as they apply to SmartIQ Produce, except instead of [SmartIQ Produce Path] use [SmartIQScheduler Path], noting that there is no ‘bin’ folder in this path so all files should be copied into the root of this path. For example, consider the path:

c:\inetpub\wwwroot\<<productname>>\produce

To install to the Scheduler, simply use this path:

c:\inetpub\wwwroot\<<productname>>\IntelledoxScheduler

Also, you must apply the same configuration changes as instructed for the Produce appsettings.json file.

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. Logging 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 behaviour or context.

  1. In a web browser, navigate to the SmartIQ Manage application and log in.
  2. Navigate to Settings in the Administration menu group, and then click the Connector Settings button at the top of the page.
  3. Using the Connector drop-down list, select the ‘Salesforce Connector’ option.
  4. Review and update the settings as required. The settings are described in the table below.
  5. Click the Save button at the top of the page.

Setting

Description

User Name

The Salesforce.com username who will have sufficient rights to Query, Create and Update Objects in the chosen Salesforce instance.

Password

Password corresponding to the provided username

User Token (Security Token)

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

Authentication URL

The OAuth2 endpoint which the system will use the provided credentials (username etc.).

Consumer Key

The OAuth Id Consumer Key for the SmartIQ Application

Consumer Secret

Corresponding Consumer Secret for the Consumer Secret

Schema Cache Expiration

Data source's schema cache duration in seconds. By default, this is set to 60 seconds.

Debug Mode [true|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.

  • These Connector Settings, apart from "Schema Cache Expiration", only apply to the Actions, they do not apply to the configuration of a Datasource.
  • All of the settings are required to be filled for the Connector to operate.*

🚧

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.