Salesforce Integration

Overview

The SiteCapture Salesforce integration supports the following scenario:

• An administrative user creates a field report in Salesforce and assigns it to a SiteCapture user.
• The field report is automatically pulled into the SiteCapture application.
• The SiteCapture user completes the report using the mobile app, and marks it complete.
• Data (including a report pdf and/or image zip file) is pushed back to Salesforce. 

This page gives an overview of the integration and then describes how to set it up in the SiteCapture application.  Before doing that, it is necessary to do some setup in Salesforce, which is described here (for the Salesforce Lightning UI) or here (for the classic UI).

Data Model

The SiteCapture integration with Salesforce is based on a particular data model, which is important to understand before creating a configuration as described below.

There should be two kinds of objects in Salesforce, which have a parent/child relationship.  The parent object is something like a customer account, or a particular property/site/installation where inspections or other work will be performed.  The child object represents the job to be done on the parent, like a field report, work order, inspection, repair, or estimate.  Throughout the remainder of this document, the child object will be referred to as a "field report".

(Note that the parent can contain multiple child objects.  For example, a site might require several inspections and/or several maintenance orders corresponding to different templates in SiteCapture.  For simplicity, the instructions below will just assume that a single "field report" template being used.)

The parent and field report Salesforce objects are used in the SiteCapture integration as follows:

Each field report in Salesforce is represented by a corresponding object in SiteCapture.  Parent objects are not represented in SiteCapture.

The Salesforce field report will specify the following:

• The SiteCapture template to be used for the field report
• The SiteCapture user that the field report will be assigned to
• The due date for the report to be completed in SiteCapture

SiteCapture will pull the field report from Salesforce and create it in SiteCapture.  Additionally, SiteCapture will pull any relevant data from the Salesforce parent object.  The data fields that are pulled from the parent object are determined by the pull field mappings specified in the integration configuration, which is explained below.  It may include information such as the property address, the name of the customer, etc.

Once the report has been completed in SiteCapture, data collected in the field will get sent back to the Salesforce parent object.  Which data gets sent back to Salesforce is specified by the push field mappings specified in the integration configuration.  Additionally, it is possible to also send some basic SiteCapture fields back to the child object.

Salesforce Setup

Credentials

The first step in establishing the integration between Salesforce and SiteCapture is to create a connected app in Salesforce and make note of the following parameters:  

• the Salesforce base url
• the Salesforce username and password that will be used to make the connection
• the Salesforce client ID and secret associated with the connected app

Instructions for creating the connected app in Salesforce and determining these parameters can be found here (for the Salesforce Lightning UI) or here (for the classic UI).

Objects

As described above, the SiteCapture/Salesforce integration requires the existence of a parent object and a field report object in Salesforce.  These may be either basic Salesforce objects, or custom objects.  There are no particular requirements regarding the parent object, but the field report object must contain a specific set of fields that are required by the SiteCapture integration.  In the descriptions of these fields below, note that the API name of each field is shown in parentheses, and this name must be created exactly as shown for the integration to work.

parent_id (parent_id__c)

The Parent_Id must be present on the child object as a formula field that refers to the parent object.

SiteCapture Template Key (fn_template_key__c)

The template key field will hold the key of the SiteCapture template that should be used to create the child object in SiteCapture.  It is specified at the time that the child object is created.  This field can be a free-form text field or a picklist containing the set of possible template keys.

sitecapture Status (fn_status__c)

The status field should be a picklist that at a minimum must include the value "NEW".  The picklist must also include any status values from the SiteCapture application which correspond to workflow states that trigger a push to Salesforce.   Most commonly, the COMPLETE workflow state will be configured in SiteCapture to push data, in which case the value of the corresponding status (most likely just "COMPLETE") should be included in the Salesforce picklist.

NEW is set by a user in Salesforce to indicate that the object should be pulled into SiteCapture and used to create a corresponding work order.  Other statuses are set by SiteCapture after the assigned user has made status changes on the work order in SiteCapture. 

SiteCapture Assigned User (fn_assignee__c)

The assigned user field can be a free-form text field or a picklist.  If it is a picklist, it should contain the set of SiteCapture usernames who are eligible to be assigned work.  (The username can be obtained from the "Users" tab underneath the "Admin" menu in SiteCapture.)

SiteCapture Due Date (fn_due_date__c)

The due date must be a date field.  It will be used to set the due date on the SiteCapture work order that gets created from the child object. 

Additional Optional Fields

In addition to the required fields listed above, the following fields can be configured to be pushed from SiteCapture to the field report object.  Any fields so configured in SiteCapture must be defined in the Salesforce field report:

SiteCapture Project ID (fn_project_id__c)

SiteCapture Assigned Manager Username (fn_manager__c)

SiteCapture Assigned Customer Username (fn_customer__c)

SiteCapture Priority (fn_priority__c)

SiteCapture Location (fn_latitude__c and fn_longitude__c)

All of the fields above can be defined as Text fields in Salesforce, except for latitude and longitude, which should be of type Number(3, 10). 

The screenshot below shows the complete set of required and optional fields and their data types:

sitecapture Setup

Creating A Template

The first step in setting up the integration in the SiteCapture application is to create the template that will be used for mapping Salesforce work to SiteCapture work.  This template can contain any number and type of fields, but there is one field that is required:

salesforce_parent_id

The Salesforce parent ID field will contain the ID of the parent object in Salesforce.  It should be a Text field, and  "Admin Only", so that nobody accidentally changes its value.

Once the template is created, note the keys of any fields that will be mapped to or from Salesforce.  These fields keys will be needed to configure the integration, as described below.

Configuring the Integration

Configuring SiteCapture for Salesforce Integration can be done on the "Salesforce Integration Settings" page, which can be found by selecting "Settings" under the gear icon in the top navigation bar and scrolling to the bottom of the Settings page.  If the link to the Salesforce Integration Settings page is not visible, please contact customer support to request that Salesforce Integration be enabled for your portal.

The first section of the integration settings page is "Salesforce Credentials".  Enter all of the fields required for connecting to the Salesforce API, as shown below. Please see the Salesforce setup page for instructions on how to obtain these values from the Salesforce admin website.

The next section, "Salesforce Object Names",  contains the names of the Salesforce parent and child objects described in the "Data Model" section above.  Note that the names of these objects must be specified exactly, with the proper case (upper/lower).

The next section, "Template Keys and WorkflowStates", can be used to specify lists of template keys and workflow states that participate in the integration.  In particular, when the status on a project in SiteCapture is changed to a new value, the SiteCapture application decides whether to attempt a push of data to Salesforce by applying the following rule:  If the template of the project has a key that is is in the list of specified template keys, and if the new status on the project is associated with a workflow state in the specified list, then the push will be attempted.  Note that for every workflow state that is specified, the corresponding SiteCapture status value must exist in the picklist for the Salesforce child object field called fn_status__c (see the "Objects" section of "Salesforce Setup" above.)

The "Field Mappings" section is used to establish mappings between SiteCapture template fields and Salesforce parent object fields, for both the "pull" and "push" directions.  Mappings created in the "pull" section indicate that data will be pulled from Salesforce into SiteCapture when a Salesforce child object is in the "NEW" state.  Those created in the "push" section indicate data that will be pushed from SiteCapture to Salesforce when a SiteCapture project enters a status with a configured workflow state, as described above.  SiteCapture template fields are designated by their keys, which can be obtained from the template editor (the field key appears under the field display name).  Salesforce object fields can be obtained from the Salesforce admin console.  The location of this page in Salesforce is different depending on whether the Salesforce object is a basic or custom one.  Note that for custom fields, the value of the "API Name" is what should be used -- this value typically ends in  "__c".

The "Child Push Fields" section is used to optionally specify basic SiteCapture fields which will be pushed to the Salesforce child object (the field report).  For every SiteCapture field that is selected, the corresponding field must exist on the Salesforce child object, with the name exactly matching the one shown on the SiteCapture settings page. (see the "Objects" section of "Salesforce Setup" above.)

The "Reports and Images" section is for specifying whether SiteCapture reports and/or zip files of images should be attached to the Salesforce parent object when the data is pushed.  The report that gets attached will be the one associated with the template that was used to create the SiteCapture project.  Both of these options have additional parameters associated with them (such as the ability to have timestamped photos);  these additional parameters become visible when the option checkbox is chosen.  Note that the report and image zip file are only pushed to Salesforce when the SiteCapture status represents a "complete" workflow state: either COMPLETE, COMPLETE_OTHER, or COMPLETE_REVIEWED.  For any other status change, only data are pushed.

Verifying Workflow

Once the integration setup is complete, it is a good idea to verify that data is flowing in both directions by executing the following sequence of steps:

1. Log in to Salesforce and create a new child object (inspection, work order, etc.)  Set the appropriate sitecapture template key, due date, and assignee, and set the status to NEW.
2. After 5 minutes, log in to the sitecapture web portal and look for a new item that was automatically created.  This can be done by using the Advanced Search and specifying the particular template that was designated above.
3. The new item should have the correct due date and be assigned to the correct user, matching what was specified in Salesforce.
4. Using the web portal (or having the assignee use the SiteCapture mobile application), complete all the relevant fields.  Once the work is complete, set the status to the value that was configured to push to Salesforce (see Configuring the Integration above).
5. After 1 minute, log in to Salesforce again and find the parent of the child object that was created in step 1 above.  Verify that the object's fields have been updated with the data from SiteCapture.  In the "Notes and Attachments" section, verify that the report and/or photo zip file have been attached, depending on how the integration was configured.  If any fields were configured to be pushed to the child object, verify that those have also been updated in Salesforce.

Once these steps have been successfully executed, both directions of data flow have been verified, indicating that the configured integration is working correctly.