Skip to content

SurveyCTO Integration

In this section, we describe how to set up a SurveyCTO survey that integrates with your BACE application to optimally select questions.

Note: these instructions are in the process of being updated.

Note

Internet connectivity is required in order to run a SurveyCTO survey connected to BACE.

The list of API calls and how to find <your-URL> are in List of API calls.

Prior to working through this section, make sure you have created and deployed your own BACE application.

You should be familiar with working with SurveyCTO. We also provide links to some helpful SurveyCTO resources.

Setup your SurveyCTO form and BACE connection

Download the Survey Components

Create a new SurveyCTO form

  • Navigate to the Design tab from SurveyCTO.
  • Click "Add Form, Group, or Dataset".
  • Click "Upload form definition"
  • Add the survey form definition to the Form definition section.
  • Select "Attach filed?" → "Yes"
    • Add the bace.fieldplugin.zip file to this.
  • Mark whether you want to deploy the survey immediately or upload as a draft.
  • Click "Upload"
  • Update the field plug-in parameters (See section below.)
  • In particular, update the bace_url variable to reference the "<your-URL>/surveyCTO". This is necessary to connect the plug-in with your application. The url should be saved in quotes.
  • To update additional parameters, follow the steps below:
    • Scroll down to the field titled "bace_response"
    • Click "Edit this field"
    • Update the plug-in parameters. Add a comma separated list of key = value. To reference variables from other fields, use ${variable_name}.
    • Click "Save now" to save changes.

Once you have set this up, your SurveyCTO form will be connected to your BACE application.

Understanding your SurveyCTO form

Data Format

Each field stores a pipe (|) separated list of the options presented to the respondent; the final element of the string records the index of the option that the respondent selected. (Note that options are zero-indexed so 0 → Profile 1, 1 → Profile 2, ...)

The field plug-in maps this string to display a table of choices to the user.

Consider the following field:

"Price,$5.45,$5.44|Ink Color,blue,black|Pen Type,Ballpoint,Ballpoint|1"

The design displayed to the user would reflect the information shown in the table below. The final element of the string indicates that Profile 2 (the second option) was selected by the respondent.

Profile 1 Profile 2
Price $5.45 $5.44
Ink Color Blue Black
Pen Type Ballpoint Ballpoint

Parameters

Key Value
bace_url (required) String. Specifies the url to your BACE application. It should specify "<your-URL>/surveyCTO".
unique_profile_id (required) String. A unique uuid that is associated with an individual. By default, this is created using once(uuid()) in a calculate field at the start of your survey.
previous_choice (required) String. The choice selected by the respondent on the previous question. Calculated within a repeat group as if(index()=1, null, indexed-repeat(${selected_choice}, ${bace_repeat}, index() - 1)).
final_question (required) Integer (1/0). Indicates whether this is the final API call. Survey example calculates this as index() = ${n_scenarios} + 1.
display_estimates_page (optional) Integer (1/0). Indicates whether posterior estimates should be displayed to the user after the final API call.
split_to_rows (optional) String. Defaults to \|. Separator for breaking response into table rows. This should match this split_to_rows variable in /app/bace/user_surveycto.py.
split_to_vars (optional) String. Defaults to :. Separator for breaking a row into columns. This should match the split_to_vars variable in /app/bace/user_surveycto.py.
n_options (optional) Int. Defaults to 2. Number of choice options to display to the respondent.
button_label (optional) String. Defaults to Choice. Label for each option.
profile_enumerator (optional) String ("number" or "letter"). Defaults to number. Indicates how options should be enumerated. number -> Option 1, Option 2, ... or letter -> Option A, Option B, ...
loading_message (optional) String. Message to display to users while BACE questions load. Defaults to "Your choice scenario is loading.\nWe appreciate your patience."
answers (optional) Comma-separated string of answer values. Defaults to "0,1" or "0,...,(n_options-1)" if n_options>2. This should map to the answers variable that is defined in the user_config.py file from your BACE application.
buttons_per_row (optional) Int. Defaults to 3. Formats the number of answer buttons per row.
add_to_request_vars (optional) String separated by commas. Use this to add additional variables that will be sent to your BACE application with each query. Provide the name of each variable separated by commas. Add these new variables to your field plug-in as keys. E.g. add_to_request_vars = 'foo,bar', foo='hello', bar='world!' will make it so that foo and bar are sent to your application and stored in the user's profile upon creation. Note: variables are only saved in the profile for the first call.

Examples

Here is an example appearance for your text field that uses this field plug-in:

BACE SurveyCTO Appearance Example

Developer Notes

A general user needs only to upload the field plug-in integration/SurveyCTO/bace.fieldplugin.zip as an attachment to their survey form in order to use the plug-in. However, some users may need to edit the plug-in to handle additional functionality for their experiment.

Please see SurveyCTO's developer documentation for more details on how to edit or create a new field plug-in that uses this code.

After you make changes to the source files, zip the source folder into a new plug-in as <plug-in-name>/fieldplugin.zip. Upload this new plugin to be used with your form and call it in the bace_response question field.

Acknowledgments

Initial code for this plug-in was built using logic from Survey CTO's Conjoint field plug-in.