Skip to content

Knowledge Base

White Paper Libary

Salesforce Connector Tool v2.0.1

What is the Salesforce Connector Tool?

The Salesforce Connector tool allows communication between BPA Platform and Salesforce. This enables efficient Salesforce integration between Salesforce and incompatible systems, via BPA Platform.

The Salesforce Integration Connector Tool Pack

The tool pack consists of:

  • Salesforce Connector — The Salesforce integration Connector is a BPA Platform tool, used to communicate with the Salesforce API. It must be installed on the BPA Platform server, and on any BPA Platform client machines. It is this that provides the translation between the BPA Platform data and the Salesforce objects and operations.
  • Salesforce Event Agent — The Salesforce Event Agent is a web service, receiving specific events from Salesforce and writing them to a database. These events can then be used by BPA Platform steps for processing.

System Requirements

The Salesforce Connector tool pack requires BPA Platform (formerly TaskCentre) version 4.6 or above. This tool is compatible with the following versions of Salesforce:

  • Salesforce Cloud Services
White Paper - Salesforce Connector Tool

White Paper - Salesforce Connector Tool

The Salesforce Connector tool allows communication between TaskCentre and Salesforce. This enables efficient integration between Salesforce and incompatible systems, via TaskCentre.

Download Brochure

Salesforce Integration Architecture

The diagram below provides a high-level system architecture overview of the Salesforce Connector tool pack, with BPA Platform and Salesforce:

Salesforce Connector Tool v2.0.1

The Salesforce event agent can be installed on any compatible Microsoft Windows Server. If required, you can install the event agent on the same machine running the BPA Platform server instance.

The event agent is independent of BPA Platform. It runs as a service on the server; only one Salesforce event agent can be installed on the server at any one time. The agent writes events to a Notifications table. This table can be located on the same server running the agent, or on a remote machine.

The Salesforce Connector is used to read and write data directly to Salesforce. It must be installed on the same server as BPA Platform, and on any client installations of BPA Platform.

Video Overview

 

About the Salesforce Event Agent

The Salesforce event agent receives workflow events from your Salesforce instance. These are stored in a database for later retrieval and processing by a BPA Platform task step. It runs as a passive web service on the server.

For a detailed description of how to install and configure the Event Agent.

Event Agent Database — Notification Table

The Salesforce event agent makes use of a database table — Notification. This table holds workflow events’ details.

Column NameTypeDescription
IdintPrimary Key
NotificationIdnchar 
ActionIdnchar 
ObjectIdnchar 
ObjectTypenchar 
DataXMLxmlThe full XML string of the workflow event
UserParamvarchar 
EnterpreisURInchar 
CreateDateTimedatetimeTimestamp of when the record was added

About the Salesforce Connector

The Salesforce Connector provides a means of communication between the BPA Platform server, and your Salesforce instance. You install the connector on the BPA Platform server.

Global Configuration

The global configuration for this tool is used to create the connection to the Salesforce server. You access the Global Tool Settings dialog box via System > Tools > SKIT > Salesforce Connector.

salesforce integration

When a connection is created, the available objects and fields of Salesforce are retrieved. Click Add to create a connection to Salesforce.

Using Extended Logging

Enabling this option exposes the XML parsed between the Salesforce Connector and Salesforce.

Without extended logging, the Event Log only contains start and end of transaction messages, plus any error messages encountered at runtime.

You can view the extended log in the BPA Platform Event Log (Manage > Event Log).

About the Connection Settings Panel

You configure the connection to the Salesforce instance here.

salesforce connector

Configure a meaningful Connection Name for this connection; this is the name displayed when adding tasks for Salesforce.

Enter the credentials of the Salesforce user, created in Prerequisites, allowed to access the API, that is:

  • username
  • password
  • security token

You can choose whether to encode ASCII-compatible characters in the XML passed between BPA Platform and Salesforce — select Use HTML-Encoding to enable this; it is recommended you do this.

Select UAT if the instance of Salesforce you are using is the Test or Sandbox version. This changes the URL the Salesforce Connector tool uses to access Salesforce itself.

Use the Test connection button to ensure the Salesforce Connector can access Salesforce correctly.

Licence Panel

Each instance of the Salesforce connection must be licensed — for more information, contact your Codeless Platforms’ representative. The license is in the form of a .stg file. It contains the licensed company name, the expiry date of the license (Valid until), and the licensed Salesforce Connector tool version (max Version).

Click Enter New, and locate and open the license file.

Update Objects and Operations

Enabling this option allows the Salesforce schema within BPA Platform to be refreshed every time an update is made in Salesforce itself.

Should you also upgrade Salesforce to a newer, compatible version, all related schemas within BPA Platform will be refreshed.

Step Configuration

When creating new tasks, the Salesforce Connector tool is located under SKIT of the Task Browser.

About the General Tab

Salesforce Connector

Provide a meaningful Name and Description for this step.

Data source can either be:

  • No data source — If you don’t make use of a dedicated XML input source, select this option to use BPA Platform variables in place of the XML objects’ fields. These can then be mapped to operational fields.
    For example, you can extract various bits of information from an email and store them in BPA Platform variables. Then, having mapped them to Salesforce objects and operations, these can be stored in the Salesforce database for later use.
  • Task step — The data source can be set to an available BPA Platform XML data source. Only those steps that are capable of natively exposing an XML document at runtime are listed. These may be another Salesforce Connector step, or a tool, such as Convert Recordset to XML.
  • Custom schema — An XML schema defines the structure of the parsed XML: what tags are present, and the nesting of the tags. You Define the schema of the XML that will be used as the input data source for this step. The Salesforce Connector tool uses the industry standard XSD format. Any XML processed by this step must conform to this schema else an error will be reported.
    If the XSD schema is available, either import it into the Custom Schema Configuration (use the Import XSD/XML File button), or copy and paste it into the configuration box.

    salesforce integration

    If the XSD schema is not available, you can import an example of the runtime XML (Import XSD/XML File), or copy and paste it into the configuration box. Use the Parse button to create the schema.

  • Input source variable — As well as defining the schema, specify the BPA Platform variable that contains the XML data at runtime.

About the Connection Tab

You specify the Salesforce Connection this step must use.

salesforce integration

All Connections created in Global Tools Settings are presented here.

Alternatively, you can use a BPA Platform variable to create a dynamic connection, where the connection used is determined by runtime circumstances. At runtime, the contents of the variable must match the name of one of the configured Salesforce connections — this is case sensitive.

About the Mapping Tab

Here you define links between the incoming XML (left-side XML tree control) and the outgoing data that is sent to Salesforce (right-side XML tree control). This defines how, at runtime, the incoming XML is to be translated into the XML required for the relevant object and operation.

salesforce integration

The Object drop-down shows the available objects. The Operations drop-down shows the operations available for the selected Object; for all objects, these are:

  • Get — The get operation is used to retrieve records.
  • Update — The update operation updates fields in existing Salesforce records. To successfully carry out this operation, you must ensure the Id field of the outgoing data object is mapped correctly.
  • Create — The create operation adds new records to the selected outgoing data object.
  • Upsert — The upsert operation creates new records and updates existing ones based on the value of the externalId field: if matched, then the record is updated; if not, then a new record is created.
  • Delete — The delete operation deletes existing records. To successfully carry out this operation, you must ensure the Id field of the outgoing data object is mapped correctly.

User-defined objects, if exposed, are also made available for mapping here — these have a __c suffix.

You create the links by clicking and dragging the data source’s field (left) onto its corresponding tool input data field (right). Note that only linked fields are used in the output XML.

BPA Platform formulas and variables can be included in the incoming data — drag them from the BPA Platform Browser to the data source’s incoming XML tree control.

These can then be linked to tool input data fields. Note that BPA Platform recordsets must first be converted to XML using either the Convert Recordset to XML or Transform Data tool before they can be used here.

The Salesforce Connector tool uses eXtensible Stylesheet Language (XSLT) to translate the received XML. The Advanced Translations (XSLT) tab shows the XSLT generated for the links created for the object and operation.

Use Enable Free Type Mode to directly edit the XSLT — this is particularly useful when translating a non-standard translation requirement.

Using the SQLQuery Object

An additional object is made available for use — SQLQuery — with a single operation of Select. You can use this object to query the Salesforce database, to either retrieve data or count the number of records that match specified criteria.

The SQLQuery object does not come with any predetermined fields. Instead, you create a variable (global or task) containing the SQL, then add it to SQLQuery’s incoming XML tree control. Depending on the expected results, this can then be mapped to the relevant outgoing data field — query for data retrieval, or rowcount for the number of records.

For example:
salesforce integration

Using Filters with Objects

When using get and upsert operations, you can make use of filters to limit the data involved. At runtime, these fields are treated as “where clauses”. Available filter conditions are:

  • <> — Not equal to
  • = — Equal to
  • < — Less than
  • > — Greater than

The presence of multiple filter fields implies that all conditions must be met.

Nominated fields must be mapped to be included in the output XML. You add filter conditions by right-clicking the output XML field, and selecting Set as Filter. By default, all filters are set to “equal to”. To change the filter condition, right-click the field again, and select Set Filter Condition. Change the filter condition as required.

Salesforce Connector

About the Options Tab

The Options tab allows you to define how errors in this step are handled at task runtime.

Salesforce Connector

If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Step).

If the step is aborted, you can choose to Continue processing onto the next step in the task, or terminate the whole task immediately (Abort Task).

Working with Other Steps

Consuming XML from Other Steps

IconTool NameTool Category
Import Flat File ToolImport Flat FileInput
Salesforce Connector Tool v2.0.1Import XML DocumentInput
Salesforce Connector Tool v2.0.1Convert Recordset to XMLFormat
Salesforce Connector Tool v2.0.1Transform DataFormat
Salesforce Connector Tool v2.0.1Call TaskExecute
Salesforce Connector Tool v2.0.1Web Service ConnectorData Connectors
Salesforce Connector Tool v2.0.1Salesforce ConnectorSKIT

Exposing XML to Other Steps

IconTool NameTool Category
Convert XML to Recordset ToolConvert XML to RecordsetFormat
Salesforce Connector Tool v2.0.1Transform DataFormat
Salesforce Connector Tool v2.0.1Save FileOutput
Salesforce Connector Tool v2.0.1Call TaskExecute
Salesforce Connector Tool v2.0.1Web Service ConnectorData Connectors
Salesforce Connector Tool v2.0.1Salesforce ConnectorSKIT

Supported Objects

Provision of supported objects and operations are handled independently to the tool pack. This means subsequent changes to the API’s metadata can be made available to instances of the Salesforce Connector tool without the need to reinstall or upgrade.At the time of writing, the following objects are supported:

List: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


Account
AccountContactRole
AccountFeed
AccountHistory
AccountPartner
AccountShare
AdditionalNumber
AggregateResult
ApexClass
ApexComponent
ApexLog
ApexPage
ApexTestQueueItem
ApexTestResult
ApexTrigger
Approval
Asset
AssetFeed
AssetHistory
AssignmentRule
AsyncApexJob
Attachment


BrandTemplate
BusinessHours
BusinessProcess


CallCenter
Campaign
CampaignFeed
CampaignHistory
CampaignMember
CampaignMemberStatus
CampaignShare
Case
CaseComment
CaseContactRole
CaseFeed
CaseHistory
CaseShare
CaseSolution
CaseStatus
CaseTeamMember
CaseTeamRole
CaseTeamTemplate
CaseTeamTemplateMember
CaseTeamTemplateRecord
CategoryData
CategoryNode
ChatterActivity
ClientBrowser
CollaborationGroup
CollaborationGroupFeed
CollaborationGroupMember
CollaborationGroupMemberRequest
CollaborationInvitation
Community
Contact
ContactFeed
ContactHistory
ContactShare
ContentDocument
ContentDocumentFeed
ContentDocumentHistory
ContentDocumentLink
ContentVersion
ContentVersionHistory
ContentWorkspace
ContentWorkspaceDoc
Contract
ContractContactRole
ContractFeed
ContractHistory
ContractStatus
CronTrigger
CustomConsoleComponent


Dashboard
DashboardComponent
DashboardComponentFeed
DashboardFeed
Document
DocumentAttachmentMap
Domain
DomainSite


EmailMessage
EmailServicesAddress
EmailServicesFunction
EmailStatus
EmailTemplate
EntitySubscription
Event
EventFeed
EventRelation
ExternalDataSource
ExternalDataUserAuth


FeedComment
FeedItem
FeedLike
FeedTrackedChange
FieldPermissions
FiscalYearSettings
Folder
ForecastShare


Group
GroupMember


Holiday


Idea
IdeaComment


Lead
LeadFeed
LeadHistory
LeadShare
LeadStatus
LoginHistory
LoginIp


MailmergeTemplate


Name
NewsFeed
Note
NoteAndAttachment


ObjectPermissions
OpenActivity
Opportunity
OpportunityCompetitor
OpportunityContactRole
OpportunityFeed
OpportunityFieldHistory
OpportunityHistory
OpportunityLineItem
OpportunityPartner
OpportunityShare
OpportunityStage
Organization
OrgWideEmailAddress


Partner
PartnerRole
Period
PermissionSet
PermissionSetAssignment
Pricebook2
Pricebook2History
PricebookEntry
ProcessDefinition
ProcessInstance
ProcessInstanceHistory
ProcessInstanceStep
ProcessInstanceWorkitem
ProcessNode
Product2
Product2Feed
Profile
PushTopic


QueueSobject


RecordType
Report
ReportFeed


Scontrol
SelfServiceUser
SetupAuditTrail
SetupEntityAccess
Site
SiteFeed
SiteHistory
Solution
SolutionFeed
SolutionHistory
SolutionStatus
StaticResource


Task
TaskFeed
TaskPriority
TaskStatus
Topic


User
UserFeed
UserLicense
UserPreference
UserProfileFeed
UserRecordAccess
UserRole
UserShare


Vote


WebLink

Salesforce Connector Tool Output

The Salesforce Connector tool outputs two documents:

  • OutputData
  • ErrorData

Both outputs can be:

  • Used directly by subsequent tool steps which consume XML data inputs. If required, use the Convert XML to Recordset tool to convert the XML to a BPA Platform recordset first
  • Accessed using the output (OutputXmlString) or error (ErrorXmlString) objects for response data present in the Task Browser.

Runtime

The incoming XML is translated into the XML format for the object and operation selected in the configuration.

The data for the linked fields is brought across into the output XML — only those fields that were linked are brought across. The XML is passed to the connector tool, which then:

  • Processes the data
  • Performs the operation requested
  • Sends back an XML document containing the response

The XML can then be used by other BPA Platform steps.

Error Handling

Errors are written to the BPA Platform Event Log (Manage > Event Log). You define how errors are handled in the Options tab of the Salesforce Connector tool.

Reasons for the errors could include:

  • Web service connection errors
  • User privilege errors
  • Errors from the Salesforce API
  • Warnings and messages from the Salesforce API

Salesforce Accounts Security

The Salesforce API is the only method used to connect to a Salesforce database, and perform read / write tasks — all security present in the API is used.

White Paper - Salesforce Connector Tool

White Paper - Salesforce Connector Tool

The Salesforce Connector tool allows communication between TaskCentre and Salesforce. This enables efficient integration between Salesforce and incompatible systems, via TaskCentre.