Salesforce Integration FAQ - Jobs

Jobs

What information is required to have a job created in OCC when the Job Object is configured as a Lead?

When the Job Object is configured as a Lead for the integration, the following process happens:

1. The user from Salesforce MUST be mapped to a user in OCC and their mapping must be active.
2. We then iterate over all of the active Salesforce Users we have mapped and look for appointments based on the association key (e.g. OwnerId, or whatever is configured) in the Lead.
3. For each lead, we utilize the following mapping to create a job in OCC:
   1. Customer Name: {lead.Name} 
   2. Name: {lead.Name}: {lead.ProductInterest__c}
   3. Email: {lead.Email}
   4. Lead Source: {lead.LeadSource}
   5. Job Address:
      1. Line 1: {lead.Address.street}
      2. City: {lead.Address.city}
      3. State: {lead.Addres.state} (there is a mapping to validate it is in the correct format)
      4. Postal Code: {lead.Addres.postalCode}
   6. Status: In the event the integration is configured to update the status, the following is done:
      1. Status is set to lead.Status.delete(‘ ‘).underscore (in the case that the status matches on in OCC)
   7. Phone Number (lead.Phone):
      1. Name: Main
      2. Number: {lead.Phone}
   8. Phone Number (lead.MobilePhone):
      1. Name: Mobile
      2. Number: {lead.MobilePhone}
   9. Assigned User: lead.OwnerId (Based upon the mapping set up in the integration)
   10. Metadata:
       1. salesforce_lead:: {lead.Id}
       2. salesforce_user_id: {lead.OwnerId}

What information is required to have a job created in OCC when the Job Object is configured as an Opportunity?

When the Job Object is configured as a Lead for the integration, the following process happens:

1. The user from Salesforce MUST be mapped to a user in OCC and their mapping must be active.
2. We then iterate over all of the active Salesforce Users we have mapped and look for appointments based on the association key (e.g. OwnerId, or whatever is configured) in the Opportunity.
   1. The integration also looks for the Contact which is identified which is identified as “Primary”.
3. For each Opportunity, we utilize the following mapping to create a job in OCC:
   1. Customer Name: {contact.Name}
   2. Name: {contact.Name}: {opportunity.Name}
   3. Email: {contact.Email}
   4. Lead Source: {opportunity.LeadSource}
   5. Job Address:
      1. Line 1: {contact.MailingStreet}
      2. City: {contact.MailingCity}
      3. State: {contact.MailingState}
      4. Postal Code: {contact.MailingPostalCode}
   6. Phone Number (contact.Phone):
      1. Name: Main
      2. Number: {contact.Phone}
   7. Phone Number (contact.HomePhone):
      1. Name: Home
      2. Number: {contact.HomePhone}
   8. Phone Number (contact.MobilePhone):
      1. Name: Mobile
      2. Number: contact.MobilePhone
   9. Assigned User: opportunity.OwnerId
   10. Metadata:
       1. salesforce_opportunity_id: {opportunity.Id}
       2. salesforce_contact_id: {contact.Id}
       3. salesforce_user_id: {opportunity.OwnerId} (or whatever is set up in the integration)
   11. Job Type(s):
       1. The token job_type configuration must be setup by a developer
       2. The column must be a multi select within Salesforce
       3. The column must be directly associated with the Opportunity
       4. Create the job types within One Click to match the values in the multi select within Salesforce
   12. Status: {opportunity.StageName}
       1. The org job states must be set up by a developer to match the Opportunity StageName stages by a developer
       2. Enable Opportunity Status Update through the Salesforce UI
   13. Additional Info:
       1. The token additional_info configuration must be setup by a developer
       2. The column must be a string within Salesforce
       3. The column must be directly associated with the Opportunity
   14. Appointment:
       1. Summary: {event.Subject}
       2. Start Time: {event.StartDateTime}
       3. End Time: {event.EndDateTime}
       4. Appointment Note Text: {event.Description)
       5. Metadata:
          1. salesforce_event_id: {event.Id}

What information is required to have a job created in OCC when the Job Object is configured as Custom?

There is a custom configuration which is available to be able to customize the object(s) utilized to push/pull information to/from Salesforce. If the customer requirements cannot be met by the default Salesforce integration, this can be an option through consulting with OCC. If the data is available via a Salesforce SOQL query call, the information can be pulled and pushed from One Click Contractor.

When configuring a “custom” Salesforce integration, there are a few things that are required:

1. SOQL Query for Jobs: There needs to be a SOQL query which can be run to get a list of records that have been updated for importing / updating into OCC. The goal is to make the query as efficient as possible and be able to be run in a single query every 15 minutes. In order to help make the query more efficient, there is a value which can be added to the query which can be utilized to help filter records.
   1. For example, you can utilize something like WHERE LastModifiedDate >= to help filter and include only records that were updated since the last sync. One thing to keep in mind is that IF there are multiple records you have in the query you may need to make sure you check updates to each of them as it is common for updates to an Account not to update an Opportunity, etc.
2. Organization Mapping: There must be a value that is present on the object we’re utilizing from Salesforce that is set to a value we can map to identify the location in OCC. That value MUST be present in the SOQL query (mentioned below) and a value must be set in the OCC Org Metadata for mapping.
3. Job Mapping: There will need to be a configuration which will allow the system to know how to map data from Salesforce to the job / address / phone number(s) in OCC.
   1. For each of the values, there are at least 2 properties which need to be defined:
      1. Key (key): The value corresponding to the SOQL query for the job that we’re pulling data from
      2. OCC Value (occ_value): The field on the OCC Job this data will map to.
   2. Here is a list of the OCC values which can be configured:
      1. Name (name): The name of the job
      2. Customer Name (customer_name): The customer’s name on the job
      3. Lead Source (lead_source): The lead source on the job
      4. Email (email): The email address for the customer
      5. Address Line 1(address_attributes.line_1): The first line of the job’s address
      6. Address Line 2 (address_attributes.line_2): The second line of the job’s address
      7. Address City (address_attributes.city): The city for the job’s address
      8. Address State (address_attributes.state): The state for the job’s address
      9. Address Postal Code (address_attributes.postal_code): The postal code for the job’s address
      10. Phone Number: There can be multiple phone numbers added to the job. In this case, there are 3 values which need to be set:
          1. Key, occ_value, and label
          2. For example, if you’re pulling a phone number off of an account and you want to call it “Mobile” you would utilize the following configuration:
             1. key: Account.Pnone
             2. occ_value: phone_numbers_attributes
             3. label: Mobile
      11. Assignment (assignments_attributes): The user we will be assigning the job that is created to. By default, this utilizes the OwnerId value from the record but can be overwritten in the configuration.
      12. Additional Assignment (additional_assignments_attributes): The user that will be brought over as the “secondary” assigned user on the job.
      13. Metadata: This is where you can set up a record(s) you wish to store the identifying values back to the job. If you wish to make use of the default ability to push a document back to either the opportunity or lead object, you will want to utilize either of the following configurations:
          1. Opportunity: Set the values as follows:
             1. key: Id (or whatever the field is in the SOQL query for jobs to identify the opportunity)
             2. occ_value: metadata.integration.salesforce_opportunity
          2.  Lead: Set the values as follows:
             1. key: Lead.Id (or whatever the field is in the SOQL query for jobs to identify the opportunity)
             2. occ_value: metadata.integration.salesforce_lead
4. Event Mapping: There will need to be a configuration which will allow the system to know how to map data from Salesforce to an appointment in OCC.
   1. For each of the values, there are at least 2 properties which need to be defined:
      1. Key (key): The value corresponding to the SOQL query for the job that we’re pulling data from
      2. OCC Value (occ_value): The field on the OCC Job this data will map to.
   2. Here is a list of the OCC values which can be configured:
      1. Summary (summary): The title of the appointment
      2. Notes (notes): The description of the appointment
      3. Start Time (start_time): The start date/time of the appointment (ensure it is specified in the appropriate time zone as it will be assumed to be UTC if not specified).
      4. End Time (end_time): The end date/time of the appointment (ensure it is specified in the appropriate time zone as it will be assumed to be UTC if not specified).
      5. Metadata: You will want to provide at least one metadata field to store the id. For example, if utilizing the first ServiceAppointment associated with a record you might have a configuration such as:
         1. key: ServiceAppointments.first.Id
         2. occ_value: metadata.salesforce_service_appointment_id
5. Push Back to Salesforce: A configuration/mapping of pushing data back to the record in Salesforce when it is updated in OCC.

Are there any options for other mappings for job creation?

There are additional options for mappings that are custom.

When should an update in Salesforce be reflected in OCC?

There is a job that runs every 15 minutes at 10, 25, 40, and 55 minutes after the hour.

What happens if an Opportunity, Contact, or Opportunity Contact Role is deleted in Salesforce?

The information created in OCC would be orphaned and unlinked between Salesforce and OCC. There is no update to reflect that in OCC and no updates will be pulled to a job(s) in OCC.

What happens if an Event is deleted in Salesforce?

Much like if an Opportunity, Contact, or Opportunity Contact Role is deleted in Salesforce, NO update for appointment(s) will be pulled to a job(s) in OCC.

Do updates in OCC push back to Salesforce?

Yes, there are options for information to be pushed back to Salesforce. In the integration configuration, there are options for different types of updates back to Salesforce.

• Opportunity
  • Default Data:
    • {opportunity.LeadSource} - job.lead_source
  • Job Type
    • The token job_type configuration must be setup by a developer
    • The column must be a multi select within Salesforce
    • The column must be directly associated with the Opportunity
    • Create the job types within One Click to match the values in the multi select within Salesforce
  • Additional Info:
    • The token additional_info configuration must be setup by a developer
    • The column must be a string within Salesforce
    • The column must be directly associated with the Opportunity
  • Custom Mapping:
    • The custom opportunity mapping must be setup by a developer
    • Any information that is related to job (organization information) can be mapped to a column on the Opportunity
• Contact
  • Default Data:
    • Email: job.email,
    • FirstName: first_name,
    • LastName: last_name,
    • MailingStreet: job.address.line_1,
    • MailingCity: job.address.city,
    • MailingState: job.address.state,
    • MailingPostalCode: job.address.postal_code,
    • MobilePhone: number_map.mobile,
    • Phone: number_map.first_alternate
• Account
  • Default Data:
    • Name: job.customer_name
    • Phone: job mobile phone OR first alternate - finds a number in job.phone_numbers to send to Salesforce
    • ShippingStreet: job.address.line_1
    • Name: job.customer_name
    • ShippingStreet: job.address.line_1
    • ShippingCity: job.address.city
    • ShippingState: job.address.state
    • ShippingPostalCode: job.address.postal_code
    • BillingStreet: job.address.line_1
    • BillingCity: job.address.city
    • BillingState: job.address.state
    • BillingPostalCode: job.address.postal_code
  • Custom Mapping:
    • The custom opportunity mapping must be setup by a developer
    • Any information that is related to job (organization information) can be mapped to a column on the Account

Can I make status changes in OCC and have them show up in Salesforce?

Yes, there are 2 options for getting status changes in OCC back to Salesforce.

Option 1: Currently, there is an ability to update a result and result reason on an appointment in OCC and have that reflected back in Salesforce "immediately". There is NO ability to change the Job’s status in OCC and have that reflected back in Salesforce.

Under the appointments tab, for each of the appointments that come over from Salesforce will have an option to result each of those appointments.

After selecting the icon to result it gives you the ability to select a result and notes to save the changes.

Once that change is saved it is accessible on the Opportunity and Appointment back in Salesforce.

• Result will update the Stage of the Opportunity back in Salesforce.

• The notes which are entered on the result screen will also show back up in Salesforce on the Event.

Is there anything else that happens when an appointment is resulted?

Yes, the Opportunity.StageName is updated AND the event.notes are updated on the associated Salesforce event.

What happens when I change the owner (or other association key) on the Job Object (Opportunity or Lead) in Salesforce?

Once the association is changed in Salesforce, it should be picked up on the 15 minute synchronization timeframe. Please note the SAME rules still exist where there must be a user linked between OCC and Salesforce AND it must have been updated since the last synchronization.

Please note that with changes made in Salesforce, those updates may take upwards of a minute or so to reflect and be made available to the API for us to pull down.