Getting Started

This integration allows for the export survey data from the FocusVision Decipher survey platform directly into Dapresy using the Decipher REST API and Dapresy Data REST API.

 

Beta status


The first release of the integration is a Beta, we expect to see issues as the integration is adopted. These will be fixed as soon as possible.

 

IMPORTANT – COMPATIBILITY WITH ORIGINAL FOCUSVISION DECIPHER INTEGRATION AND FILE BASED IMPORTS!

The Decipher v2 integration is not directly compatible with the earlier FocusVision Decipher integration or other sources. The metadata will not match, as the question codes and answer values are derived differently, the respondent id is created with a different mechanism from the UUID it is therefore not possible to start using the v2 integration in projects that have previously used other data sources without large modifications to the metadata or by using extensive mapping in the MDT during import and at the very least a complete import of data to update respondent id’s.

Pre-Requirements

In order to use this API, you will need to have an account on the Focus Vision Decipher platform with the API feature enabled. This will allow you to create an API key. An API key is a mandatory parameter for this integration to Dapresy. Please refer to the FocusVision documentation for details on how to generate a key. It should be 64 characters long and consist of the public and private key. This key should be treated as you would a password.

Using the System

Your administration account will need access to the integration in Dapresy. If you do not see the FocusVision Decipher V2 in the list of integrations and you believe it should be available, you will need to request access from your Customer Success Manager or Account Manager.

 

Setup Integration

To setup the data source adapter, the scheduled task in other words, complete the following tasks:

Task 1: Go to the Data Integration Scheduler screen


To access the Data Integration UI in Dapresy, please follow these steps after creating or selecting the appropriate project:


Select the Data tab from the main menu

Capture1.PNG



Click on the arrow under Import data, then select Schedule imports from the dropdown menu.

Capture2.PNG

Then the Data Integration UI will open.


Task 2: Create the Scheduled task


Your first scheduled task is automatically created when you access the Import Scheduler screen for the first time. This screen contains all the setup controls for the new data source adapter instance. Some of these parameters are mandatory, and some are optional.

When you access this screen for the first time, if you wish to give it a name rather than the default value enter the required name and check the Active checkbox. If you do not add a name an automatically generated name will be applied.

After the first scheduled task has been created, you can create more data scheduler tasks for the same project with different configurations. To create a new scheduler task, just click the ‘Create new’ button.

 

The import schedule configuration form will be cleared for new parameters and configurations. Also, if you need to delete a task, simply select the task you would like to delete from the Selected import schedule dropdown list and then click the ‘Delete selected’ button.

 

Task 3: Set Data Import Scheduler


Every Import Scheduler job can be scheduled to be triggered just once or to be repeated based on one of the following schedules:

  • Hourly
  • Weekly
  • Monthly

You can select the schedule type from the ‘Import type’ dropdown menu on the Import scheduler UI.

 

NOTE: When the ‘Run import on save’ checkbox is selected, then the import job will be triggered immediately after the Save button has been clicked. Scheduled jobs will also be saved for the time that you select. You may wish to set the scheduled time to run in the past to prevent the task running again or inactivate your scheduler after initial import.


Task 4: Choose Data Source


To select a Data Source for your Data Adapter, use the Data source dropdown menu. This dropdown list contains all data sources that users have access to.

 

By default, the data source is set to the FTP Server, but this should be changed to FocusVision – Decipher V2. When FocusVision – Decipher V2 is selected as the data source, then the configuration form will be loaded.

 

Task 5: Set up Data Source


 

 

 

To set up the FocusVision - Decipher data source, you need to create an API key. To learn how to do this, see prerequisites, in this manual (above)


 

To setup FocusVision - Decipher V2 integration, follow these steps:


  1. Enter your API key from FocusVision, this should be 64 characters long.

  2. Set the base URL.

  3. Click the ‘Load survey list’ button. If the list loads you entered the correct key and URL. If there is an error check the values entered in step 1 and 2.

  4. The survey list will be populated with all surveys from FocusVision – Decipher that are linked to the provided API key.

  5. Select the desired survey, and the Survey path field will be populated.

  6. Survey layout, choose which layout template to use. This is optional and there may be no layouts defined.

  7. Layout selected will be shown.

  8. Optionally select which variables to include, you can preview all the variables in the MDT (please refer to relevant documentation on MDT usage). This defaults to importing all variables.  I.E. if you leave this field empty all variables will be imported.

  9. The filter expression allows you to filter the data downloaded. Here you can select response status filters, default is qualified, others are terminated, overquota and partial. To import all respondents including partial, the filter would be:
    “qualified or partial or overquota or terminated”

  10. Apply exclude flags to remove system variables - the types supported are v, x, t :
    v -- this is a “virtual” (computed) variable rather than recorded while taking the survey.
    x -- this is an "execute only" question, i.e., it is filled out during the survey but using code (e.g. prefill/autocode/autofill)
    t -- this is a "transient" question, which usually indicates something auto-generated by the system (so for example, variables like qtime for interview time, vos / browser for operating system / browser assignment etc)

  11. Select time period the selected survey's data. Select this from the Time period dropdown. If nothing is selected, then the system will load data from all respondents. If a specific date range is needed, then select the ‘Static’ option from time period dropdown.


The Start and End date controls will appear. Simply check the Start and End date check boxes and choose the specific dates from the calendars.

 

If incremental updates are required to be run at a regular interval use the Auto option.

Set import to Auto, use the “date” variable from the survey and set date format to MM/dd/yyyy hh:mm:ss 


 

We recommend using a date time variable, as this makes it possible to correctly retrieve the newly added responses in the survey. Using ResponseDate will only filter on date, as it is stored as a date, rather than the time of day. This can cause issues with missing responses.

System Variables


The RespondentID is mapped from UUID, the same UUID will always give the same numeric value.

ResponseDate is taken from the system “date” variable in Decipher, if missing it is taken from

“start_date”, if also missing it will default to current date time.

Weight will be assigned to value 1 unless there is a variable named weight in the survey, that will be used instead.

Metadata Transformation


The final step is to create the metadata definition. Typically, this is used for eliminating unwanted variables (e.g. system information such as browser version or screen resolution), search and replace updates on codes and texts, fixing answer texts in multiple choice questions, fix any errors on import etc. 

Please refer to general Dapresy documentation for further details on the metadata transformation function.

After completing these steps, the data adapter will be configured ready to use. The last step is to click ‘Save at the end of the Import scheduler UI.

 

After completing this, the FocusVision - Decipher Data Adapter will be configured ready to use. The last step is to click ‘Save at the end of the Import scheduler UI.

 

Using Layouts to Resolve Issues


You can use layouts in Decipher to exclude variables which are not required for reporting (aside from the flag exclusions (v,t and x) and include variable options described above).

The layout function also sets sort order of variables.

If there is an issue importing data, and the error relates to a specific variable you can use the Decipher layout feature to exclude the affected variable.

Care should be taken not remove required variables with layouts. E.G. UUID and date. Removing UUID will cause the import to fail as this the unique identifier for the responses. “date” is required to have the correct response date.

 

Stacked Data Support


Any stacked data will be loaded automatically. Activation will include stacked data. Any logic for last “x” batches will include stacked data associated with the regular data batches. The number of main data batches will match the number of batches selected for activation. If you have one main batch and three stacked data batches in each import, selecting to activate last 2 batches will result in 2 main data batches and 6 stacked data batches (2 * 3) being activated.

Iterators, the keys for the loop, are identified to be used in Dapresy.

Supported Controls

 

Typically, questions repeat to represent both columns and rows. For instance, a multiple choice defined with 4 rows and 3 columns will generate 4 multiple choice questions each with 3 answer options.

 

Scale questions are transferred as single choice (non-scale) but values are correctly transferred. To use the values as factor average values in Dapresy use the questions screen to change question type to single choice scale.

 

Control Name

Imported as

Comments

Single Select

Single Choice

 

Multi Select

Multiple Choice

 

Dropdown Menu

Single Choice

 

Button Single Select

Single Choice

 

Single Select Grid

Single Choice 

 

Button Single Select Grid

Single Choice

 

Button Multi Select

Multiple Choice

 

Multi Select Grid

Multiple Choice

 

This or That

Single Choice

Generates 1 single choice per pair, and 1 single choice per concept labelled left or right with suffix “l” or “r”

Text

Open Ended Text

 

Essay

Open Ended Text

 

Number

Open Numeric

 

AutoSum

Open Numerics

One open numeric per cell, excludes totals

Date Picker

Open Date

 

AutoSuggest

Open Ended Text

One open ended for ID and one for TEXT

Button Rating

Single Choice

 

Star Rating

Single Choice

 

Card Rating

Single Choice

 

Slider Rating

Single Choice

 

Slider

Single Choice

 

Rank Sort

Single Choice

 

Card Sort Single Select

Single Choice

 

Card Sort Multi Select

Multiple Choice

Multiple choice per card

Net Promoter Score

Open Numeric

One per row

Audio Player

Not applicable

 

Image Map

Open Ended

A set of co-ordinates in a single open ended field – this is not natively supported in Dapresy

Media Evaluator

Not applicable

 

Page Timer

Not applicable

 

Page Turner

Not applicable

 

Shopping Cart

Open Ended Texts

A set of open ended text questions recording Quantity, Click Order, Seconds Viewed for each item

Text Highlighter

Single Choice

One per word with default options Positive, Neutral, Negative

Video Player

Not applicable

 

Video Player (You Tube / Vimeo)

Not applicable

 

Image Upload

Open Ended

Supports creating a web variable in respondent tables, this will generate thumbnails dynamically and allow click to view original image

Audio Testimonial

Open Ended

 

Video Testimonial

Open Ended