​
Overview

The SurveyCTO Integration module is where users connect SurveyStream to their SurveyCTO server.

Only Survey Admins can access this module and it is mandatory for all surveys.

​
Prerequisites

  1. Finish coding the main form on SurveyCTO

    The survey team should have a SurveyCTO server (refer to the SurveyCTO subscription details provided here) and the main form should be deployed on the server.

    Please refer to the main form requirements section below for important considerations while coding this form.

    Minor changes to the form after this step are acceptable. Major changes, such as a form ID update or the removal of questions used in later steps on SurveyStream, can cause errors and requires updating the configurations on SurveyStream. (Read more on this here.)

  2. Give SurveyStream access to the SurveyCTO server

    On SurveyCTO, grant “Data Manager” level access to the SurveyStream email surveystream.devs@idinsight.org, with the permission “Allow server API access” (refer to the SurveyCTO documentation here). This needs to be done only once for a SurveyCTO server.

​
Configuration

​
Key concepts

​
  Main form

In a data collection project, the form used to collect the data required for the study from the survey respondents is referred to as the main form. This term is used to distinguish the main form from data quality forms and admin forms.

A survey can have one or more main forms, depending on the types of respondents and how the survey is configured.

SurveyStream currently supports only one main form per survey. If there is more than one main form in the survey, each can be configured as a separate survey on SurveyStream. Kindly reach out to the SurveyStream team for more information.

​
Process

1

Enter main form and server details

The first step is to provide the form details, which include:

InputDescription
Main form IDSurveyCTO ID for the main form. This should match the form_id in the SurveyCTO form settings.
Main form nameLabel for the main form that will be shown in the SurveyStream web app and on SurveyStream-generated outputs (dashboards, media audit sheets). We recommend using the form_title in the SurveyCTO form settings.
SurveyCTO server nameName of the SurveyCTO server to connect to. For example, if the server is at idinsight.surveycto.com, the server name is idinsight.
Timezone of location of data collectionThe timezone in which data collection is being carried out. This is used to convert the timestamps provided by SurveyCTO from UTC time to the survey timezone for more intuitive reporting.

Select the appropriate checkboxes:

  • The form is encrypted. If yes, please share the key with surveystream.devs@idinsight.org via FlowCrypt/Nordpass.

    Select this only if your form is using SurveyCTO form encryption.

  • Please grant Data Manager access to surveystream.devs@idinsight.org on the SurveyCTO server with API access.

    Check this to confirm that SurveyStream has been given the required level of access to the SurveyCTO server.

  • I allow SurveyStream to connect to the SurveyCTO server as per the requirements of modules selected.

    Consent for SurveyStream to connect to your SurveyCTO server.

2

Map the SurveyCTO metadata fields

First, click on the Load questions from SCTO form button. This may take a few seconds as it loads the form definition from SurveyCTO and populates the dropdowns with the variable names.

Next, map the required metadata fields to their corresponding variable names in the SurveyCTO form. Details on these fields can be found in the main form requirements section.

Please refer to this section section below if you get errors when loading the questions.

​
Additional notes

​
Main form requirements

Ensure the main form has the following variables:

  1. Target ID - Unique alphanumeric identifier for the survey target (for example household ID, facility ID, etc).
  2. Surveyor ID - Unique alphanumeric identifier for the surveyor. This identifier needs to be created by the survey team and included in the SurveyCTO form.
  3. Survey status - A numeric variable indicating the status of the survey for the given target (for example, 1 for complete, 2 for partially complete, etc). The values in this variable should match the survey status values configured in the Survey Status for Targets module.
  4. Revisit section - (Optional) In case of partially complete surveys, this variable has the list of modules in the survey which are pending for that target.
  5. Location variables - Unique identifier for each of the location levels configured in the survey. Will only be enabled if you’ve selected features that require location information to be provided.

If there is any test or pilot data in the form, purge it before the start of data collection if it should not be included in the dashboard, emails etc.

​
Effect of form changes

Changes to the form after configurations on SurveyStream can lead to errors and unexpected outcomes. Kindly remember to make required changes on SurveyStream whenever the following changes occur:

  1. SurveyCTO server is updated

    • Update the server name on the form details screen
    • Grant the SurveyStream email access to the new SurveyCTO server
    • Contact the SurveyStream team to set up the server’s login credentials

  2. SurveyCTO Form ID is updated

    • Update the SurveyCTO form ID on the form details screen
    • Reload form questions on the questions mapping screen
    • Check if the question mappings are correct

  3. Question corresponding to a metadata field like Target ID, Survey Status etc. is updated

    • Reload form questions on the questions mapping screen
    • Update the question mapping on SurveyStream

  4. Questions used in other modules like Media Audits or Data Quality are updated

    • Reload form questions on the questions mapping screen
    • Revisit the modules to make required changes

​
Errors when loading the form questions

Here are some common errors and things to check when loading the form questions:

  1. The resource is not found..

    1. Check if the server name is correct
    2. Contact the SurveyStream team to verify whether the server’s login credentials are stored correctly

  2. Either Main Form ID is wrong or access is not given

    1. Check if the server name is correct
    2. Check if the SurveyStream email has been granted access to the SurveyCTO server
    3. Check if SurveyCTO form ID is correct

  3. An error was found on the choices tab of your SurveyCTO form definition. The choice list "..." has multiple choices with the value "...". Please update your form definition on SurveyCTO and try again.

    1. Check the choices tab in the form definition for duplicates values in the specified list.