Gentrack Support

Salesforce Sales Cloud

Overview

Salesforce Sales Cloud is a sales performance management solution that compliments your Gentrack solution by providing lead-to-order journey management for demanding sales teams.

Gentrack Cloud Integration Services offers a native integration with Salesforce Sales Cloud which has been optimized to deliver the best of both systems. Our connector synchronises relationship, contract, quote-to-order management data, surfaces events on which more complex workflows can be built, and delivers the essential sales workflows for your business. Gentrack regularly invests in performance, reliability, and quality of the integration which is important in keeping pace of change driven by Salesforce, as well as Gentrack’s own products. Using this connector allows you to focus on your business and not worry about maintaining the skills necessary in both billing and CRM spaces, as well as integration strategies and tooling.

The documentation captures the general process of enabling the connector. Given the nature of Salesforce we consider this to be a complex connector where pricing includes an on-boarding program for us to work with you to activate the connector as well as address your unique integration needs.

Before you begin

To use this connector you will need to ensure that you are running:

  • Gentrack Billing System
    • Velocity 4.13 or later, with the latest system modules
    • Junifer 6 or later
  • Salesforce Sales Cloud Enterprise Edition
    • Service account will require a licensed user profile

Before you initiate the synchronisation process you will need to plan for an outage window to ensure there is no data corruption during the initial synchronisation. To ensure an efficient synchronisation the initial synchronisation will require that you:

  • Disable Salesforce triggers on related objects
  • Disable Velocity event publishing

Preparing your Salesforce instance

Before you connect your Salesforce instance you will need to configure entities, install event triggers, and create a service user.

Configuring entities

We require several custom fields to be added to allow us to reconcile and synchronise the data sets. To prepare the entity model:

  1. Review the custom Salesforce field configurations in the Data Model Reference
  2. Add the custom fields to the Salesforce data model
  3. Enable the contacts to be related to multiple accounts
  4. Enable quotes

In addition to adding the custom fields, you will need to review your screen layout to make a decision on how best to represent the additional fields for your users.

Adding the Gentrack Object Event channel

Gentrack Object Event channel is used by the Salesforce Sales Cloud Connector to synchronise Salesforce entities to the Gentrack billing system upon changes in Salesforce entities.

In this Platform Event channel,

  • Salesforce is the publisher
  • Salesforce Sales Cloud Connector is the subscriber
  1. Create a new Platform Event that the connector can listen to using the following parameters:

    • Label: Gentrack Object Event
    • Plural Label: Gentrack Object Events
    • Object Name: Gentrack_Object_Event
    • API Name: Gentrack_Object_Event__e
    • Publish Behavior: Publish Immediately
  2. Once the event is complete add the following custom fields to the Platform Event:

    Field LabelAPI NameData Type
    Operation TypeOperation_Type__cText (64)
    Object TypeObject_Type__cText (64)
    Old PayloadOld_Payload__cLong Text Area (32768)
    New PayloadNew_Payload__cLong Text Area (32768)

Adding Platform Event publisher and triggers

With the Platform Event created, Salesforce Apex Classes and Apex Triggers are required to publish Platform Events upon changes on Salesforce entities.

The following are examples of Apex Classes and Apex Triggers.

  1. Add following Apex classes in Salesforce
  2. Add following Apex triggers in Salesforce

Refer to the following Salesforce documentations for more details:

Note:

  • The above code examples are not production-level code, and are for test purposes only.
  • We recommend you follow your normal Salesforce code release process in writing, testing, and deploying these classes and triggers. You may also consider alternative designs depending on other Apex code you have running in your instance.

Creating the application profile

The application profile allows you to track the activity the connector performs against all aspects of Salesforce, and limits operations regardless of service account access:

  1. Create a new connected app using the following settings:
    • Connected App Name: Gentrack Salesforce Sales Cloud Connector
    • API Name: (auto generated)
    • Contact Email: ops-gcis@gentrack.com
    • Contact Phone: (leave blank)
    • Logo Image URL: (leave blank)
    • Icon URL: (leave blank)
    • Info URL: https://go.gentrackcloud.com/docs/gcis/salesforce-sales-cloud-connector
    • Description: (leave blank)
    • Enable OAuth Settings: Checked
    • Enable for Device Flow: Unchecked
    • Callback URL: http://localhost
    • Use Digital Signature: Unchecked
    • Selected OAuth Scopes: Full access
    • Require Secret for Web Server Flow: Checked
    • Introspect All Tokens: Unchecked
    • Configure ID Token: Unchecked
    • Enable Asset Tokens: Unchecked
    • Enable Single Logout: Unchecked
    • Leave all other sections with default values - Web App Settings, Custom Connected App Handler, Mobile App Settings, Canvas App Settings
  2. Once the form is complete, click Save
  3. Note the warning “Allow from 2-10 minutes for your changes to take effect on the server before using the connected app”, then click Continue
  4. On the app detail page under API take note of the following values for later:
    • Consumer Key
    • Consumer Secret - you will need to click to reveal

Creating the service account

The service account is used in combination with the application profile to make API calls and subscribe to the Platform Events. The authentication model requires that we have both a password and a token for this user.

  1. Create a new user for the service account using the following values set and reviewing other settings as per your instance’s configuration:
    • Name: gcis-salesforce-sales-cloud-connector@[your domain]
    • Email Address: gcis-salesforce-sales-cloud-connector@[your domain]
    • User License: Salesforce
    • Profile: Standard User (or equivalent that can edit data)
  2. Login as the new user, then reset the security token to generate an API token for the user and take note of it for use in configuring the Salesforce connection later

Adding the Gentrack Event channel

Gentrack Event channel is used by the Salesforce Sales Cloud Connector to publish Gentrack Events to Salesforce.

In this Platform Event channel,

  • Salesforce Sales Cloud Connector is the publisher
  • Salesforce is the subscriber
  1. Create a new Platform Event that the connector can listen to using the following parameters:

    • Label: Gentrack Event
    • Plural Label: Gentrack Events
    • Object Name: Gentrack_Event
    • API Name: Gentrack_Event__e
    • Publish Behavior: Publish Immediately
  2. Once the event is complete add the following custom fields to the Platform Event:

    Field LabelAPI NameData Type
    Event IdEvent_Id__cText (64)
    Event TimeEvent_Time__cText (64)
    Event TypeEvent_Type__cText (64)
    PayloadPayload__cLong Text Area (32768)
    VersionVersion__cNumber (4, 0)

Connecting to Salesforce

When you are ready to create a new connector instance:

  1. Sign in to the GCIS Developer Portal
  2. Under Connectors click Connector Store
  3. On the Connector Store page choose Salesforce Connector by clicking on the Setup new instance button
  4. In the Setup New Instance dialog, provide the following:
    • Username - username for the service account
    • Password - password for the service account
    • Security Token - security token generated for the service account
    • Consumer Key - unique identifier for the connected app
    • Consumer Secret - secret generated for the connected app
    • Login URL - the URL of your Salesforce Sales Cloud instance (default: login.salesforce.com)
    • Tenant - select a tenant from the drop down menu that will be connected to this connector instance
  5. Click Save which will verify the credentials provided are valid
  6. From the Connectors list select the newly created connector instance, then navigate to the Salesforce Basic Information page
  7. Click Validate Data Model to ensure the entity configuration is correct

(Optional) API calls to Gentrack

API calls to Gentrack is an optional extra capability in Salesforce Sales Cloud Connector that allows Salesforce applications to directly call Gentrack APIs.

Refer to How to call Gentrack APIs for more details.

Enable API calls to Gentrack

Once a new connector has been created, you can choose to enable API calls to Gentrack:

  1. Navigate to My Connectors under Connectors on the Developer Portal, find your Connector instance in the table and click on it.
  2. On the Salesforce Basic Information page, click Add under the Named Credentials section to enable API calls to Gentrack.

Note: For security reasons, Gentrack does not save the Named Credential.

Rotate Named Credentials

With the Calling Gentrack APIs feature enabled, you can rotate the Named Credential by clicking on the Rotate button.

Note:

  • You can do this any time you believe the Named Credential is lost or compromised.
  • Once the Named Credential has been rotated, the old credential becomes invalid and can no longer be used to request new access tokens.
  • Access tokens, which are generated before the rotation of the Named Credential, will not be revoked or invalidated. They will continue to be valid until its expiry time.
  • Rotating the Named Credential does not break the existing integration. However, it may take a few seconds for Gentrack to update the Named Credential in Salesforce. During this short period, it is possible that you might not be able to request new access tokens.

Disable API calls to Gentrack

With the Calling Gentrack APIs feature enabled, you can revoke the Named Credential by clicking on the Revoke button.

Note:

  • Once the Named Credential has been revoked, the old credential becomes invalid and can no longer be used to request new access tokens.
  • Similar to rotation, access tokens, which are generated before the revocation of the Named Credential, will not be revoked or invalidated. They will continue to be valid until its expiry time.
Last updated on 17 Jun 2021