Salesforce Data Synchronization and Troubleshooting
Technical data mapping, custom-object design, outbound updates, operational behavior, and troubleshooting reference.
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 |
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 |
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 |
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.StageNameto 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.
Documents and Notes
- Document Attachment Preferences controls document push-back.
- Note synchronization uses Salesforce
ContentNoterecords. - Notes are linked to Orders and Opportunities.
5. Operational Behavior and Deletions
Scheduled Synchronization
Job synchronization runs at the following minutes after each hour:
- 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
- Verify the Salesforce integration shows Connected.
- Confirm at least one active mapped user exists.
- Verify the selected Job Object.
- Confirm the configured association key.
- 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
- Use Sync to request a manual pull.
- Allow for Salesforce API visibility delays.
- Review the next scheduled synchronization cycle.
- Inspect filters and source record values.
- Confirm object and field access for the integration user.
INVALID_FIELD and API Errors
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
- Connection authorization confirmed
- Job Object and association key verified
- Active Salesforce-to-OCC user mapping confirmed
- Required Contact Role verified for Opportunities
- Source fields and API permissions checked
- Organization Mapping reviewed where applicable
- Integration metadata identifiers preserved
- Event mapping and time zones reviewed
- Outbound mappings checked if enabled
- Manual or scheduled synchronization tested
- Integration error logs reviewed
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.