Overview

The Salesforce Revenue Management Integration provides a wealth of insights to help you manage and improve the health of your business.

1. View current customer revenue, products purchased, and contract terms
2. Manage renewal and post-sales opportunities, forecasts, and workflow
3. Gain visibility into the health of renewals across your business

This article is about integrating ClientSuccess with Salesforce to ingest revenue data. Please review the ClientSuccess Revenue Manager video for more information on general revenue setup, configuration, and reporting.

IMPORTANT: Please ensure you review the Prerequisites section below before implementing the integration

The following topics are covered in this article

• Features and Functionality
• Terminology
• Prerequisites
• Integration Survey
• Step 1: Integrations Configuration Page
• Step 2: Field Mappings
• Step 2a: Field Mappings - Contracts (Opportunities)
  • Renewal Relationships
  • Up-sells and Adjustments
• Step 2b: Field Mappings - Contract Line Items
  • Example Field Mapping - Contract + Contract Line Items
  • Example Field Mapping - Contract Only
• Step 3: Product List and Product External IDs 
• Step 4: Pull One Contract from Salesforce
• Step 5: Sync Filter
• Step 6: Stage Mappings
• Step 7: Bi-Directional Sync and Sync Frequency
• Push Requirements and Roadblocks
• FAQs

Features and Functionality

• Out-of-the-box support for mapping to Salesforce Opportunity and Opportunity Line Items
• Support for one or many products per contract
• Bi-directional sync configurable at the field level
• Sync forecast, closed, terminated, and historical subscription information
• Support for custom stage names to indicate Booked, Lost, or Forecasted revenue
• Safety protocols ensure records in your Salesforce CRM are NOT deleted

Terminology

The Salesforce Opportunity object is typically used to track deals through to a Closed stage.  The Contract module is the ClientSuccess version of the Salesforce Opportunity object. 

The Salesforce Opportunity Line Item object can be used to track products that are added to a particular Opportunity. The Contract Line Items module in ClientSuccess is most similar to Opportunity Line Items in Salesforce. 

A standard Salesforce implementation has a one-to-many relationship between Accounts and Opportunities and a one-to-many relationship between Opportunity and Opportunity Line Items

Here is an example of a Salesforce Opportunity with Opportunity Line Items (in red square).

NOTE: The Salesforce Contract object is not equivalent to Contracts in ClientSuccess.  The Salesforce Contract object is not typically used as part of this integration.

Prerequisites

• An understanding of your Salesforce object structure
• The following data elements are required on contracts brought over from Salesforce
  • Client name
  • Contract term start date
  • Contract term end date
  • Revenue amount for the entire contract term (not ARR or MRR) in your master currency
  • Product(s)
  • Quantity for each product
  • Close date
  • Stage
• There are four recommended implementation models to choose from (note that the above data elements are always required)
  1. Map to the standard Salesforce Opportunity object (sample below, required fields in red)
     
     
     
  2. Map to both the standard Salesforce Opportunity and OpportunityLineItem (AKA OpportunityProduct) object
     
     
     
  3. Map to CS_Contract, a Salesforce custom object that you create
     
     
     
  4. Map to both CS_Contract and CS_ContractLineItem, these are both Salesforce custom objects that you create
     
     
     
• If multiple products per contract are required, you will need to use both the Salesforce Opportunity (or CS_Contract) object and Opportunity Line Item (or CS_ContractLineItem) object. These line-item objects are separate, child objects for product line items.
• Your product list in Salesforce must be entered in ClientSuccess before contracts are imported.  Please see the step “Product List and Product External IDs” for more information.
• Matching data between Salesforce and ClientSuccess (data parity) prior to enabling the sync.  Please see this article for more information.
• If you are interested in Pushing data from ClientSuccess to Salesforce, please see Push Requirements and Roadblocks

Integration Survey

The Revenue Management Integration Survey is provided to help facilitate a quick setup of your revenue management integration.  Please attach the appropriate screenshots within the survey and provide the completed file to your CSM/Onboarding Specialist.  Your Onboarding Specialist will use this information to set up your Salesforce Revenue Integration and import one sample contract for your review.

Note that there are two sheets in the survey to support both a Contract+Line Item or Contract-only implementation model. Please complete the sheet that supports your implementation.

Step 1: Integrations Configuration Page

In this step, you will set up the mapping between the ClientSuccess and Salesforce objects. Please review Salesforce Integrations Configuration for a general overview of how to use this page.

1. Ensure you have authenticated to Salesforce via ClientSuccess
2. Let your CSM know that you would like to use the new Revenue Management module. They will make sure your tenant is configured appropriately.
3. Decide which implementation model you will use (as listed in the Prerequisites section above).  The default configuration is to map to the Salesforce Opportunity object, if you would like to map to the CS_Contract object, please let Support or your CSM know. 
4. If you use a separate Salesforce object to track line items, make sure the “Use Contract Items” checkbox is checked on the main Integration Settings page.
   1. ClientSuccess also needs to know which field is used to map the Line Items object to the Contract object. In most cases, the Salesforce Opportunity ID is used to relate the Opportunity Line Item object (child) to an Opportunity (parent)

1. If you do NOT use line items (e.g. your product is on the same Salesforce object as your Contract) then make sure the “Use Contract Items” checkbox is UNchecked.

Step 2: Field Mappings

In this step, you will configure your field level mappings. Please review the Salesforce Field Mappings Setup Guide first for an explanation of how this page works.

1. Map your Contract level data to ClientSuccess Contracts. This data will typically come from your Salesforce Opportunity object.
2. Map your Opportunity Line Item level data to ClientSuccess Contract Line Items, ONLY IF you use Line Items in Salesforce. If you have one and only one product per Contract, you do NOT need to map Contract Line Items.

1. Setup your sync criteria within Salesforce. An Import Filter will allow you to specify which contract records will be imported into ClientSuccess

Step 2a: Field Mappings - Contracts (Opportunities)

Renewal Relationships/Process

Understanding how your renewals are progressing toward completion is critical functionality in ClientSuccess. To do this, ClientSuccess must know which renewal opportunity belongs to which parent contract.  This relationship mapping can be done either in ClientSuccess or Salesforce. 

If this mapping is to be done in Salesforce, simply populate the “Renewed by” field with the opportunity ID of the child opportunity OR the “Renews” field with the parent opportunity ID. If you automatically create a renewal opportunity after the original opportunity closes, this may be a simple adjustment to your Salesforce opportunity creation process.

Alternatively, this mapping can be set up in ClientSuccess by simply selecting the child contract that renews (OR is renewed by) the chosen contract. 

Mid-term Upsells and Contract Adjustments Relationships/Process

Having an accurate picture of revenue, including up-sells and adjustments, is critical functionality in ClientSucccess. In order to track upsell and down-sell data, an adjustment/amendment is created.

. This is accomplished by a separate opportunity that can add or remove products and revenue from the original contract.

ClientSuccess must know which adjustment opportunity belongs to which parent contract. This relationship mapping can be configured either in ClientSuccess or Salesforce. 

If this mapping is to be done in Salesforce, simply populate the “Amended by” field with the opportunity ID of the child opportunity (e.g. an up-sell) and/or the “Amends” field with the parent opportunity ID

Step 2b: Field Mappings - Contract Line Items

NOTE: These field mappings enable you to have multiple products per contract.  If setting up these field mappings, make sure the “Use Contract Items” checkbox is checked on the main Integration Settings page

Example Mapping for Contract w/Contract Line Items:

Contracts (Opportunities) 

Contract Line Items (Opportunity Line Items)

Example Mapping WITHOUT Line Items (Contract only)

Step 3: Product List and Product External IDs 

1. The Products listed on your Salesforce Contracts must be set up in ClientSuccess beforehand. The Product List can either be entered manually or you can send a list of products via CSV to be imported by customer support with the following required fields:

2. Products MUST indicate if they are recurring or one-time. This enables ClientSuccess to differentiate between contracts with recurring revenue, and therefore can be renewed, vs. one-time revenue.
3. A unique SKU/Product Code must be present for each product. This will be used in future reporting
4. If you are using Salesforce Price Books (typically via the Salesforce Opportunity Line Item object) then Salesforce External IDs ("Product ID - External System ID" in field mapping) must be used for the Product Line Item mapping bi-directional sync. This is the 18 Digit ID found in the URL of each product page in Salesforce. 
5. If you are not using Line Items, ClientSuccess can lookup product information by Salesforce ID, code, or description

Step 4: Pull One Contract from Salesforce

1. Once your fields are mapped and your products are in ClientSuccess, we recommend pulling over one opportunity as a test.  
2. Ensure the one opportunity you want to import has the “Sync with ClientSuccess” checkbox set to TRUE (or otherwise matches your sync filter).
3. Run the manual import from the Salesforce Integrations Configuration Page > Contract: Import/Export/Sync button > Import
4. Review the Integration History for any errors. You can filter for “400” in the Result column, “Contract” in the Resource column, and review the Error Message column for a description of any errors. 

4. Review the “Revenue” module for the sample account to ensure the contract came over as expected. You may need to configure your stages – please see “Step 6: Stage Mappings” section

Step 5: Sync Filter

1. Once the sample opportunity comes over to ClientSuccess as expected, you can now set the “Sync with ClientSuccess” checkbox on all applicable opportunities.
2. In order to establish renewal linkage, you want to ensure that the first new opportunity for a client and all renewal opportunities including forecasted, renewed, and churned/terminated renewals are brought over. Any opportunity that has been created after the initial sale should be brought over.

3. We strongly recommend utilizing the "Sync Preview" Report before enabling the sync. This report will show you how many opportunities will be brought over. This report will also show you the values for any mapped fields and how they will be updated in ClientSuccess/Salesforce. 

4. Please work with your CSM to pull over all applicable opportunities

Step 6: Stage Mappings

1. Stage is required for ALL contracts 
2. Stage configuration is dynamic to meet the needs of all customers who configure their stages differently 
3. Stage keys are added automatically as new contract stage key names are ingested into ClientSuccess. These stages can be found and configured in Global Settings > Field Settings > Contract > Stage
4. Stage Names do NOT need to be added in advance (unlike Product Names)
5. Stages must be configured in order to display booked, forecast, and lost renewals
6. If stages are not set, all Contracts will default to a "Forecast" status
7. There are three Stage Categories found in the “Stage” field for contracts
   1. Booked = Closed Won (Cash in Hand/Paid Contracts).  No longer in a forecast stage
   2. Lost = Closed Lost. No longer in a forecast stage
   3. Not Set = Any state not Lost or Booked and indicates a Forecasted Contract.  
8. Do not configure stages until you have synced opportunities into ClientSuccess
9. Once you have mapped the stages, you will need to do another import of your contracts from Salesforce for the contract stages to be set correctly.

Step 7: Sync Direction and Sync Frequency

1. After you have successfully pulled opportunities from Salesforce into ClientSuccess, you can, if necessary, enable bi-directional sync to PUSH contracts and subscriptions to Salesforce opportunities.
2. This will enable you to push renewals, up-sells, and cross-sells that are created and managed in ClientSuccess back to Salesforce.  Note that contract or line-item deletes in ClientSuccess are NOT pushed to Salesforce.
3. Please see Salesforce Field Mappings Configuration for information on setting the applicable sync direction and frequency

Push Requirements and Roadblocks

Please be aware of the following if you want to push Contracts from ClientSuccess to Salesforce.

1. Salesforce formula fields are not updatable. ClientSuccess can read data from Salesforce formula fields but can not push data to formula fields. This is a key point to remember as you plan your field mapping.
2. Contract pushes are independent of your sync filter. If a push is enabled, ALL contracts created or updated in ClientSuccess will be pushed to Salesforce. Therefore, data parity is critical to ensuring contracts are aligned between systems.  Please see this article for more information. 
3. Custom validation rules can not be created in ClientSuccess. For example, you may have a Salesforce validation rule requiring a non-zero quantity on any Salesforce Opportunity.  This rule can not be replicated in ClientSuccess.
   Also, any Salesforce validation errors will not appear in the ClientSuccess UI.  Only the Integrations History log indicates whether or not a push to Salesforce succeeded or failed.
4. Contracts or line-item deletes are not replicated between ClientSuccess and Salesforce. So, if you accidentally add a line item in ClientSuccess and then delete it, you will need to immediately delete it in Salesforce as well.
5. Salesforce Pricebooks can not be selected from ClientSuccess.  If you are using the Opportunity Line Item object, your Salesforce configuration needs one standard default pricebook for a Contract push to function.  
6. Contracts can only be created in ClientSuccess in your tenant currency.

Many ClientSuccess users create Opportunities in Salesforce and use ClientSuccess to update the record as needed. For example, adjusting probability, stage, etc.

FAQs

• Do I need to have a product on my Contracts?
  • Contract Imports will fail if Products are not present in ClientSuccess.

• Can I have the same product on multiple line items?
  • Yes. This is the recommended approach if you charge different amounts for different time periods.  For example, year 1 has a different price than year 2.

• What happens if I delete a line item or contract in ClientSuccess?
  • To ensure records are not accidentally deleted in Salesforce, deletes in ClientSuccess are NOT pushed to Salesforce.

• Do I need to set up renewal relationships before importing Contracts?
  • No, relationship mapping fields can be imported or configured after the Contracts are brought over.

• I don’t have start dates on my Salesforce Opportunities. What can I do?
  • Start date and end dates are required for any recurring subscriptions. The Close date is likely populated on your Salesforce Opportunities and may be similar to the Start date.

• What is the difference if I map start dates and end dates to the Opportunity object vs. the Opportunity Line Item object?
  • If the start and end dates are on the Opportunity object the line items for the Opportunity will all have the same start date and end date. If you have line items with different start dates and end dates you will want to map to start and end dates on the Opportunity Line Item object. Start and end dates on the Opportunity object override dates on the Opportunity Line Item object.

• I have an Overdue Contract – what does that mean?
  • Contracts are active or overdue until they are either renewed, terminated, or deleted. Renewal occurs by linking a child contract to the original and marking it “Booked”

• I have validation rules on my fields in Salesforce for any record updates. How can I reflect these in ClientSuccess?
  • ClientSuccess is NOT a mirror of your Salesforce instance. If you need to bypass Salesforce validation rules to update fields in Salesforce from ClientSuccess, consider using Salesforce Record Types.

• Can Contracts be linked in ClientSuccess if there is an overlap in start-date or end-date between the contracts (e.g. can an end-date for an original contract come before the start-date of the renewal)?
  • ClientSuccess will only allow parent-child renewal to be linked if there is NO overlap between the start date and end dates. The end date CAN NOT come before the start date.
    However, if the linkages come from a Salesforce import than ClientSuccess does not perform this validation check and will accept both Contracts. 

• I use a custom object for line items, how do I relate it back to the parent object (e.g. Opportunity)
  • The "Use Contract Items" must be checked and the "Contract Item Parent ID" key must be entered on the mapping configuration page.
  • To relate your line-item objects back to the parent object (e.g. Opportunity), please use a lookup field, not a master-detail relationship, for the Opportunity ID.

• I see the error "query did not return a unique result" in the Transaction History when I run a sync
  • Typically, this error is the result of multiple products in the ClientSuccess product catalog that have the same product ID, or whichever field you use to uniquely identify products.
• I see the error "Item Id: Contract Item Missing LookupKey" in the Transaction History
  • The value in the product ID field (e.g. product code, product CRM ID, or product name) cannot be matched to a value in your product list in ClientSuccess. In these cases, the default product will be used to import the Contract into ClientSuccess.

• What do I need to send over to ClientSuccess to indicate that a booked contract has been churned?
  • If you send over a Terminated Effective Date and a Termination Date on the booked contract the contract will be marked as churned.  No other data from Salesforce is required.  
  • Another option is to mark the forecasted renewal opportunity linked to the booked contract as "Lost". This will result in the booked contract being marked as churned.  Remember that both contracts will need to be linked in the "Renewals" section or else the original booked contract will not change status.

• The ARR values in ClientSuccess do not match my calculation
  • You can use the Assigned ARR field mapping at the Contract or Contract Line Item level to overwrite the ARR/MRR values.  Please note that if you use Assigned ARR at the Contract level you must also populate the Assigned MRR value.  

• How do I ensure my integration is working?
  • There are a number of proactive steps you can take to ensure the data integration continues to work as expected.  Please review "Maintaining your Integration" to learn more.