<< Click to Display Table of Contents >> Navigation:  Bizagi Studio > How To´s > Integration how-to's > How to integrate Bizagi with Salesforce

Overview

Integrating Bizagi with a CRM such as Salesforce, is supported through more than one alternative.

This section presents an example of how you can present in Bizagi all leads stored in Salesforce, while allowing that same user to create a new lead based on the information already entered in Bizagi:

 

 

Alternatives

For such scenarios where you want your Bizagi process to connect to your corporate CRM systems in general, to either retrieve information (e.g, Leads, Accounts, Opportunities or Contacts), or to create new records, you may rely on these different features:

 

1. Bizagi Web services connector

Allows you to connect to SOAP-compliant Web services without the need of programming.

For more information about the Web services connector, refer to Invoking external services from Bizagi.

 

2. Bizagi Connectors

Allows you to use existing connectors from Bizagi Connector Xchange, or create you own connectors.

Once you have a connector for your CRM system, it is registered in Bizagi to be used from the process business rules.

Bizagi Connectors will allow you to rely on powerful built-in options, such as graphical mapping for inputs and outputs, or the use of traces to troubleshoot.

For more information about this feature, refer to Bizagi Connectors.

 

3. Bizagi Component library

Allows you to create you own coded components and bundle them in Bizagi, so that you can extend your business rules by using those components directly.

For more information about Bizagi Component library feature, refer to Custom components.

 

 

Salesforce API

Because Salesforce is offered as a cloud service which has an internet-accessible API, it demands the use of a dynamic session ID to invoke any of its methods (for cloud-safety reasons, in order to restrict the invocation of its services to a time frame in which that session ID is valid).

Salesforce SOAP-based API relies on an authentication endpoint that is separate from the service endpoint, and this implies that the logic behind undergoes an authentication flow similar to that one used by those APIs which are based on OAuth exchanges (https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_login.htm).

 

Therefore, using the Web services connector is not optimal because getting a dynamic session ID means that you need to invoke first the Salesforce login method (via an authentication login, password and security token), to then invoke the method you are looking for.

The Web service connector for this approach would result in having more than one call from Bizagi to Salesforce, while not following best practices regarding the management of transactions or highest security aspects when handling session IDs.

 

Due to the above, the best option to approach this integration scenario is to use Bizagi Connectors, though in this how-to we will be invoking Salesforce via its SOAP API, but through the Component library feature.

For this feature we will develop a custom component that handles the session ID and all due aspects which are specific to this authentication mechanism, as available in Salesforce.

 

Before you start

Before you move on with the integration illustrated by this how-to, make sure you already have a valid account at Salesforce.

 

 

When doing so, note that you will need to grant access to your machine, so that it is allowed to use your Salesforce account, as required by Salesforce security policies.

You may authorize such access to your Salesforce account and set up an explicit security token, directly at the Personal settings presented in your Salesforce portal (e.g, https://na22.salesforce.com/_ui/system/security/ResetApiTokenEdit?retURL=%2Fui%2Fsetup%2FSetup%3Fsetupid%3DPersonalInfo&setupid=ResetApiToken).

 

 

What you need to do

In addition to requisites at Salesforce, the following list illustrates a general outline of steps you need to carry out when integrating to Salesforce:

 

1. Create your own component that connects to Salesforce.

This step is done outside of Bizagi to produce a class library.

 

2. Register the component in Bizagi Studio.

This step means using Bizagi Studio to import the class library output into your Bizagi project.

 

3. Configure a business rule that invokes your component.

This step means configuring the use of methods in that component, so that you may invoke Salesforce from any point of your Bizagi processes.

In order to accomplish these steps, you will need to have included in your process data model and user interfaces, the appropriate definitions to either send out information to Salesforce, or to store incoming one.

 

Example

To illustrate how to integrate with Salesforce, we will part from having already implemented a Petition, claims and complaints process, just as the one available directly in Bizagi's Process Xchange (https://www.bizagi.com/en/platform/xchange).

The main objective of this process is to assign responsibilities and to follow up the incoming comments that are either a petition, claim, complaint or suggestion, in order to handle them accordingly throughout the organization.

 

 

For the sake of the example, we will be assuming for incoming requests which are strictly suggestions:

1.The person in charge of analyzing that suggestion ("Case resolver", appointed to the Analyze suggestion task) may choose to create a new lead with the requester's data.

2.Bizagi will present a table with all current leads in Salesforce for the Case resolver to use as real-time reference.

Once the suggestion has been analyzed and assuming that the requester is to be created as a new lead, Bizagi will persist this information in Salesforce.

 

All in all, in this how-to we will be executing these 2 integration points with Salesforce by adding configuration to the existing process template in the Send answer and Analyze Suggestion activities.

The Send answer activity will be the integration point where Bizagi fetches all leads from Salesforce (i.e a read), while the Analyze Suggestion activity will be the integration point where Bizagi submits the new lead (i.e a write).

 

 

Steps

The following steps and component are developed as an example targeted to a .NET platform.

 

1. Create your own component that connects to Salesforce

The first step before even starting to develop the component, is to make sure that you have prepared everything needed to connect to Salesforce.

In addition to having an account and security token as described in the above Before you start section, you will also need to first save the definition of those services made available by the SOAP API of your Salesforce account.

Saving that definition (the actual WSDL) is done into your local machine, and to be hosted by a running IIS web server.

 

 

1.1 Locate the WSDL

Locate the WSDL by logging in to Salesforce portal and then typing API in the quick search box.

Within its search results, you should be able to browse into the Develop API page:

 

 

1.2 Save the WSDL

Once in the API WSDL page, download and save locally the generated WSDL file for your Enterprise Salesforce services, by using your browser's "save link as..." option:

 

 

Notice this file should use the .wsdl file extension (furthermore, the complete default name for this file is "enterprise.wsdl").

 

1.3 Host the file at the IIS

In order to make this file web-accessible, save this file into the local IIS start path at C:\inetpub\wwwroot\.

The image below shows the enterprise.wsdl file being saved into C:\inetpub\e wwwroot\LocalWS\:

 

 

1.4 Modify the WSDL

This step is needed to resolve a known issue which Salesforce has regarding its WSDL definitions.

Modify the WSDL by including this additional line:

<xsd:attribute name="tmp" type="xsd:string" />

into the ListViewRecord element definition.

 

This means changing this original definition:

<complexType name="ListViewRecord">

 <sequence>

           <element name="columns" type="tns:ListViewRecordColumn" maxOccurs="unbounded"/>

 </sequence>

</complexType>

 

Into this one:

<complexType name="ListViewRecord">

 <sequence>

           <element name="columns" type="tns:ListViewRecordColumn" maxOccurs="unbounded"/>

 </sequence>

 <xsd:attribute name="tmp" type="xsd:string" />

</complexType>

 

 

1.5 Verify the WSDL from web-access

At this point, you should be able to access this WSDL via the HTTP protocol.

Use http://localhost/[PATH_TO_YOUR_WSDL] from a browser of your choice, to verify that WSDL is web-accessible and that its structure is XML-consistent after having made modifications to it.

 

As specified in previous steps, the image below uses the LocalWS folder and therefore has the WSDL accessible at http://localhost/LocalWS/enterprise.wsdl:

 

 

1.6 Create a new Visual Studio project.

Now that you have everything needed from Salesforce, proceed to create the component.

To do so, create a new class library project that is targeted for the .NET version 4.0 framework:

 

 

1.7 Add a service reference to the WSDL

As described in Salesforce documentation, add a service reference that points to the WSDL hosted at the IIS:

 

 

 

Notice that the service reference namespace for this example is called sforce2.

Though you may give it any name of your choice, keep into account that the sforce2 exact name will be referenced in further steps in this how-to.

 

1.8 Add other libraries

Include other libraries as needed, especially the System.ServiceModel library:

 

 

1.9 Adjust buffer parameters

All .NET projects by default use buffer parameters set to a low value, aimed for transmitting small amounts of data.

Make sure you adjust such parameters so that you explicitly allow your application to transmit larger amounts of data (you should adjust this in a measurable fashion for a production environment since these settings are part of security measures that mitigate denial of service attacks).

Because the Salesforce example fetches all leads (though an approximate of 22 records), but alongside with a lot of metadata information, proceed to modify the buffer parameters which are: maxBufferSize, maxReceivedMessageSize and maxBufferPoolSize.

 

To do so, edit the binding element found directly in your project's app.config so that it uses the following values (or as measured accordingly to the expected information you will manage):

 

<binding name="SoapBinding"  maxBufferSize="2147483647" maxReceivedMessageSize="2147483647" maxBufferPoolSize="524288">

 <security mode="Transport" />

</binding>

 

 

1.10 Code the component

Include the code for the main Class.cs of your class library project.

You may use the following code which was based on the quick-start Salesforce documentation (https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_quickstart_steps_walk_through_code.htm):

 

 

 

 

Notice that the class called Class1 offers 2 methods which serve as entry points for the logic that Bizagi will need to use from the processes perspective.

These 2 methods are:

•public String Query(String userName, String password, String securityToken): To fetch all leads by providing authentication parameters.

•public String Create(String userName, String password, String securityToken, String firstName, String lastName, String company, String email): To create a new lead, by providing authentication parameters along with the 4 basic and mandatory fields of a new lead: a first name, last name, the company he/she works for, and an e-mail address.

 

Both the class name (Class1) and each of these above methods will be referenced by their exact name in further steps.

 

 

1.11 Build the output

Build your project so that it produces the class library output you need in Bizagi.

Do this while ensuring it is generated for your target system architecture (32-bit or 64-bit system) and .NET framework version:

 

 

The image above shows the MySalesforceLibrary.dll class library output (as named by the sample steps presented before).

Acknowledge on where is this output generated, as it will be needed in further steps and configuration.

 

1.12 Test your component from another Visual Studio project

Though this an optional step, it is strongly recommended to make sure that your component works when invoked by another project.

This other project can be one directly created in your same Visual Studio solution, namely a Console project.

 

 

To do this, create a new Console project to this same solution:

 

 

This will help you test and verify your component (for instance, viewing directly in console output those fetched leads):

 

 

Make sure you include your class library as a reference:

 

 

Then, copy and paste exactly the same contents from the app.config file of the Salesforce class library project, and into the new app.config created for your new Console project.

This means that the app.config or the Console project should define the same endpoint address, and the settings used for the maxBufferSize, maxReceivedMessageSize and maxBufferPoolSize, as shown below:

 

,

 

For the main class (called TestConsole in this example), you may use the following code, and fill in the blanks for userName, password and securityToken:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using MySalesforceLibrary;

 

namespace TestConsole

{

   class Program

   {

       

       static void Main(string[] args)

       {

           String userName = "";                //your account's username here

           String password = "";                //your password here

           String securityToken = "";        //your security token here

           String objectType = "Lead";

 

           Console.WriteLine("Press an option (1-4) to run a test:");

           Console.WriteLine("\t" + "-> 1 to test the connection only");

           Console.WriteLine("\t" + "-> 2 to test querying all leads");

           Console.WriteLine("\t" + "-> 3 to test creating one lead");

           Console.WriteLine("\t" + "-> 4 to test all of the above");

 

           Class1 pr = new Class1();

           String option = Console.ReadLine();

           int optionInt;

           if (Int32.TryParse(option, out optionInt))

           {

               switch (optionInt)

               {

                   case 1:

                       pr.Connect(userName, password, securityToken, objectType);

                       break;

                   case 2:

                       Console.WriteLine(pr.Query(userName, password, securityToken));

                       break;

                   case 3:

                       Console.WriteLine(pr.Create(userName, password, securityToken,

                           "Jerome", "Jones", "AgilityCorp", "jj@agilitycorp.com"));

                       break;

                   case 4:

                       pr.Test(userName, password, securityToken, objectType,

                           "Jerome", "Jones", "AgilityCorp", "jj@agilitycorp.com");

                       break;

                   default:

                       Console.WriteLine("Not a valid option. Ending execution.");

                       break;

               }

           }

       }

   }

}

 

Running the Console project as per the sample code above, will allow you to test separately both the connectivity or all methods used in this example (or you may extend these possibilities if you implement additional methods):

 

 

2. Register the component in Bizagi Studio

Once you have the built class library output and verified its adequate working, open up your project with Bizagi Studio.

 

2.1 Open the Component library

Browse to the Tools tab in the ribbon and click on the Components option.

Click on Add to register your Salesforce component:

 

 

2.2 Enter the component's details

Enter the details for Display name and Description. Finally, locate and upload the class library assembly, which in this example is MySalesforceLibrary.dll:

 

 

Click OK.

 

2.3 Enter the component's details

Similarly as done with the Test Console project, you need to use the same definitions that allow Bizagi as an application to run and transmit Salesforce services.

To do so, copy the contents from the app.config file of the Salesforce class library project, specifically those inside of the <system.serviceModel> element which are <bindings> and <client>.

 

 

From a windows explorer, locate the web.config file of Bizagi and edit it (by default at C:\Bizagi\Projects\[your_project]\WebApplication).

To edit it, first locate its <system.serviceModel> element and then paste such copied content inside of this element:

 

 

Save the file when done.

From this point on, the component has been bundled and can be used freely in any business rule of your processes.

 

 

3. Configure a business rule that invokes your component

Before configuring any given business rule to use the already registered component, you will need to previously make sure you have the appropriate data model definitions and UI options that handle Salesforce data (e.g, the lead's name, e-mail or company fields in Bizagi).

To illustrate this part and produce a fully-running application, recall that we will go through the changes needed in the Petition, Claims and Complaints template process as directly downloaded from the Process Xchange.

 

3.1 Create an entity called Lead

Edit the data model so that it now has an entity called Lead.

To do this, go to the Data model diagram of the process (process wizard step #2) and create a new master entity:

 

 

3.2 Create attributes for the entity

The Lead entity's data structure should match that information used by a Salesforce Lead that is considered by the component.

Therefore, create the following attributes which correspond to those used by the provided code example: Name, Company, StateProvince, Email, LeadStatus, and CreatedDate.

 

 

3.3 Create an entity relationship

Create a new relationship in order to connect the current data model (from the starting point process entity called Claim and Complaint request), to the newly created Lead entity, .

To do so, click on the Relationship option:

 

 

For this relationship, make sure you select Claim and Complaint request as the Entity1, and Lead as the Entity2:

 

 

Then, select the Collection (one-to-many) option.

This will allow the user interfaces to present a table having a list of leads, those which will be fetched by Bizagi from Salesforce.

Bizagi will name this relationship automatically as Leads.

 

 

Now that changes in the data model have been completed, the data model diagram should display the new relationship that connects the Claim and Complaint request entity to the Lead entity:

 

 

 

3.4 Open the forms

We now proceed to edit the existing user interfaces.

To do so, go to the process wizard step #3 called Define forms, and open the form of the Analyze suggestion activity:

 

 

Notice that you may use that information of the requester which is already stored at this point (this set of information is the one to be submitted as a new lead in Salesforce).

Therefore, adjusting the user interfaces to present the possibility of creating a lead in Salesforce only needs a button with its respective click action.

 

3.5 Add a new button

Locate the Button control to add it to the requester's information group:

 

 

Make sure you configure its Display name and Button caption, and then click on Actions and validations to define its click action:

 

 

3.6 Define the button's action

Add a new action, which will trigger integration with Salesforce when the Create as lead button is clicked.

Configure the action to execute a rule, as shown below:

 

 

For the argument configuration, create a new business rule:

 

 

The code in the rule should have:

var myComponent = new MySalesforceLibrary.Class1();

myComponent.Create("", "", "",

 <ClaimandComplaintRequest.Customer.FirstName>,

 <ClaimandComplaintRequest.Customer.LastName>,

 "Agility Corp.",

 <ClaimandComplaintRequest.Customer.CustomerSnapshot.Email>);

 

 

Save the rule while ensuring that no errors are prompted by Bizagi.

The new action which should look similar to this one below:

 

 

Though at this point you may already verify the connectivity with Salesforce from Bizagi and create leads by using the button, we will illustrate as well how to configure that part where we fetch all leads.

 

3.7 Include a table for all leads

While in the same activity's form, create an additional tab:

 

 

Notice you may label it as "Salesforce leads" or with any other name of your choice, though the most relevant part is to make sure you include the Leads relationship of your data model (i.e a collection, to be displayed by Bizagi as a table in runtime).

 

3.8 Configure the table

Set this table's properties as read-only (i.e having delete options, add options and row options disabled), then include the relevant information for a Lead (Name, Company, StateProvince, Email, LeadStatus and CreatedDate), as shown below:

 

 

Close and save the form when done.

 

3.9 Configure the business rule from activity actions.

Go to the process wizard step #4 called Activity Actions.

 

 

Add a new activity action for the On Exit timing of the Send Answer activity:

 

 

Create a new business rule having this code:

var myComponent = new MySalesforceLibrary.Class1();

var result = myComponent.Query("", "", "");

CEntityXmlHelper.fromXmlToEntityWithScopes(Me, result,false);

 

 

Save the rule while ensuring that no errors are prompted by Bizagi, and that's it.

 

 

Execution

Execute your process by using the Run button in Bizagi Studio.

Once Bizagi Work portal is opened in browser, create a new case of the Petitions, claims and complaints process:

 

 

In the first task called Receive request, you will be filling up the details of the requester (document, name,  e-mail), and make sure you select that this request is a Suggestion.

 

 

Click Next when done.

You will see Bizagi on hold for a moment while fetching records from Salesforce.

 

At the Analyze Suggestion task, you can view all leads at the Salesforce leads tab, or use the Create as lead button to create the new lead:

 

 

Viewing all the leads:

 

 

Creating the new lead, while going to Salesforce portal to verify:

 

 

Troubleshooting tips

As stated before, it is strongly recommended that you test the component in Bizagi once you have completely validated that your component's methods work OK when invoked in another Visual Studio project.

Once you have already verified this, and in order to troubleshoot while being used by Bizagi, debug the component by using the standard "Attach to process..." option, as provided by Visual Studio.

To do so, note that you should attach this to a running IIS process of w3wp.exe:

 

 

For this, you will need to make sure that the component's output is bundled in Bizagi in a Debug mode (to be used only in development environments, for troubleshooting purposes).

 

When doing changes to the component and re-building its output, make sure you upload again this new assembly in Bizagi Studio.

To always force that all changes are taken, you may reset your IIS services and delete temporary files or older versions of the dll files of your components.