Salesforce Sales Cloud
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 synchronizes 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.
We require several custom fields to be added to allow us to reconcile and synchronize the data sets. To prepare the entity model:
- Review the custom Salesforce field configurations in the Data Model Reference
- Add the custom fields to the Salesforce data model
- Enable the contacts to be related to multiple accounts
- 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 event
Salesforce requires triggers be activated for the Salesforce Sales Cloud Connector to pick up on changes that are initiated by Salesforce:
- 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
- Once the event is complete add the following custom fields to the platform event:
Field Label API Name Data Type Operation Type
Text (64) Object Type
Text (64) Old Payload
Long Text Area (32768) New Payload
Long Text Area (32768)
Adding event publisher and triggers
With the platform event created the next step is to intercept various internal events and publish them out for the connector to receive:
- Add a new Apex class called GentrackCallout, referring to the sample code on our Github repository for an example on how to implement
- Add a new Apex class called TriggerHandler, referring to the sample code on our Github repository for an example on how to implement
- Add a new Apex trigger called AccountTrigger, referring to the sample code on our Github repository for an example on how to implement
- Add a new Apex trigger called ContactTrigger, referring to the sample code on our Github repository for an example on how to implement
- Add a new Apex trigger called AccountContactRelation, referring to the sample code on our Github repository for an example on how to implement
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 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:
- Create a new connected app using the following settings:
- Connected App Name: Gentrack Salesforce Sales Cloud Connector
- API Name: (auto generated)
- Contact Email: email@example.com
- Contact Phone: (leave blank)
- Logo Image URL: (leave blank)
- Icon URL: (leave blank)
- Info URL:
- Description: (leave blank)
- Enable OAuth Settings: Checked
- Enable for Device Flow: Unchecked
- Callback URL:
- 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
- Once the form is complete, click Save
- 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
- 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.
- 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@
- Email Address: gcis-salesforce-sales-cloud-connector@
- User License: Salesforce
- Profile: Standard User (or equivalent that can edit data)
- Name: gcis-salesforce-sales-cloud-connector@
- 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
Connecting to Salesforce
When you are ready to create a new connector instance:
- Sign into the GCIS Developer Portal
- Under Connectors click Connector Store
- On the Connector Store page choose Salesforce Connector by clicking on the Setup new instance button
- In the Setup New Instance dialog, provide the following:
- Username - user name 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:
- Tenant - select a tenant from the drop down menu that will be connected to this connector instance
- Click Save which will verify the credentials provided are valid
- From the Connectors list select the newly created connector instance, then navigate to the Salesforce Basic Information page
- 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:
- Navigate to My Connectors under Connectors on the Developer Portal, find your Connector instance in the table and click on it.
- 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.
Starting Synchronisation Process
The connector performs an initial synchronisation to reconcile data sets across both systems, then moves into an on-going synchronisation mode. As you plan for the initial synchronisation you will need to consider:
- Volume of data determines how long the synchronization process takes, we recommend testing first in a non-production environment
- An outage window for both systems to prevent data modifications during initial synchronisation
- Disable Salesforce triggers on related objects
- Disable Velocity event publishing
GCIS uses Salesforce Bulk API 2.0 to do Initial Data Synchronisation and it relies on an External ID to ‘upsert’ (update or insert) records into Salesforce.
To begin the process:
- Sign in to the GCIS Developer Portal
- Navigate to My Connectors then select the connector instance
- As this is the first time you are doing synchronisation for this instance, no synchronisation history will be shown. Over time you will find all the synchronisations run for this instance on this page, regardless whether those were successful or otherwise.
- When both Gentrack billing system and Salesforce are ready, navigate to Initial Data Synchronisation and click Start Migration which will ask you to confirm to proceed
You can monitor progress of the initial data synchronisation on the Initial Data Synchronisation page. Once it has finished, you will see the result - possible options are as follows:
- Initial data synchronisation has successfully completed.
- Initial data synchronisation has completed with errors. For details, a link to a full report in Salesforce will be provided.
- Initial data synchronisation has failed. A synchronisation stage which the process failed at will be indicated.
Additionally, an email will be sent to indicate result of the initial data synchronisation. Once the initial synchronisation is complete you can re-enable Salesforce triggers and Velocity event publishing. At this point Salesforce becomes a source of truth for respective data model attributes. When a change of data occurs in the master system - whether it is Salesforce or Gentrack, - it is automatically synchronised to another. E.g., a change of a contact phone number in Salesforce will automatically update the respective phone number in Gentrack billing system.
As part of onboarding we will work with you on how to link to the related entity in your Gentrack billing system.