Salesforce Integration

Chris Quiroz -

 


This document will go through how to set up the Salesforce integration, the logic behind push and pull actions, the limitations of our integration and best practices. For a PDF of this article,click here.

 

The key topics covered in this document are:

 

  • HOW DOES IT WORK
  • HOW TO ADD THE INTEGRATION
  • SALESFORCE ACTIONS
  • INTERPRETING INFORMATION
  • HOW TO TEST
  • BEST PRACTICES
  • RESOURCES

 

Who should read this:

 

This document was created to assist FluidReview clients, FluidReview Customer Engagement Representatives, and FluidReview Support Staff in setting up a Salesforce integration with FluidReview.



How Does It Work

  • Currently, the integration only allows for submission based information - this means that in order to push Contact information (i.e. fields from a User task), a submission must exist.
  • Information is collected within FluidReview in the way of creating, editing, or submitting a submission. This information can be mapped to the corresponding Salesforce field in the form of a “Push” action in our integration. This allows for a client to gain access to the fields that are most important to them from within their Salesforce environment, without having to access FluidReview.
  • If your client already has information on the applicant housed in their Salesforce, we can PULL this into their FluidReview submission, potentially eliminating the need  for the applicants to re-enter such information along with allowing for other unique use-cases to work with using FluidReview.

How To Add The Integration

  • Click the Configure your site icon on the left hand side, then choose Add Integration, then click Add Salesforce to your site
  • Enter the Name for the integration. Depending on your Salesforce setup, client will pick either Sandbox or Production. More details on this can be found here.

**NOTE: If this is your first time working with this integration, we recommend that you first integrate with your Sandbox environment to test, then later re-build a new integration with your Production environment.

  • You will be redirected to Salesforce to login to your account, and will then be redirected back to the newly created Salesforce integration in FluidReview.
  • Before clicking the blue “Save” button at the bottom of this page, you may wish to ensure that you are not currently signed in to any given Salesforce environment or else an integration will automatically be created for you using that account instead of the one that you had intended.

 

** NOTE: the account being used cannot be changed in the future. More information on this found in our best practices section.

 

Salesforce Actions

 

An Action is the link between an object in FluidReview and an object in Salesforce. Within the action itself you can specify when fields will be synced with your Salesforce account. Actions will require the following:

 

  • Select “Add Action”
  • Choose whether you want to create a PUSH or PULL action

 

PUSH Actions

 

Name - The name of the action. Most people use the name of the Salesforce object they are syncing to. 

When to sync - When should FluidReview sync the source object to Salesforce. The choices here are limited. For more advanced sync options, do not select anything here and instead use a trigger action to sync all or specific Salesforce actions based on any number of conditions.

Salesforce Object Type - Records that are created or updated by this action will be of an object type that is specified here.

Field Mappings - This section is for choosing which particular fields you want to map between the source and destinations objects.

  • Required fields may be found in PUSH actions and will appear automatically
  • There are a number of standard options available alongside form responses:
    • Doesn’t have a field to compare against - always uses the default field
    • Custom -  use specified default data option
    • Both User and Submission metadata fields
    • User Task fields are available (but cannot be pushed without a submission)

Unique - the unique field, if selected, will cause the system to check to see if an object already exists with the same value.

  • Also known as an “upsert” in Salesforce
  • Multiple fields can be specified as unique and then the match must be successful on all specified fields
  • All unique fields must have a value in order for the sync to work.
  • Does a search on the fields the first time the action runs.
    • If it does, it will update the existing object rather than create a new one, thus ensuring that only one record in Salesforce has that value.
    • This is commonly used with email addresses or IDs to make sure that duplicate records aren’t created for the same object.
  • This is case insensitive. If the field changed from from “fluidreview@surveymonkey.com”' to 'FluidReview@surveymonkey.com”' then the field will be updated; a new one would not be created.
  • If the unique field(s) has/have no value, then FR does not attempt to run the action.
    • The “unique” fields are seen as a unique identifier and they have to have a value; otherwise, we’ll end up with a lot of FluidReview objects pointing to the same Salesforce object.

 

Default data - Specifying a default value for the data will replace the value of a field with the value specified IF the source field being mapped doesn’t have a value. If mapping “Custom -  use specified default data option” as described above, the default data is always used.

 

File Attachments - If the selected Salesforce object type supports it, and if it is a Push action, you will be able to specify any file attachments that should be synced. File attachments are synced separately from the fields themselves, and the newly created Attachment object in Salesforce will be linked to the created record.

 

**NOTES:

  • You won’t be able to see your attachments in Salesforce until you enable the Notes and Attachments panel.
  • An attachment being edited will NOT activate a SF action in any case (created, edited or submitted).

 

 

Reviewers and Recommenders:

  • Reviewer and Recommender fields can be pushed as well
    • For scores, AEP must be used to calculate the score in a hidden field which is then mapped accordingly in the SF configuration
    • Multiple reviews on a single submission results in data getting pushed, being comma separated into a single record.

 

PULL Actions

  • Very similar to a PUSH Action, however we are pulling information from a Salesforce field into a FluidReview field.
  • A PULL action will only occur when the selected Salesforce field matches the mapped, corresponding FluidReview field
    • Metadata can be used with this as well
    • This means that we need to have this information in FluidReview first
  • Will not overwrite existing responses - this means that the pull will only occur once, there is no editing of a field to initiate another pull in the same form even if the responses are blank (as blanks are considered a response).
    • In the case of pulling information for one task based on the completion of a prerequisite task with a trigger to sync: user activates the trigger for a sync to occur but goes into the task before the information can be pulled in, the form responses will remain to be blank.
    • Pulls typically occur on the creation of the submission, however can also occur with the use of a trigger but must be set up correctly and with the understanding of the limitations as described above.
    • It has been noted that there could be the potential for a lag from the time of the trigger activation and sync to occur and the information to be pulled into FluidReview.

 

Trigger Activated Syncs

  • If you are using a trigger to sync on a specific activation (and to add conditions), typically you would leave all options (Created, Edited & Submitted) unselected.
    • The “Sync with Salesforce” action in Triggers will not appear until you add the integration

 

Relationships

  • We support Lookup fields (both optional and required) along with Master-Detail fields (you can read more about them here)
  • This is found under the “Field Mappings” area of the Push Action
  • You can choose to create a relationship between an already existing FluidReview Action and the Salesforce Field. The object must be the same in order to create the relationship.



Salesforce Settings & Manual Sync

 

Settings

 

  • Status - Whether or not the integration is active. If the Salesforce integration is not active, any existing actions will not sync to Salesforce.
    • This includes if the trigger was activated to sync with Salesforce
  • Name - The name of the Salesforce integration.
  • Environment Type - Whether or not the connected Salesforce is in production or sandbox mode.
    • Read only
  • Salesforce account user - The user of the connected Salesforce account. This will show both the name and email of the user.
    • Read only
  • Delete Integration - Deletes the integration
  • Refresh Salesforce schema - Your Salesforce schema is a reflection of all the objects available to you. Any time you create new custom fields or custom objects in Salesforce, you will want to see the changes reflected in your Salesforce integration within FluidReview. Changes are automatically updated once every day (cached for 24 hours), but to see your changes immediately click this button.
  • Send daily digest of Salesforce errors - When this setting is enabled, it will email a daily digest of any sync errors that have happened in the past 24 hours, with a link to the action log. If no errors have occurred in the past 24 hours, no email will be sent.




Manual Sync

 

Sometimes the Salesforce integration isn’t added to the FluidReview site until after some FluidReview records/data have already been created. If this is the case, you can perform a manual sync that will apply all active Salesforce actions to all the existing objects in the system. This includes triggers that are active.

For example, if you have Salesforce actions that will map a Submission owner’s name to a Salesforce Lead name, any existing submissions will sync to new Lead objects in Salesforce.

You can specifically run a manual sync on an unsuccessful action by selecting the same icon under the “Actions” column in the log (example pictured below). This will not manually sync other actions.

  • Manual Syncs should also update existing records in SF - this is helpful for retroactive fixes / updating information such as Reviewer scores.
    • Turn off all actions you do not want to run when doing a manual sync to help limit the API calls as much as possible
    • There are no limits on the number of manual syncs you and do. However, keep in mind the API calls that could be made with this
  • The action log provides a number of filters that allow you to see only the logs that you’re interested in, as well as a search field to find details regarding a known object that didn’t sync correctly.




Interpreting Information

  • The action logs will keep track of all communication between FluidReview and Salesforce.
    • After the SF integration was added, select “Configure your site > the name of the SF integration”
    • Select the tab “Logs”
  • The log itself will distinguish between successful, unsuccessful, and resolved transactions.
    • Successful - The transaction was successful. The sync did indeed happen, and all specified fields in the action have been synced.
    • Unsuccessful - The transaction was NOT successful. Error details are shown to provide insight into what the issue was. Beside the error message is an option to rerun the action. This gives you an opportunity to look at the error message, fix any errors either in the data or in the configuration, and rerun the action with the new data and configuration.
    • Resolved - If rerunning an error action is successful, the log item is marked as resolved. This allows you to be sure that the item is now successfully in Salesforce.

 

How To Test

 

In order to test properly and for troubleshooting purposes, it is recommended to start from scratch - create a new submission and follow the business process as created in FluidReview.

  • Ensure that the Salesforce integration action runs on the specified time (created, edited, submitted and triggered activations)
  • Check the logs found in the Salesforce integration
    • “Submission edited” in the integration will fire on “Task Edited”, “Submission Edited” and “Task Completed”
      • “Next” in a form task = task edited only after the form has been completed.
    • If using a trigger, ensure that it fired (watch the count / search in the activity feed)
    • In the logs, select the Date on which the action ran to see more information, such as the fields and the values. This will tell you whether or not the information was collected and pushed/pulled correctly.

 

Examples

  • Pull event, action was successful however no information was set up in the Salesforce side to be pulled into FluidReview:
  • Pull event, action was successful and information was available in FluidReview to pass to Salesforce
  • If unsuccessful, the Event Description will typically provide why and in some instances a recommendation to resolve it

**NOTE: The errors under the “Event Description” are coming directly from Salesforce

    • Fuzzy logic rules can also be created in Salesforce, however it appears that FluidReview will read this, it would be marked as “unsuccessful” and provide an error in the logs recommending to use the correct name: “You're creating a duplicate record. We recommend you use an existing record instead.” When the change occurs (the name was updated in Salesforce), a manual sync of the failed action can be used to run the action specifically for that submission again.
  • Fields in FluidReview and in Salesforce must match.
    • Troubleshooting; ask yourself: what are the differences between the FR and SF fields?
    • If we have a dropdown/checkbox/multiple choice (any single choice) question in the form on FluidReview, this needs to have a corresponding picklist field in Salesforce.
  • Validations in FR: If there is a validation in a FluidReview textbox question that is being pushed to Salesforce, the validation - or more typically the Custom Field - on SF must also be the same.
      • May be easier in most instances to remove the validation in FluidReview
      • PIPING: if there is piping in a FR field, the format of this may not match with the what is set in SF
        • Example: {{ date }} does not equal to the date format specified in the SF field - use a text response question with validation of MM/DD/YYYY or DD/MM/YYYY

 

 

Best Practices

  • The account being used to set-up the Salesforce (“You will be redirected to Salesforce to login to your account”) cannot be changed in the future.
    • If Admin Roles were added, ensure that the administrators have the proper permissions
      • Should have at the minimum API permissions enabled.
    • It’s always the account that setup the Salesforce site that should be setting up the integration, in which case they have access to everything and not limited by permissions, OR:
    • Use an account that isn't likely to change. This could be an account that has been set aside just for FluidReview, or for multiple integrations. Or if this isn't possible, that it be a generic admin account that won't change when staff come and go.
  • A sandbox environment should be used for testing purposes first
    • This will require the client to MANUALLY configure the production environment after - in some instances (quick turnaround) this may not be possible
  • Changes to a submission such as editing submission metadata and moving the submission from one stage to another do NOT activate the Salesforce action even if it’s on “edited”.
      • Create a trigger to sync with Salesforce on the activation
      • “Submission edited” in the integration will fire on “Task Edited”, “Submission Edited” and “Task Completed”
        • “Next” in a form task = task edited only after the form has been completed.
    • A SF Action on “Submitted” will fire with indirect submitting of the application - marking the submit task as “complete”, submitting via a trigger, bulk submit, submitting due to auto-apply functionality
  • On pull events for single-choice questions, the INDEX must be sent over from client’s Salesforce  (0, 1, 2, etc). This will not work if they are only sending a string.
  • FluidReview will complete two passes of the mapped fields in a Push action. Errors may occur on the first pass, however can be rectified in the second pass dependent on the order of the action.
    • Would show as a “Resolved” action.
  • Keep in mind triggers and manual syncs to control the number of API calls due to limitations as errors will occur if limit has been exceeded.
  • User task fields are limited to Applicant (submission) only; will not work for reviewers or co-applicants.

 

Resources

To report a bug/issue or to ask a Support question, please log into your site as an administrator https://yoursite.fluidreview.com/helpdesk/contact/ or https://example.yoursite.com/helpdesk/contact if you have a vanity URL.

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.