Configure Salesforce (Legacy) Integration

The Salesforce user account is created on the site http://developer.salesforce.com. The individual representing the organization or company creates a user account using an e-mail address and password. Once registered, Salesforce will send a confirmation email to the user account. Follow the instructions in the email.

The login credentials are used later on in the integration process to authenticate against the Salesforce site so keep them handy. Once the account has been created, a security token for the chosen password must be generated. The image and steps below describe how to do this:

1. Log into the Salesforce web site. The Getting Started Salesforce page is displayed.
2. Click the login name in the upper right corner of the page, this displays a menu. Select My Settings from this menu.
3. Click Personal in the navigation bar on the left of the page to expand the menu, then select the Reset Security Token item. Read the important information on the page.
4. Salesforce will send an e-mail with the new security token. This token must be appended to the account password to access Salesforce from within K2.

Salesforce supplies a Web Services Description Language (WSDL) file to its customers. The WSDL file enables the developer to integrate with Salesforce using the Salesforce API.

The method of generating the WSDL file is beyond the scope of this document but full details can be found on this site: Salesforce: SOAP API Developer Guide.

Once you have the WSDL file you can distribute it amongst the developers in your organization and use it to generate the files required for developing solutions in conjunction with Salesforce.

As a prerequisite to generating the service instance, the Windows SDK .NET Framework 4 must be installed. See the K2 Product Compatibility, Integration and Support matrix for supported versions.

A Windows Registry entry of type String must be created in the following branch: HKLM > Software > Microsoft > .NETFramework with the following data:
Value name: SDKInstallRootv4.0
Value data: C:\\Program Files (x86)\\Microsoft SDKs\\Windows\\v7.0A\\ (the SDK is installed to this folder by default).

Before the service instance can be registered and used, it needs to be generated. This is done by using the Broker Manager.

1. The Broker Manager is started by browsing to the ServiceBroker folder in the K2 installation folder and running the BrokerManagement.exe file ("%ProgramFiles%\K2\ServiceBroker\BrokerManagement.exe").
   
2. Select the Salesforce Instance Generator from the list:
   
3. Fill in the Salesforce Instance Generator page remembering to append the security token generated earlier to your password.

   The Instance destination path should be a short path with no spaces or ( ) in it, as these characters will cause an error.
   Once the files have been generated, they can be copied to "%ProgramFiles%\K2\ServiceBroker\Salesforce" and registered from there.

   
   As Salesforce requires TLS 1.1/TLS 1.2 from July 2017, you must use the Latest Available or .NET v 4 options in the MS .NET version box as prior versions do not support TLS 1.1/TLS 1.2.
4. Choose to register the DLLs and enter credentials (remember that security token with the password).
   
5. Once the DLLs have been registered it is important to restart the server to allow for the caching credentials step.

Considerations

The Generate button will generate the necessary DLLs from the WSDL and after some time, which depends on the connection to Salesforce and the complexity and quantity of Salesforce objects to generate, a dialog box will ask if you want to register the DLLs. If there is an issue during the registration and you need to cancel out, you can use the Register button after sorting out the issue instead of re-generating the files (re-generating the files can be time consuming). Be sure to provide the same Instance destination path and This instance name in the dialog that come up, that you entered when generating the DLLs.

The final step is to cache your credentials by selecting the Cache Salesforce Credentials, remember to append the token to the password.

Configuring credentials to execute Salesforce SmartObject methods

Issue:

A Salesforce service instance is created and some SmartObjects are created.

The application that uses the SmartObjects cannot execute their methods unless you have cached the Salesforce credentials in Workspace while being logged in as yourself. The application needs to use impersonation, so as long as the impersonated person has cached their credentials beforehand, the SmartObject methods will execute successfully. If you do not cache your credentials, the exception thrown is "No Credentials Cached for this label".

Workaround:

To avoid the requirement that each end user needs to cache Salesforce.com credentials in order for a SmartObject method to execute, perform the following:

1. Ensure that the web application using the SmartObjects is running under an app pool account that is in turn configured to run under a service account user identity (i.e. not a predefined service).
2. In your browser, log into Workspace as that app pool service account user and drill into "K2 Management > Smart Objects > Services > Salesforce Service". Select the service instance that you are using and click ’Credentials’, then enter the Salesforce credentials. Ensure that you append the Salesforce token to your password.
3. In the web application code, you need to:
   1. Remove impersonation.
   2. Sign into the SmartObject server.
   3. Execute the SmartObject methods once you are done with the connection.
   4. Resume impersonation. By removing impersonation during sign in, the K2 server will pick up the service account user in the app pool that this application is running under.

Web application code:

using SourceCode.SmartObjects.Client;
.
.
.

object retVal = null, paramValue = "Some_Value";

// Stop impersonation
System.Security.Principal.WindowsImpersonationContext ctx = System.Security.Principal.WindowsIdentity.Impersonate(IntPtr.Zero);

SmartObjectClientServer clientServer = new SmartObjectClientServer();
clientServer.CreateConnection();
clientServer.Connection.Open("Integrated=True;IsPrimaryLogin=True;Authenticate=True;EncryptedPassword=False;Host=[YOUR_K2_HOST];Port=5555"); // conn string hard-coded for simplicity.
SmartObject soOpportunity = clientServer.GetSmartObject("sfOpportunity"); // or whatever your smart object is named.

try
{
// replace quoted values with your own values.
smartObject.Methods["methodToExecute"].Parameters["paramName"].Value = (string)paramValue;
smartObject.MethodToExecute = "methodToExecute";
clientServer.ExecuteScalar(soOpportunity);
retVal = smartObject.Properties["returnPropertyName"].Value;
.
.
.
.
}
catch (SourceCode.Hosting.Exceptions.AuthenticationException authEx)
{
if (ctx != null)
{
ctx.Undo();
}
throw new Exception("SourceCode.Hosting.Exceptions.AuthenticationException: " + authEx.Message);
} //*/
catch (Exception ex)
{
// Resume impersonation
if (ctx != null)
{
ctx.Undo();
}
throw new Exception(ex.Message);
}
finally
{
// Resume impersonation
if (ctx != null)
{
ctx.Undo();
}
}