3.3 Surveys

What is Survey?

A survey defines critical aspects of a post’s structure and permissions. For example, a post’s “survey” defines which fields are available for contributors to complete, and who can see it when it’s published.

This section will show you how to create and manage surveys on your deployment.

The setup in this guide is demonstrated in the below video as well. You can watch and follow the guide at the same time!

Pre-Requisites

Before configuring the survey on your platform, you'll need to install Ushahidi's platform and set up your deployment. You can complete this task by referring to the following resources:

Make sure you are logged in to your deployment page.

Setup guide

Video tutorial for accessing surveys

To access the Surveys configuration page, on the sidebar, click on Settings

Settings link highlighted in a Ushahidi deployment sidebar

Then, click on Surveys

"Surveys" link in the deployment settings page.

3.3.1 Building Surveys

By default, each deployment has a Basic Post survey, which can be deleted or modified as needed. To create a new survey:

Video setup guide for Building surveys

Click on Add Survey as shown below.
In the upper right corner of the survey form, you will see the default language that your deployment is currently in. Check Chapter 3.3.2 on how to change a survey's default language
Fill in the required details:
- Survey Name: Try being as specific as possible when creating your survey name so that users will understand what they are selecting when creating new posts
- Description: Provide a brief description of what kind of data you’ll be collecting with this survey
- Fields + Tasks: See below for details on how to add fields and tasks into your survey.
- Click on save once you're done building your survey.

Add Survey button highlighted In the Surveys page.

Change Surveys Default Language Drop Down Highlighted In The Add Survey Page to show on how to change a survey's default language

See chapter 3.3.2 on how to translate your survey

Video setup guide for duplicate surveys

To duplicate a survey

On the surveys settings page where you have a list of surveys:

Click on the bulk actions button
Check/select the survey(s) you would like to duplicate
Then click on the duplicate button or icon.

Click on the Bulk Actions button and then select surveys to delete.

Click on the "Duplicate" button in the contextual bar. This will duplicate your survey.

3.3.1.1 Fields

Video setup guide for managing fields

Each survey you create will have a title and description field by default. It's important to note these fields can be edited, but cannot be deleted.

Different Types Of Field

Short Text: Short Text field is designed for brief, single-line responses—typically a sentence or less. This field is particularly useful when you need concise information.

For example, in a flood report survey, you might ask a simple question like: "What is the estimated water level during the flood?" Here, a Short Text field would capture specific, brief inputs like "3 feet" or "1 meter."

Long Text: Long Text field is ideal for capturing more detailed responses, such as paragraphs or multiple sentences. This field is perfect when you expect users to provide in-depth feedback or explanations.

For example, in a flood report survey, you might ask: "Can you describe the impact of the flood on your home and surroundings?" In this case, the Long Text field would allow respondents to give a detailed response like: "The flood caused significant damage to our home. The water reached the first floor, destroying furniture and appliances. Roads were also submerged, cutting off access to emergency services for several days."

Number(Decimal): This field is designed to capture numerical inputs, which include decimal values. This field is useful when precise numerical data is needed.

For example, you might ask: "What was the total cost of flood damage in dollars?" Here, the Number (Decimal) field ensures respondents can enter exact monetary figures like 1500.75, making it easy to record detailed financial data.

Note: Number will not accept any kind of alphabet and Special symbol for example $.

Number(Integer): The number (Integer) field is designed to capture numerical inputs, which are whole numbers. This field can be useful for the answer which will obviously be a whole number.

For example, you might ask: "What is your age?" Here, the Number field ensures respondents can enter the whole number as inputs.

Note: Both Number (Decimal & Integer) fields don't accept digits greater than 10, so respondents cannot add country codes if the field is requesting phone numbers.

Location: This field allows users to share geographic data. This field can provide a map interface, enabling respondents to select their location or manually input latitude and longitude coordinates. This is particularly useful when collecting precise location data.

For example, in a flood report survey, you might ask: "Please provide the exact location of the flood impact." When using the Location field, a map will appear in the survey. Respondents can either click on the map to mark their location or can manually move the cursor on the map for exact latitude and longitude values, such as 28.6139° N, and 77.2090° E. This data is valuable for creating accurate, location-based reports.

Date: This field allows respondents to select a specific date, providing them with a calendar interface where they can adjust the month, date, and year according to their requirements. This is particularly useful when you need time-related information.

For example, in a flood report survey, you might ask: "When did the flooding start in your area?" Using the Date Field, respondents can open the calendar, navigate through the months and years, and select the exact date. The default value will be the current date when the form is filled, but users can easily modify it to reflect the appropriate date of the event.

Date and Time Field: This allows respondents to select both a specific date and the exact time using a calendar and time picker interface. This field is useful when you need precise information that includes both the day and the time of an event.

For example, in a flood report survey, you might ask: "When did the floodwaters start rising in your area?" Respondents can select the date from the calendar and then adjust the time by choosing the exact hour and minute, such as August 15, 2024, 03:30.

Select: This field provides respondents with a set of predefined options to choose from. These options are created by the admin. Respondents will see a drop-down arrow, which they can click to reveal the available choices. Only one option can be selected from the list.

For example, in a flood report survey, you might ask: "What is your preferred method of receiving flood alerts?"
In the Select Field, respondents can click the drop-down and see options like:
SMS
Email
WhatsApp Message

The respondent can then select the one option that best fits their preference.

Radio Button(s): The Radio Buttons Field is similar to the Select Field, but the key difference is that all options are visible on the form itself, rather than being hidden in a drop-down menu. Respondents can view the options directly and select only one.

For example, in a flood report survey, you might ask:
"What is your current living condition after the flood?"
In the Radio Buttons Field, the options might appear like this:
Staying at home
Temporarily relocated
In a shelter
With relatives

The respondent can select the most accurate option by clicking the corresponding radio button.

Checkbox(es): These allow respondents to choose one or more options from a predefined set. Unlike radio buttons, where only one option can be selected, checkboxes enable users to select multiple options if applicable.

For example, in a flood report survey, you might ask:
"Which resources do you currently need?"
The Checkboxes Field could have the following options:
Food
Water
Medical Supplies
Shelter
Clothing

Here, the respondent can select multiple options based on their needs, such as both Food and Water.

Related Post: The Related Post Field allows you to create a connection between different surveys by linking relevant posts. This is particularly useful for cross-referencing data from various surveys. However, it’s important to note that only posts that have been published will appear in the search results when linking; posts that are "Under review" will not be visible for selection.

For example, in a flood report survey, you might want to relate a previous disaster preparedness survey to understand how preparedness impacted the flood response. Using the Related Post Field, you can link the two surveys, enabling easy access to relevant data across surveys.

Image: The Image Field allows users to upload images to the post, with a maximum file size of 10.00 MB. To add an image, respondents can click the Add photo button and select the desired image from their device. Additionally, there's an option to include a caption for the image, allowing users to provide a brief description or context for the uploaded photo.

For example, in a flood damage report, respondents could upload images showing the extent of the flood's impact and add captions like: "Floodwaters reaching up to 3 feet in the living room."

Note: Always add an image, if you add a caption. Respondents can't submit the form by adding only a caption WITHOUT uploading the image.

This feature is particularly useful when visual documentation is needed to support the report.

Embed Video: The Embed Video Field allows users to embed videos from platforms such as YouTube or Vimeo directly into the post. Respondents simply need to paste the video link (URL) into the provided field. This feature is useful for sharing visual content that supports the post or survey data.

For example, in a flood damage report, respondents could include a YouTube video showing the flooding in their area. This allows for more dynamic and detailed reporting, providing a clearer visual context alongside written information.

3.3.1.1.1 Adding Fields

You can add as many custom fields to your survey as you see fit. To add a new field, click on the Add Field button.

Click On Add Field Button To add custom fields In the survey.

A pop-up box with a list of different field types will appear on your screen. Choose whichever one will work best for the type of data you are trying to capture.

A pop-up box with a list of different field types ,such as short text, long text, location, number, date, date & time, select - a drop down list of items.

Add the following details for which ever field type(s) you select:

Name: This is what is displayed as a label for your newly created field
Add field description (optional): A visual editor should appear below, you may add help text that provides additional details about this field.
- Add some text in the description-editor, format it however you want to, and as long text as you want to.
Required: If set to yes, post submission will be only be successful once this field has been filled out. If set to no, post submission will be successful even if it has not been filled out.
Make responses private: This allows limiting access to responses to this field to specific users.
Default Value: You can set a default value displayed every time someone is creating a new post. example, a survey asks whether you want to subscribe to a service, and it has a default value of 'No'. If you submit without changing this value, the default value will be submitted as 'No' when you save the survey. If you change to 'Yes', the value that will be submitted will be 'Yes'. That's the value that will be submitted when the survey is saved. Note: For fields where it's possible to add a default value (all field-types except "image", and "categories"), the default value box should be displayed with no toggle-switch
Field Options: This appears in cases where you’re creating a checkbox, select or radio button field. You can add as many options as you would like.
Once you’re done, click on Save.

Adding a field form with name, field description fields, highlighting required and make responses private toggle button.

Note that, the description should have the same formatting as it did in the field description editor. To confirm this:

Add a new post to this survey you just created
Save the post
Go to data view
Select the post you added and select "edit"
The field description you added will be visible.
The description should have the same formatting as you did in the editor

3.3.1.1.2 Editing Fields

Video Setup Guide for Editing Fields

To edit an existing field:

Select the desired custom field by clicking on it
Edit the fields (as described in the section above on Adding fields) as desired.
Click on Update when done.

Editing a survey's fields.Highlighted field: Location

Modal with field editor. Edit the field name and display options.

You can also change the position of existing fields by dragging the field with the scroll icons to the left of every field as shown below.

Sorting the fields of a survey with Up and Down arrow in the survey editor.

3.3.1.1.3 Deleting Fields

Video setup guide for Deleting Fields

To delete an existing field

Click on the trash icon adjacent to the field you'd like to delete.
A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete the field
- Click on Delete to delete the field
- If you’d like to cancel the field deletion process, click on Cancel

Deleting survey fields with the "trash" icon in the survey editor.

3.3.1.2 Tasks

You can organize your survey into “Tasks”, allowing a deployment to add fields related to actions that need to be taken, like translation or verification. These groups of tasks are visible to specified users and can be marked as ‘complete.’ For example, if a particular survey requires verification upon submission, you can design a task to ensure your team knows the post needs to be verified before publishing. The task could include fields like whether the information was verified or not, who verified the information, how they verified it, and when they verified it. After verification, the task can be marked as complete and the post can either be moved to the next task if necessary, or published.

3.3.1.2.1 Building Tasks

Video setup for Building Tasks

To add a new task:

Click on Add Task on your survey creation/edit page
A small pop up box will appear, prompting you to give your task a name
If you’d like to make this task required before post submission, switch on the Require this task be completed before a post can be visible to the public toggle. This means that, a post will not be published until this task is marked as complete
Click on Add

Click On Add Task Button To add custom fields In the survey.

Add task modal displaying a form with "Task name", "Task description" and task completion requirements.

Once set up, you can duplicate your task as follows. Adding task fields

You should be able to add fields to tasks in the same way that you add fields to a survey.

Highlighted Add Fields button to tasks in the survey editor.

Please refer to the Fields section of this manual for details on how to add, edit, and delete task fields.

3.3.1.2.2 Configuring tasks

Video setup for Configuring tasks

To make additional configurations to your task, click on the Configure tab

Set the following options

_Required: _When set to yes, this task must be set as complete for successful post-submission
Task is only for internal use: This limits the visibility of this task during submission only to teams with permissions to manage posts on your deployment i.e only internal team members will be able to submit responses to this task
_Show this task to everyone when published: _This limits the visibility of task responses when viewing submitted posts if not enabled i.e. it limits the visibility of responses to tasks to internal teams only.

Survey task options highlighted in the tasks editor. Highlighted 3 toggle buttons, Required, This task is only for internal use, Show this task to everyone when published

This is what it would look like when applied to your survey form later on:

A page showing an Example of a Task. Highlighting task name, task completed off toggle button, location and task description.

3.3.1.2.3 Editing Tasks

To edit an existing task:

Scroll down to the desired task
Make changes as desired, e.g changing the task name, description, and/or making a task required or not
When done, click on Save at the bottom of the page

Editing a survey's tasks. Build, configure and edit the task fields.

3.3.1.2.4 Deleting Tasks

Video setup for deleting tasks

To delete an existing task

Scroll down to the desired task
Select Delete Task button

3.3.2 Translating Surveys

Once the survey form has been created and all the required fields have been filled, you can translate the survey into other languages if you want to. Below are a video and written setup guides to help you.

Note: You can add more than one language

Written Setup Guide

Click on Add translation at the upper right-hand corner of the survey form.

Edit Survey page with arrow in red pointing to Add Translation button

A pop-up module will appear on your screen, select the language(s) you want to translate to using the checkboxes beside the language names.

Choose Language Translation Page with a list of checkboxes of available languages to choose from. Select the language to translate your content into

Then:

Click on Add to finish.
You will be redirected to a survey form with the translatable content in the default language and fields where you can add your translations
On the empty fields, translate the survey details into the chosen language e.g in the above image the default language is English and the added language is French.

Chosen language in this example is French. French language is chosen in the drop down menu.

On the survey, you will then be able to see the available languages that the survey has been translated into.

Available languages that the survey has been translated into.Languages drop down menu is highlighted.

Similarly you can see this translate dropdown to select a language to translate to on the post edit form in the data view:

Available languages that the survey can be translated to in Edit Post section.Languages drop down menu is highlighted.

3.3.2.1 Translating Fields

To translate the added fields on your survey;

Scroll down to fields.
Select the desired custom field by clicking on the edit button icon that is on it.
A pop-up module will appear. Translate the field details to the chosen language.

Selecting the title and description field for translation

Translate the remaining fields that you added.

3.3.2.2 Translating Tasks

To translate tasks:

Scroll down to tasks.
Translate the task details. You should be able to translate the task fields in the same way that you translated the fields in the surveys. Please refer to the Fields section of this manual for details on how to translate task fields.
Click Save when all is done.

Translate the task name and description on the empty fields as shown above.

3.3.3 Configuring Surveys

You can add additional configurations to your survey e.g setting a survey color etc. To do so, click on Configure on the top of the survey editor.

Using the "Configure" tab in the survey editor.

Configure the settings to suit your needs

Require posts be reviewed before they’re published: When toggled on, posts submitted on your deployment will not be made public i.e accessible to anyone beyond your internal team, until it is reviewed ( It will remain in draft). Setting this option off will automatically publish all posts submitted on your deployment.
Hide author information: When toggled on, this option hides author information e.g phone numbers, twitter handles and email addresses of people who submit posts to your deployment from the public. Note: logged in users with permission to manage posts will still be able to see author information.
Hide exact location information: When toggled on, this option hides the exact location of posts on the map. Only the people with the permission to edit will be able to see exact locations, those without permission will only able to see rounded locations. The locations will be accurate to 0.1 km.
Hide exact time information: When toggled on, only people with permission to edit responses will be able to see exact time submitted. Other people will see only the date.
_Who can add to this survey:_You can limit submission of posts to your survey by roles. By default, surveys are open to the general public for submissions, and not limited to internal roles.
Color: Select a color or input a specific hex value to choose which color will be associated with this survey. Pins on the map will match whichever color you select.
Select default language for this survey: Click on the dropdown menu to choose the default language. This will be changing the language of the deployment that is currently in.
Click on save once your configuration options are complete

Using the "Configure" tab in the survey editor. Highlighting the color field, default language field and two radio buttons.

Ushahidi provides the ability to Share your survey across multiple platforms. Share via:

Web address: Copy and paste this link to direct people to your survey form
Facebook: Share the survey form on Facebook
Twitter: Share the survey form on Twitter
Embed: Copy and paste this HTML block of code to embed the survey form on any site across the web

Sharing surveys across Facebook, Twitter and Embed methods.

3.3.5 Editing surveys

To edit a survey:

Click on a survey from the list of surveys on your page.
From here, change your survey details as desired then click on Save.

Selecting a survey to edit it from the list of surveys

3.3.6 Deleting surveys