Configure a Survey to Push to Salesforce

Before we get started, it needs to be understood that Salesforce is highly configurable and customisable, so we will need to speak in general terms, as far as the Salesforce side. We make no assumptions about how the reader has set up Salesforce, and this guide assumes the reader is familiar with their own Salesforce instance configuration.

To start, open the survey you want to integrate by selecting it from the dashboard or My Surveys page.

You then need to access the survey settings by clicking "settings" from the white bar on the survey design page.

On this page, you will find the options to create a new push integration for the survey. This can be either to a Salesforce instance or a Sandbox.

Each push integration can only target one object in Salesforce. If you need to push data from a single survey into multiple objects, you’ll need to create a new integration for each object.

If a survey has multiple integrations, then you can set the order in which they are executed by clicking the "Reorder:" switch in the upper-right of the configured integrations list and then dragging and dropping the integrations into the desired order of execution, top to bottom.

Creating a New Integration

Click “Configure” to create a new integration.

The interface will ask you for a name for your integration, and for you to choose a target Salesforce account or sandbox for it.

Clicking “Continue Setup” will bring up the next stage of integration.

On the setup screen, you can edit the name of the integration, and whether it is enabled or disabled.

Under the Disable / Enable switch, you can choose the object in your Salesforce instance that you want to target.

The "Triggers on" option defines what will cause the integration to sync the survey response to Salesforce. The integration can be set to trigger, or not, when a response is Completed, Disqualified, or Updated.

Choosing an Action

You can choose the specific action that you want the integration to undertake – Insert, Update, or “Upsert”.

Insert – Add a new entry as the chosen object type.

Update – Change an existing record with new data.

Upsert – Change an existing record with new data, unless no existing record is found, in which case a new record will be created.

All of the above will update the fields within the targeted (or new, in the case of insert) object as defined on the “Field Mapping”

Setting up an Insert

When you choose the “Insert” action, you can proceed straight to field mapping.

Setting up an Update

An update action needs to target a specific record to update it, when you choose the option, a new option will appear for you to define this using an ID. This ID is the alphanumeric code that appears in the URL after the Object name when viewing the record in Salesforce. In most circumstances, you’re likely to be piping this from a custom variable or contact list column, but the dialogue allows you complete freedom in how you go about this.

Once set up, proceed to field mapping.

Setting up an Upsert

Upsert is the most flexible of the options, as such, it has the most complex setup.

When Upsert is chosen, you will be prompted to choose an external field and an ID value for that field. This is basically telling the integration A: where to look, and B: what to look for.

The external field name is chosen from a drop-down list, which will show all the fields set up on the chosen object. You need to ensure that the one you choose is configured as an External ID in Salesforce.

Once you have selected the field name to target, then the second drop-down for External Field ID is where you define the value that is targeted. This works in the same way as the field mapper.

After completing the Fields, choose a Push Trigger.

Note: While Upsert is flexible, it has two important limitations – you cannot search for just anything, only in fields that have been configured as an "external" field. Secondly, you cannot use upsert to change the value that you’re using to identify the record.

Choosing a Push Trigger:

Below the action selection fields, there is a section titled "Triggers on".

This is a selection of three checkboxes which set when the integration will actually try and push data to Salesforce.

You can set the integration to trigger when the response is first completed, when the response is edited, or when the response is marked as disqualified (or any combination of the above). Which of these you will want to choose is dependent on the specific purposes of the survey, the integration, and the targeted object.

Note - Using "Trigger on Update" on an "Insert" integration will attempt to create a new record every time the survey response is updated. It will not up update an existing record, so be careful when using these options in conjunction.

Field Mapping

The field mapping dialogue works in the same way for all three actions.

You can map several fields, but they must all be from the same object.

To map a field, you will need to choose two things. One is the data from SmartSurvey that you wish to send to Salesforce, and the second is where you want to store it in the Salesforce object.

Selecting the SmartSurvey Data:

This is a drop-down menu that works in a similar way to the “Piping” dialogue. When you click on it, you will be able to choose to use any of the following:

  • All answers the respondent has given to the survey
  • Any Contact list data for the respondent
  • Any Custom Variables based in to the Survey via URL
  • Various Survey Metadata such as ID, title, etc.

Custom Value. This allows you to manually set in the value.

This can be static (useful for testing) or uses the same syntax as would be used for piping. To add piped values, click the pencil icon next to the lower field when this is selected and follow the onscreen instructions.

This can be used to combine multiple values into a single field, for instance if your form has separate fields for first name and last name, but your salesforce is set up to have full name as a single field, then you could combine them using this feature, by simply using the piping code for “first name” and then the code for “last name”, separated by a space.

Selecting the Salesforce Field

This drop-down shows all the fields on the targeted object. Simply choose your intended destination for the data.

Mapping More Fields

Once a field has been napped, click "Add Another Mapping" to create a new one, and repeat the process as many times as needed to map everything you need.

Ordering the Field Mapping

You can use the arrow icons to the left of each row of the field mapper to change the order that the the fields appear on screen.

 

Completing the Integration

The Integration should be activated by clicking the "Enable" button.

Once enabled, you will be able to check the status of the integrations on the integrations settings page, including the number of successful and failed events. Clicking the "view details" button for the integration will allow you to see further details.

With this window open, clicking "Events" will show a log of the most recent 250 events, marked as whether they were successful or not. To see the data payload that was transmitted by the event, then click the small question mark icon. This will include any error messages that were returned by a failed event.

Testing and Managing the Integration

By clicking "View details" next to each integration, you can see an overview of how the integration is set up, and an event log.

The Event Log will show the most recent 250 sync events, whether they were completed or failed, along with other information about the event.

To the right, are two or three icons.

  • Question mark in a circle - View or edit event data.
  • Circular arrow - Retry event
  • Trash bin (only appears for failed events) - Delete event.

Viewing and editing event data

Clicking the circular arrow will show the request data payload that was sent to Salesforce, and below it the result that was received.

By Default, the request data view is collapsed, but can be expanded by clicking on the small grey triangles.

The result will show any error messages that were received in the event of a failed sync, and other information if successful, such as the ID of a newly-created record in the the event of a successful insert.

You can edit the request data by clicking the "Edit Request Data" button. This will load a dialogue box allowing you to manually amend any of the data sent to Salesforce. Clicking "Save And Retry" will save the changes and retry the sync. Clicking "Save" will just save the changes and if you want to retry the sync, then you can do it using the icon on the list view.

Editing the Event data will not change the data in the survey itself.


Was this guide helpful?