Salesforce

An automatic and bi-directional sync between Hatch and Salesforce.

 

---

Overview:

• Type: CRM
• Version: Prismatic/Hatch App Marketplace
• Set-Up: Oauth (Credentials)
• Sync Frequency: 15 minutes
• SandBox: Yes

Shared Data:

Objects that Sync with Hatch:

• Contact
• Lead
• Opportunity
• OpportunityContactRole

Sync Rules: How a Hatch Contact gets updated by Salesforce:

The following TRIGGERS cause the listed sync ACTIONS:

• TRIGGER: A Salesforce Opportunity object is updated within the last 17 minutes before the sync began
  • ACTION: All Salesforce Opportunity object fields/values are sync’d
  • ACTION: If there is an associated Salesforce Contact object, that Contact object’s fields/values are sync’d
  • ACTION: If there is not an associated Salesforce Contact object, the associated Salesforce OpportunityContactRole object’s fields/values are sync’d
• TRIGGER: A Salesforce Contact object is updated within the last 17 minutes before the sync began and was not associated with a Salesforce Opportunity object during the sync
  • ACTION: All Salesforce Contact object fields/values are sync’d
• TRIGGER: A Salesforce Lead object is updated within the last 17 minutes before the sync began
  • ACTION: All Salesforce Lead object fields/values are sync’d

Salesforce to Hatch Opportunities

 

Creating a Hatch Opportunity

Sync’d Salesforce objects will be joined into a single Hatch opportunity in one of the following combinations:

• Contact
• Opportunity + Contact
• Opportunity + OpportunityContactRole
• Lead

Updating a Hatch Opportunity

The integration will replace an existing Hatch opportunity when:

• The sync’d External ID matches the existing opportunity’s External ID
• The sync’d External Created At matches the existing opportunity’s External Created At

Adding an Additional Hatch Opportunity

The integration will create an additional (new) Hatch opportunity when:

• The sync’d External ID does not match the existing opportunity’s External ID
• The sync’d External Created At does not match the existing opportunity’s External Created At

Hatch Opportunities to Salesforce Field Mapping

 

Salesforce Customizations in Hatch Integration Settings:

 

User options

• Ignore Leads — A true/false flag that indicates if the integration should process or ignore updated lead records (default is false)
• Push Communications — A true/false flag that indicates if the integration should push communication data back to the external application (default is true)

Admin options

• Contact Additional Select — SQL that will be included in the SELECT statement that retrieves the Salesforce Contact records. It is included in the statement like this: SELECT Fields(ALL), {your value here} FROM Contact … (default is N/A)
• Custom Lead Select — SQL that will replace the default SELECT statement that retrieves the Salesforce Lead records. It is included in the statement like this: SELECT {your value here} FROM Lead … (default is N/A)
• Email Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the Email Hatch field (default is [Contact:Email])
• External Contact ID Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the External Contact ID Hatch field (default is [Contact:Id])
• External Created At Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the External Created At Hatch field (default is [Opportunity:CreatedDate])
• External ID Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the External ID Hatch field (default is [Opportunity:Id])
• External Updated At Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the External Updated At Hatch field (default is [Opportunity:LastModifiedDate])
• First Name Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the First Name Hatch field (default is [Contact:FirstName])
• Last Name Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the Last Name Hatch field (default is [Contact:LastName])
• Max Iterations —
• Opportunity Additional Select — SQL that will be included in the SELECT statement that retrieves the Salesforce Opportunity records. It is included in the statement like this: SELECT Fields(ALL), {your value here} FROM Opportunity … (default is N/A)
• Phone Number Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the Phone Hatch field (default is [Contact:MobilePhone, Contact:Phone])
• Status Keys — A list of field names that the integration will attempt to use (in the order provided) to populate the Status Hatch field (default is [Opportunity:StageName])
• Sync Schedule — The schedule that dictates how often the integration attempts to sync (default is every 15 minutes)

Salesforce API system limits:

• A single sync with a high number of Salesforce objects will fail to import data at very high volumes
  • Importing over ~6,000 total objects from Salesforce at one time will be unstable
  • Importing over ~10,000 total objects from Salesforce at once time will almost definitely fail
  • SOLUTION: Customers should attempt to limit updates in their system to fewer than 6,000 in any 15 minute period
• If syncs fail for more than 20 minutes, it is possible that some records will be missed
  • When a sync starts, it only requests customer records updated in the last 20 minutes
  • If 20+ minutes go by without a sync, it is possible that the next successful sync will miss records updated beyond the 20 minute window
  • SOLUTION: If syncs fail for a long duration, run a back-sync for the time that the syncs were failing to ensure that all data has been sync’d to Hatch

Salesforce to Hatch Business Logic and Rules and Settings:

 

Salesforce→Hatch business logic

1. Define the sync time range

   1. Start timestamp = 17 minutes before the timestamp that the current sync began
   2. End timestamp = the timestamp that the current sync began

2. Get Contact records from Salesforce that have been modified within the sync time range

   1. Both of these criteria must be true for the contact to be pulled:

      1. The LastModifiedDate field on the Contact record must be greater than the start timestamp
      2. The LastModifiedDate field on the Contact record must be less than or equal to the end timestamp

   2. This is the template used to query Salesforce:

      SELECT
      	FIELDS(ALL)
      FROM Contact
      WHERE
      	LastModifiedDate > 
      	AND LastModifiedDate <= 
      ORDER BY LastModifiedDate LIMIT 200 OFFSET 

   3. If contact additional select has been set, this is the template used to query Salesforce (instead of the one above):

      SELECT
      	FIELDS(ALL), 
      FROM Contact
      WHERE
      	LastModifiedDate > 
      	AND LastModifiedDate <= 
      ORDER BY LastModifiedDate LIMIT 200 OFFSET 

3. Get Opportunity records from Salesforce that have been modified within the sync time range

   1. Both of these criteria must be true for the contact to be pulled:

      1. The LastModifiedDate field on the Opportunity record must be greater than the start timestamp
      2. The LastModifiedDate field on the Opportunity record must be less than or equal to the end timestamp

   2. This is the template used to query Salesforce:

      SELECT
      	FIELDS(ALL)
      FROM Opportunity
      WHERE
      	LastModifiedDate > 
      	AND LastModifiedDate <= 
      ORDER BY LastModifiedDate LIMIT 200 OFFSET 

   3. If opportunity additional select has been set, this is the template used to query Salesforce (instead of the one above):

      SELECT
      	FIELDS(ALL), 
      FROM Opportunity
      WHERE
      	LastModifiedDate > 
      	AND LastModifiedDate <= 
      ORDER BY LastModifiedDate LIMIT 200 OFFSET 

4. Look through all the Opportunity records that were retrieved and associate a Contact record (if possible)

   1. If the ContactId property does not exist on the Opportunity record, the integration gets the OpportunityContactRole record from Salesforce for the particular Opportunity record and adds the OpportunityContactRole record data to the Opportunity record
   2. If the ContactId property exists on the Opportunity record, the integration looks to see if it has previously acquired the associated Contact record
      1. If the integration previously acquired the Contact record, it adds the Contact record data to the Opportunity record
      2. If the integration did not previously acquire the Contact record, it gets the Contact record from Salesforce and adds the Contact record data to the Opportunity record
   3. The integration looks to see if the ContactId property exists on the Opportunity record

5. Generate a Hatch opportunity for each Opportunity record (with the added Contact record or OpportunityContactRole record data)

   1. All fields with __r in their name are removed
   2. All fields with :records in their name are removed

6. Generate a Hatch opportunity for each Contact record that was not included in Opportunity record data that was already imported

   1. All fields with __r in their name are removed
   2. All fields with :records in their name are removed

7. End the sync if Ignore Leads is set to true

8. Get Lead records from Salesforce that have been modified within the sync time range

   1. Both of these criteria must be true for the contact to be pulled:

      1. The LastModifiedDate field on the Lead record must be greater than the start timestamp
      2. The LastModifiedDate field on the Lead record must be less than or equal to the end timestamp

   2. This is the template used to query Salesforce:

      SELECT FIELDS(ALL)
      FROM Lead
      WHERE LastModifiedDate >= ${start}
          AND LastModifiedDate < ${end}
      LIMIT 200
      OFFSET ${offset}

   3. If Custom Lead Select has been set, this is the template used to query Salesforce (instead of the one above):

      SELECT ${configVars["Custom Lead Select"]}
      FROM Lead
      WHERE LastModifiedDate >= ${start}
          AND LastModifiedDate < ${end}
      LIMIT 200
      OFFSET ${offset}

9. Generate a Hatch opportunity for each Lead record

   1. All fields with __r in their name are removed
   2. All fields with :records in their name are removed

10. End the sync

Hatch→Salesforce business logic

1. Determine which Salesforce object should receive the communication information
   1. Evaluate the first 3 characters of the externalContactID property
   2. If the characters are 006, the communication should be sent to a Salesforce Opportunity
   3. If the characters are 00Q, the communication be sent to a Salesforce Lead
   4. If the characters are neither of these, end the sync
2. Create a new Task record in Salesforce on the object determined in the last step
3. End the sync