Applies to version 2016.1.x; Author: Karol Wozniak
BPS version 2016 introduced new functionalities which allow simple integration with external service providers. The integration is conducted through the usage of API (Application Programming Interface) supplied by third party vendors.
From the perspective of WEBCON BPS, the API can be employed in one of two ways:
- As data sources – data is fetched from the external system and can be used on the user’s forms e.g. to provide selectable values in Choice field type form fields,
- Through action invocation – data provided in form fields can be used for handling operations in an external system e.g. creating an account in Dynamics CRM based on input provided by the user on the form.
For the process Company business contacts (vendors, consultants/experts etc.) we need the following:
- Ability to automatically create a new account in Dynamics CRM and/or SalesForce for newly registered contacts (e.g. while moving between steps) based on the data entered into the form.
- Ability to then use the pool of existing accounts as a data source for a Choice field – selecting one of them will automatically populate the form with information about the chosen contact account.
This particular case presents how two-way communication from/to our system works.
The configuration presented below that allows the fulfilling of aforementioned requirements in the context of Dynamics CRM and SalesForce API.
Details concerning the queries which are connected to the knowledge of vendor API documentation as well as HTTP protocol usage will not be covered in this article.
REST Data source configuration
The configuration of a REST type data source can be divided into three areas:
- Connection settings to the Web Service
- Settings determining HTTP request with the usage of GET/POST/PUT/PATCH/DELETE methods and optional JSON body
- Settings defining the Response, including the decision of which data collections returned by the Web Service will be available to use e.g. on forms to populate form fields
Usage cases for data sources
A data source is be added which will return all existing accounts created in the SalesForce system. Due to a rather big data set returned for the Account object (it has quite a lot of properties) only several columns will be selected such as: „AccountNumber”, „Name”, „Description”, „Phone”, „AnnualRevenue”.
The data source will be used in Choice field type form field. After selecting specific account other form fields will be populated with its data (explaining this part will be excluded from this article).
Data source configuration for SalesForce API – fetching all existing accounts.
Data source configuration – selecting a resource (Account) from which specific object properties will be fetched.
REST Data sources usually use GET method from HTTP protocol. Due to their concept, they are mostly used for holding data which are accessed/read via form fields (choice fields, SQL grid, charts etc.) on user’s forms.
Usage of REST data source on forms – Autocomplete form field aggregates data returned from SalesForce API and populated other form fields.
REST action configuration
REST action configuration can be divided (similarly to the data source) into several sections – this time four:
- Authentication – choosing data source from which the connection settings will be used, or providing login credentials manually in the configuration
- Request data – URL to an API resource, HTTP protocol method to use and optional custom headers which will be sent in a request
- JSON – for methods POST/PUT/PATCH – it’s usually necessary to provide a body of the request in JSON format
- Response – data returned from API can be easily used to populate specific form fields or item list and its columns
1st Scenario – Create new SalesForce account based on entered data
A new action will be added which will create a new SalesForce account upon its invocation. This Action will be executed after choosing the appropriate path on the workflow instance. It will collect data from form fields in the “SalesForce” tab panel, and based on the found data it will generate an HTTP Request to the external system (SalesForce).
REST Action I configuration p.1 – Configuration of authentication settings with the usage of the process constants holding actual connection data.
REST action I configuration p.2 – Choosing HTTP method as well as pointing to specific API Resource where we would like to create a new object – using process constants holding actual resource name.
REST action I configuration p.3 – request body in JSON format, holding data which will be used to create a new object in the external system (here: an account in SalesForce).
REST action I usage – Data was entered into form fields in the SalesForce tab, then the “Save to SalesForce” path was clicked, triggering an actual call to API and creating a user account.
REST action I usage effect – New account created in SalesForce with data taken from BPS forms.
2nd scenario – Fetch the 5 most recently added accounts and initialize an Item list with their data
Action will be added which will run on demand (menu button on the form) and fetch data of five previously added contacts from Dynamics CRM, and populate the Item list with values based on the response.
REST action II configuration p.2 – Choosing HTTP method as well as pointing to the specific API Resource. Additionally with a query filtering last 5 accounts and selecting only the specific columns.
REST action II configuration p.3 – Defining mappings for the data returned by the API. Form fields which will be populated with an appropriate data are selected.
REST action II usage – after execution data returned by Dynamics CRM API are populated into Item lists and its columns.