Skip to main content

FV Decipher Support

All the topics, resources needed for FV Decipher.

 
FocusVision Knowledge Base

Integrating the Automated Database Management System

The Automated Database Management system (ADB) allows us to capture Sample data that we already have available in survey. For example, if we have a Sample file containing contact details for our respondents - a First Name, a Last Name, and an e-mail address, we can use the ADB system to capture that data for each respondent. The ADB system uses a unique variable assigned to each respondent called source, to locate and match-up the corresponding data for them. This source variable is automatically generated by our Email Campaign Manager, once we upload our Sample list in order to send out our survey invites.

Note: The source variable is the only one that can be used with the ADB system.

1:  Creating/Uploading the Sample File

1.1:  File Format

The format of the Sample File we are going to use for our ADB set-up should conform to the same requirements as uploading a Sample File in our Campaign Manager - either an excel file or a tab-delimited text file. Each separate field in our file should have a column header. The Sample file should always have a list column, which needs to contain values corresponding to one of our sample sources. For example, if we only have one Sample Source that has list=”1” as an attribute, we will need to have a list column that contains 1 for each respondent in our sample file. Click here to download an example structure file that we can upload to our Campaign manager.

1.2:  Uploading the File

Since we want the system to generate a unique source variable for each record in our sample file, we will upload our list to our Campaign Manager, and later reference it from the Campaign Manager in survey. In order to upload the file, we need to create a new e-mail campaign and upload our list into that campaign.

2:  Referencing the List

Once we have the list uploaded, we can reference it in our survey by adding the lists=”mail” to our survey tag:

<survey 
  alt="ADB TEST"
  autosave="0"
  compat="133"
  extraVariables="source,record,ipAddress,decLang,list,userAgent"
  lists="mail"
  mobile="compat"
  mobileDevices="smartphone,tablet,featurephone,desktop"
  name="Survey"
  setup="term,decLang,quota,time"
  state="testing">

Since our sample file is uploaded to the Campaign Manager, the location of that file is in a folder called mail. Specifying lists=”mail” tells the system to look for files in that specific folder when trying to match up a respondent’s source to a specific record. If multiple lists are uploaded to Campaign Manager, the system will look in each separate file to try and locate the source variable that a respondent is using. When using lists=”mail”, the system will look for a match in any file that starts with the word “list” and is situated in the mail directory.

3:  Setting up the Samplesources

3.1:  Enabling the ADB System

For any samplesources that are going to use the Automated Database System to pull data for respondents, we need to add adb=”1” inside the samplesource tag:

 <samplesource adb="1" list="1">
    <title>Client Sample</title>
    <invalid>You are missing information in the URL. Please verify the URL with the original invite.</invalid>
    <completed>It seems you have already entered this survey.</completed>
    <exit cond="terminated">Thank you for taking our survey.</exit>
    <exit cond="qualified">Thank you for taking our survey. Your efforts are greatly appreciated!</exit>
    <exit cond="overquota">Thank you for taking our survey.</exit>
 </samplesource>

3.2:  Capturing the Source Variable

After we have uploaded our sample file, a source value will be generated for each record in our file. This source value will be appended to each respondent’s survey link. For example, if our survey link is:

http://uk.focusvision.com/survey/selfserve/214e/160701

A respondent with a unique source variable coming into our survey will be coming using a link similar to the below:

http://uk.focusvision.com/survey/selfserve/214e/160701?source=6xEVWhULbJ

In order to use this source value as a key to reference the data for each respondent, we need to make sure we are capturing the source variable in our survey. We can achieve this by adding source as a samplesource variable to any samplesources we have that will use the ADB system:

<samplesource adb="1" list="0">
    <title>Client Sample</title>
    <invalid>You are missing information in the URL. Please verify the URL with the original invite.</invalid>
<var name="source" unique="1"/>
    <completed>It seems you have already entered this survey.</completed>
    <exit cond="terminated">Thank you for taking our survey.</exit>
    <exit cond="qualified">Thank you for taking our survey. Your efforts are greatly appreciated!</exit>
    <exit cond="overquota">Thank you for taking our survey.</exit>
</samplesource>

4:  Accessing the Data

4.1:  Accessing the Data Using Python

We can use python code to access the data for the current respondent. For example if we want to pipe in the first name of our respondent from a column called fName, we can use the below syntax:

adb.fName

If we have a column header in our sample file that doesn’t follow python naming syntax (e.g. no spaces, or special characters), for example a column named “last name”, we can use the below syntax instead, to access information for that column:

adb["last name"]

Putting all of the above together, we can create a personalized welcome message for each of our respondents, by using Python piping:

<html label="cm1" where="survey"> Welcome to the survey, ${adb.fName} ${adb["last name"]} !</html>

Additionally, we can use exec blocks to populate questions with the data from our sample file. Let’s say we have a column called segNo with 4 different segments for our respondents, valued 1-4.

We can create the following question to capture the segment each respondent falls into:

<radio 
  label="hQ1"
  where="execute,survey,report">
  <title>Hidden Segment Tracker</title>
  <comment>Select one</comment>
  <row label="r1">Segment 1</row>
  <row label="r2">Segment 2</row>
  <row label="r3">Segment 3</row>
  <row label="r4">Segment 4</row>
</radio>

And use the following exec block to populate our question:

<exec>
hQ1.val = int(adb.segno)-1
</exec>

One thing to note here is that all values read from our sample file are read in as string variables, so if we are looking to extract numeric values, we will need to convert them to integer values first, using int().

4.2:  Saving the Data Directly in a Question

An alternative way to store the data from our sample file is to build our questions in a similar fashion to using a <datasource> tag. Instead of assigning the value of a question with an exec block, we can use the dataSource=”” attribute to specify where our question will pull its data from. If we add dataSource=”adb” to our question the system will automatically know to look for data for this question in our sample file. We then need to add another attribute called dataRef which would tell the system which row to reference when pulling the data. For example, if we want to reference our “segno”  column in the sample file that we have, we can add dataRef=”segno” to our question, so that we pull the data for that specific column:

<radio 
  label="captureSegmentNumber"
  dataSource="adb"
  dataRef="segno"
  where="execute,survey,report">
  <title>Capture Respondent’s Segment</title>
  <comment>Select one</comment>
  <row label="r1">Segment 1</row>
  <row label="r2">Segment 2</row>
  <row label="r3">Segment 3</row>
  <row label="r4">Segment 4</row>
</radio>

The above method will only work for numeric data contained in our Sample file. If we want to capture alphanumeric data, or text data, we would need to add a dataValues=”” attribute to our question. For example, if we want to capture our respondent’s gender, but we have “male” and “female” as values in our gender column, we can create the below question:

<radio 
  label="hGender"
  dataSource="adb"
  dataRef="segno"
  where="execute,survey,report">
  <title>Capture Respondent’s Gender</title>
  <comment>Select one</comment>
  <row label="r1" dataValue=”female”>Female</row>
  <row label="r2" dataValue=”male”>Male</row>
</radio>

4.3:  Capturing the Data in a Virtual Question

To create a virtual question pulling data from the sample file, we can build on the set up from section 4.2 - to make a question that is already pulling from our sample file, we just need to add the dataVirtual=”1” attribute to that question. Doing this to our previous question results in the below:

<radio 
  label="vGender"
  dataSource="adb"
  dataRef="segno"
  dataVirtual=”1”
  where="execute,survey,report">
  <title>Capture Respondent’s Gender</title>
  <comment>Select one</comment>
  <row label="r1" dataValue=”female”>Female</row>
  <row label="r2" dataValue=”male”>Male</row>
</radio>

5. Putting It All Together

Putting all of the previous examples together, we can create a survey that shows every example of pulling data from a sample file:

<survey 
  alt="ADB TEST"
  autosave="0"
  compat="133"
  extraVariables="source,record,ipAddress,decLang,list,userAgent"
  lists="mail"
  mobile="compat"
  mobileDevices="smartphone,tablet,featurephone,desktop"
  name="Survey"
  setup="term,decLang,quota,time"
  state="testing">

<samplesource adb="1" list="0">
    <title>Client Sample</title>
    <invalid>You are missing information in the URL. Please verify the URL with the original invite.</invalid>
<var name="source" required="1"/>
    <completed>It seems you have already entered this survey.</completed>
    <exit cond="terminated">Thank you for taking our survey.</exit>
    <exit cond="qualified">Thank you for taking our survey. Your efforts are greatly appreciated!</exit>
    <exit cond="overquota">Thank you for taking our survey.</exit>
  </samplesource>

<html label="cm1" where="survey"> Welcome to the survey, ${adb.fName} ${adb["last name"]} !</html>

<suspend/>

<exec>
hQ1.val = int(adb.segno)-1
</exec>

<radio 
  label="hQSegment"
  where="execute,survey,report">
  <title>Hidden Segment Tracker</title>
  <comment>Select one</comment>
  <row label="r1">Segment 1</row>
  <row label="r2">Segment 2</row>
  <row label="r3">Segment 3</row>
  <row label="r4">Segment 4</row>
</radio>

<suspend/>

<radio 
  label="captureSegmentNumber"
  dataSource="adb"
  dataRef="segno"
  where="execute,survey,report">
  <title>Capture Respondent’s Segment</title>
  <comment>Select one</comment>
  <row label="r1">Segment 1</row>
  <row label="r2">Segment 2</row>
  <row label="r3">Segment 3</row>
  <row label="r4">Segment 4</row>
</radio>

<suspend/>

<radio 
  label="captureGender"
  dataSource="adb"
  dataRef="segno"
  where="execute,survey,report">
  <title>Capture Respondent’s Gender</title>
  <comment>Select one</comment>
  <row label="r1" dataValue=”female”>Female</row>
  <row label="r2" dataValue=”male”>Male</row>
</radio>

<suspend/>

<radio 
  label="vcaptureGender"
  dataSource="adb"
  dataRef="segno"
  dataVirtual=”1”
  where="execute,survey,report">
  <title>Capture Respondent’s Gender</title>
  <comment>Select one</comment>
  <row label="r1" dataValue=”female”>Female</row>
  <row label="r2" dataValue=”male”>Male</row>
</radio>

</survey>
  • Was this article helpful?