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.
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 must include the following values: NEW and COMPLETE. The picklist can also include other values, but the two mentioned above are required for the FotoNotes integration. 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. COMPLETE is set by the FotoNotes application after the assigned user has completed the work 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 fields have been created.
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 it is suggested that the field be "Admin Only", so that nobody accidentally changes its value.
Once the template is created, the author should note the keys of any fields that will be mapped to or from Salesforce fields. These fields keys will be needed to configure the integration, as described in the next section.
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". This is where to enter all of the fields required for connecting to the Salesforce API including URL, username, password, client secret, and client ID. 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.
The "Field Mappings" section is used to establish mappings between FotoNotes template fields and Salesforce 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 "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.
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.
Once these steps have been successfully executed, both directions of data flow have been verified, indicating that the configured integration is working correctly.