Skip to content
  • There are no suggestions because the search field is empty.

Salesforce Data Synchronization and Troubleshooting

Technical data mapping, custom-object design, outbound updates, operational behavior, and troubleshooting reference.

Configuration Dependency

Exact fields depend on the selected job object, Salesforce schema, enabled options, and custom mappings.

1. Lead Job Creation and Mapping

A Lead requires an active Salesforce-to-OCC user mapping and an eligible association key, commonly Lead.OwnerId. It must pass configured filters.

Standard Lead Field Mapping

OCC Destination Salesforce Source
Customer Name Lead.Name
Job Name Lead.Name + Lead.ProductInterest__c
Email Lead.Email
Lead Source Lead.LeadSource
Street Lead.Address.street
City Lead.Address.city
State Lead.Address.state
Postal Code Lead.Address.postalCode
Main Phone Lead.Phone
Mobile Phone Lead.MobilePhone
Assignment Lead.OwnerId
Metadata Salesforce Lead ID and owner ID

Optional Status Mapping: Lead.Status can be transformed by removing spaces and replacing them with underscores when a matching OCC status exists.

The Salesforce Lead ID and user ID are retained as integration identifiers.

2. Opportunity Job and Appointment Mapping

An Opportunity requires an active mapped owner and a Primary Opportunity Contact Role. The association is normally Opportunity.OwnerId.

Standard Opportunity Field Mapping

OCC Destination Salesforce Source
Customer Name Contact.Name
Job Name Contact.Name + Opportunity.Name
Email Contact.Email
Lead Source Opportunity.LeadSource
Street Contact.MailingStreet
City Contact.MailingCity
State Contact.MailingState
Postal Code Contact.MailingPostalCode
Main Phone Contact.Phone
Home Phone Contact.HomePhone
Mobile Phone Contact.MobilePhone
Assignment Opportunity.OwnerId
Metadata Opportunity.Id, Contact.Id, owner ID
Important: Contact.HomePhone

Confirm that this field exists and is accessible through the connected Salesforce organization's API. An inaccessible or unsupported field can cause an INVALID_FIELD error and interrupt synchronization.

Event Appointment Mapping

Appointment Field Salesforce Source
Summary Event.Subject
Start Event.StartDateTime
End Event.EndDateTime
Notes Event.Description
Metadata Event.Id

Time Zone: Use explicit time zones because appointment date and time values may be interpreted as UTC.

Developer-Configured Extensions

  • Job Type: From an Opportunity multiselect field.
  • Additional Info: From a directly related Opportunity string field.
  • Status Mapping: Map Opportunity.StageName to matching OCC job states.

3. Custom Object Integration Design

Use a custom object only when the standard Lead or Opportunity integration cannot meet requirements. Design the configuration with OCC Support or Implementation.

SOQL Query Requirements

  • Provide one efficient SOQL query for recently changed records.
  • Account for updates to related objects that do not modify the Opportunity itself.
  • Include an Organization Mapping value so records reach the correct OCC location.

Legacy Query Pattern

WHERE LastModifiedDate >=

Job Mapping Definitions

Each mapping defines key and occ_value. Phone-number mappings also define label.

Destination Group Supported Examples
Job Identity name, customer_name
Contact email, lead_source
Address address_attributes.line_1, address_attributes.line_2, address_attributes.city, address_attributes.state, address_attributes.postal_code
Phones phone_numbers_attributes
Assignments assignments_attributes, additional_assignments_attributes
Integration Data metadata

Source Identity and Metadata

  • Opportunity record ID: metadata.integration.salesforce_opportunity
  • Lead record ID: metadata.integration.salesforce_lead

Preserve these identifiers when document push-back depends on the Salesforce record relationship.

Event Mapping

Define summary, notes, start_time, and end_time.

An identifying source field such as ServiceAppointments.first.Id can map to metadata.salesforce_service_appointment_id.

Include a separate outbound Push Back mapping when OCC changes must update Salesforce.

4. Outbound Updates, Documents, and Notes

Depending on configuration, OCC can update fields in Salesforce records.

Salesforce Object Configured Update Examples
Opportunity Lead source from job.lead_source
Contact Email, first name, last name, mailing address, mobile phone, and alternate phone
Account Name, phone, shipping address, and billing address

Custom Outbound Mappings

  • Opportunity and Account custom mappings require developer setup.
  • Job-type tokens use a directly related Opportunity multiselect field.
  • OCC job types must match Salesforce multiselect values.
  • Additional-info tokens require developer configuration.

Appointment Results and Status

When configured, appointment result and result-reason changes can immediately update Opportunity.StageName and Event notes.

Important: Changing an OCC job status does not automatically update Salesforce.

Documents and Notes

  • Document Attachment Preferences controls document push-back.
  • Note synchronization uses Salesforce ContentNote records.
  • Notes are linked to Orders and Opportunities.

5. Operational Behavior and Deletions

Scheduled Synchronization

Job synchronization runs at the following minutes after each hour:

:10   :25   :40   :55
  • Use Sync for a manual pull.
  • Salesforce API visibility can lag behind record updates by approximately one minute.

Deleted Salesforce Records

Deleting an Opportunity, Contact, Opportunity Contact Role, or Event does not automatically remove the corresponding OCC job or appointment.

The source association may instead become orphaned.

Ownership Changes

An ownership or association-key change is evaluated on the next synchronization only when the user mapping remains active and the source object is accessible to the integration.

6. Technical Troubleshooting

Initial Configuration Checks

  1. Verify the Salesforce integration shows Connected.
  2. Confirm at least one active mapped user exists.
  3. Verify the selected Job Object.
  4. Confirm the configured association key.
  5. Review all configured filters.

Lead and Opportunity Requirements

  • For Opportunities, verify a Primary Opportunity Contact Role.
  • For Leads and Opportunities, verify the owner or association points to an active mapped user.

When a Record Does Not Arrive

  1. Use Sync to request a manual pull.
  2. Allow for Salesforce API visibility delays.
  3. Review the next scheduled synchronization cycle.
  4. Inspect filters and source record values.
  5. Confirm object and field access for the integration user.

INVALID_FIELD and API Errors

An INVALID_FIELD error may indicate an inaccessible, unsupported, or misspelled field in a Salesforce query.

Validate the following:

  • Salesforce object schema
  • Field API name and availability
  • Integration-user field-level access
  • SOQL relationship paths
  • Custom queries and developer mappings

Escalate unresolved custom-query or field-mapping issues to the development team with the relevant Salesforce error and affected source object.

7. Final Technician Checklist

  1. Connection authorization confirmed
  2. Job Object and association key verified
  3. Active Salesforce-to-OCC user mapping confirmed
  4. Required Contact Role verified for Opportunities
  5. Source fields and API permissions checked
  6. Organization Mapping reviewed where applicable
  7. Integration metadata identifiers preserved
  8. Event mapping and time zones reviewed
  9. Outbound mappings checked if enabled
  10. Manual or scheduled synchronization tested
  11. Integration error logs reviewed
Remember

What you see can differ depending on your organization's settings and your permission level. Tab names, headers, and available options are configurable. If you cannot see or perform something described here, ask your manager first. They can contact support.