Table of Contents
- 1 What is the Salesforce Connector Tool?
- 2 White Paper - Salesforce Connector Tool
- 3 Salesforce Integration Architecture
- 4 About the Salesforce Event Agent
- 5 About the Salesforce Connector
- 5.1 Global Configuration
- 5.2 Step Configuration
- 6 Working with Other Steps
- 7 Supported Objects
- 8 Salesforce Connector Tool Output
- 9 Runtime
- 10 Error Handling
- 11 Salesforce Accounts Security
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.
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
The Salesforce Connector tool allows communication between TaskCentre and Salesforce. This enables efficient integration between Salesforce and incompatible systems, via TaskCentre.
Salesforce Integration Architecture
The diagram below provides a high-level system architecture overview of the Salesforce Connector tool pack, with BPA Platform and Salesforce:
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.
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.
|The full XML string of the workflow event|
|Timestamp 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.
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.
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.
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:
- 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.
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.
When creating new tasks, the Salesforce Connector tool is located under SKIT of the Task Browser.
About the General Tab
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.
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.
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.
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:
getoperation is used to retrieve records.
updateoperation updates fields in existing Salesforce records. To successfully carry out this operation, you must ensure the
Idfield of the outgoing data object is mapped correctly.
createoperation adds new records to the selected outgoing data object.
upsertoperation creates new records and updates existing ones based on the value of the
externalIdfield: if matched, then the record is updated; if not, then a new record is created.
deleteoperation deletes existing records. To successfully carry out this operation, you must ensure the
Idfield of the outgoing data object is mapped correctly.
User-defined objects, if exposed, are also made available for mapping here — these have a
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.
Using Filters with Objects
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.
About the Options Tab
The Options tab allows you to define how errors in this step are handled at task runtime.
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
|Icon||Tool Name||Tool Category|
|Import Flat File||Input|
|Import XML Document||Input|
|Convert Recordset to XML||Format|
|Web Service Connector||Data Connectors|
Exposing XML to Other Steps
|Icon||Tool Name||Tool Category|
|Convert XML to Recordset||Format|
|Web Service Connector||Data Connectors|
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:
Salesforce Connector Tool Output
The Salesforce Connector tool outputs two documents:
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.
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.
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.