The FotoNotes Salesforce integration supports the following scenario:
- An administrative user creates a field report in Salesforce and assigns it to a FotoNotes user.
- The field report is automatically pulled into the FotoNotes application.
- The FotoNotes user completes the report in the field using the FotoNotes mobile app, and marks it complete.
- Data from the FotoNotes report (and optionally a report and/or image zip file) is pushed back to Salesforce.
The FotoNotes 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 FotoNotes. 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 FotoNotes integration as follows:
Each field report in Salesforce is represented by a corresponding object in FotoNotes. Parent objects are not represented in FotoNotes.
The Salesforce field report will specify the following:
- The FotoNotes template to be used for the field report
- The FotoNotes user that the field report will be assigned to
- The due date for the report to be completed in FotoNotes
FotoNotes will pull the field report from Salesforce and create it in FotoNotes. Additionally, FotoNotes 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 FotoNotes, 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 standard FotoNotes fields back to the child object.
The first step in establishing the integration between Salesforce and FotoNotes 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 at the Salesforce Setup page.
As described above, the FotoNotes/Salesforce integration requires the existence of a parent object and a field report object in Salesforce. These may be either standard 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 FotoNotes 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.
The Parent_Id must be present on the child object as a formula field that refers to the parent object.
FotoNotes Template Key (fn_template_key__c)
The template key field will hold the key of the FotoNotes template that should be used to create the child object in FotoNotes. 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.
Fotonotes 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 FotoNotes application which correspond to workflow states that trigger a push to Salesforce. Most commonly, the COMPLETE workflow state will be configured in FotoNotes 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 FotoNotes and used to create a corresponding work order. Other statuses are set by FotoNotes after the assigned user has made status changes on the work order in FotoNotes.
FotoNotes 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 FotoNotes usernames who are eligible to be assigned work. (The username can be obtained from the "Users" tab underneath the "Admin" menu in FotoNotes.)
FotoNotes 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 FotoNotes work order that gets created from the child object.
The screenshot below shows what the field report object should like once all required fields have been created.
Additional Optional Fields
In addition to the required fields listed above, the following fields can be configured to be pushed from FotoNotes to the field report object. Any fields so configured in FotoNotes must be defined in the Salesforce field report:
FotoNotes Project ID (fn_project_id__c)
FotoNotes Assigned Manager Username (fn_manager__c)
FotoNotes Assigned Customer Username (fn_customer__c)
FotoNotes Priority (fn_priority__c)
FotoNotes 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).
Creating A Template
The first step in setting up the integration in the FotoNotes application is to create the template that will be used for mapping Salesforce work to FotoNotes work. This template can contain any number and type of fields, but there is one field that is required:
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 FotoNotes 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 FotoNotes is changed to a new value, the FotoNotes 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 FotoNotes 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 FotoNotes 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 FotoNotes when a Salesforce child object is in the "NEW" state. Those created in the "push" section indicate data that will be pushed from FotoNotes to Salesforce when a FotoNotes project enters a status with a configured workflow state, as described above. FotoNotes 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 standard 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 standard FotoNotes fields which will be pushed to the Salesforce child object (the field report). For every FotoNotes field that is selected, the corresponding field must exist on the Salesforce child object, with the name exactly matching the one shown on the FotoNotes settings page. (see the "Objects" section of "Salesforce Setup" above.)
The "Reports and Images" section is for specifying whether FotoNotes 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 FotoNotes 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 FotoNotes status represents a "complete" workflow state: either COMPLETE, COMPLETE_OTHER, or COMPLETE_REVIEWED. For any other status change, only data are pushed.
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:
- Log in to Salesforce and create a new child object (inspection, work order, etc.) Set the appropriate Fotonotes template key, due date, and assignee, and set the status to NEW.
- After 5 minutes, log in to the Fotonotes 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.
- The new item should have the correct due date and be assigned to the correct user, matching what was specified in Salesforce.
- Using the web portal (or having the assignee use the FotoNotes 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).
- 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 FotoNotes. 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.