Survey builder template

Craft your surveys with our survey builder and collect valuable data from your application's audience.

Survey builder empowers you to effortlessly craft surveys that yield meaningful insights. Seamlessly create customizable forms tailored to your specific needs. With an intuitive interface and a plethora of question types, Survey builder simplifies the process of gathering valuable feedback, organizing events, conducting research, and much more. Real-time collaboration, robust analytics, and seamless integration options make Survey builder the ultimate tool for understanding your audience, making data-driven decisions, and transforming responses into actionable results. Elevate your surveys to the next level with Survey builder—where simplicity meets powerful insights.

Introduction

Overview of the application

Glossary

As this application will only make sense if you have a clear understanding of the used terms in both the app and documentation, we’ll start with a glossary of terms and their definitions in the context of this application.

Surveys

Or: QuestionnaireTemplate, SurveyBlueprint, Blueprint

The survey is the overall term for any available questionnaires in the application. consisting of sections, consisting of questions. This is the setup/template/blueprint for a questionnaire, so this determines the order of questions/sections but does NOT hold any given answers or submissions. The answered equivalent of this will be referred to as a submission.

Submission

A submission is a (to-be) completed instance of the survey. This is very similar to the survey but then focussed on actually answering the survey. This and other data (Section, Question, Answer, Interaction) are separated from the blueprint setup itself so that historical data is always preserved. When the blueprint is changed, it does not affect the already existing submissions at all.

Section

Or: TemplateSection, BlueprintSection, SubmissionSection

A section is a chapter of the survey or submission. Every section has its own set of questions and will be displayed as one page for the end user. The progress of a submission can also be tracked per section. When referring to a section of a survey/blueprint it’s usually called BlueprintSectoin; when referring to a section of a submission it’s usually called a Section or SubmissionSection.

Question

Or: TemplateQuestion, SurveyQuestion, SubmissionQuestion

The question refers to the actual question that is (to be) asked to a user. This notably consists of a question type (number, text, multiple choice, etc), the QuestionText, and an Answer. In the context of a survey, a question is usually referred to as a SurveyQuestion; in the context of a submission, it’s usually referred to as a Question or SubmissionQuestion.

Answer

An answer is the actual answer someone has given to a user. This can only exist in the context of a submission and hold the given answer according to the specific question type, as well as a consolidated answer which is always in text format.

Back office

The back office is the part of the application only accessible to authenticated users. This is where surveys are managed and submissions can be reviewed.

Invitee

Or: QuestionnaireInvitee, SurveyInvitee

The invitee refers to someone who is invited to fill in a survey. This allows an authenticated user to receive a named (non-anonymous) submission for a survey and we generate the submission for that person at the time of invitation. The invitee is authenticated/secured by creating a unique 25-character hexadecimal string, a.k.a token.

Token

Tokens are randomly generated hexadecimal strings of different lengths, used to uniquely identify certain data, e.g. surveys, submissions, questions, and invitations.

Purpose and use cases

Survey builder is designed to simplify the process of gathering valuable feedback, insights, and data from various audiences. Its purpose is to empower individuals and organizations to create surveys with ease, allowing them to collect structured information, opinions, preferences, and suggestions from respondents. By providing an intuitive platform for survey creation, survey builder aims to facilitate informed decision-making, enhance understanding of audience needs, and drive improvements in products, services, and experiences.

Example use cases of survey builder:

• Lead generation: Create surveys to understand the needs and challenges of potential clients. Gather information about their concerns and preferences, enabling firms to generate leads and offer tailored services.

• Market research: Conduct market surveys to understand consumer preferences, behavior, and market trends, aiding in strategic planning and product development.

• Customer feedback: Collect feedback from customers regarding products, services, support experiences, and overall satisfaction levels to improve customer relations and enhance offerings.

• Employee engagement: Create surveys to gauge employee satisfaction, engagement, and feedback, fostering a positive workplace environment and identifying areas for improvement.

• Event planning: Gather attendee preferences, expectations, and feedback before and after events, ensuring a seamless and enjoyable experience for participants.

• Academic research: Design surveys for academic studies, research projects, or student feedback, allowing researchers to collect data efficiently and analyze trends.

• Training and workshops: Evaluate training effectiveness and gather participant feedback to enhance training programs and workshops for continuous improvement.

• Healthcare surveys: Conduct patient satisfaction surveys, health assessments, and healthcare service feedback to improve patient care and healthcare services.

• Social and political research: Conduct public opinion polls, political surveys, or social issue research to understand public sentiment and perspectives on various topics.

• Product development: Engage potential users to gather insights about desired features, usability, and preferences, aiding in the development of user-friendly products and applications.

• Non-profit and NGO activities: Gather data from beneficiaries and stakeholders to measure the impact of social initiatives, identify areas for support, and enhance community engagement strategies.

• Event feedback: Collect feedback from attendees after events, conferences, or webinars to assess the event's success, identify strengths, and address areas for improvement.

• Travel and hospitality: Obtain guest feedback to improve hospitality services, accommodations, and travel experiences, ensuring high levels of customer satisfaction and loyalty.

Runtime overview

Login features

The login is a standard application authentication with a password reset and registration features. The registration process will create an account and it utilizes the password reset flow to actually create a password for an account. This is done to confirm a user has access to the email address they’re using to create this account.

The permissions setup of this template is very basic, but the template will assign the admin role to the very first user that registers, and the webuser role to any other user after that.

An authenticated user can also manually create accounts and use the same password reset flow to invite these new users to the application directly via the back office pages.

Back office

The back office is where authenticated users can build and maintain their surveys as well as view all the submissions and manage other app data.

As mentioned above, the back office does not have a lot of separation between roles. Any authenticated user can basically view and manage everything. This is done to have an open canvas for you in terms of how you would like to set this up. You probably would want to close the user management page off for certain roles and you might want to make surveys only visible for their creators.

The back office pages are labeled with “BO” in their name in the IDE, let’s go through them:

• BO - Home - All Surveys
  This is the home page with a view of all the surveys of the app. This is where you can create new, or remove an entire survey.

• BO - Manage Section & Questions
  This page shows you all of the Questions of one specific SurveySection and allows you to manage the questions, as well as the section title and description up top.

• BO - My Account
  This is where a user can manage their account by updating their name and/or email or changing their password.

• BO - Question Types
  This is where the question types are managed. This page is of utmost importance to the working of your application. That’s why this is the only page that’s set to where only one with the admin role can actually make changes.

• BO - Survey Sections
  This page is where a survey’s sections are displayed and managed.

• BO - Survey Submissions and Invites

• BO - Webusers

Getting started

Configurations

As for any application template, the first step is to make sure the configurations of your app are correct. To see the configurations, open the application and navigate to Tools > Configurations.

URL configurations

The URL configurations are of utmost importance for the usability of your app so make sure this is set correctly.

• Start_path: this is the slug/path that’s used to access the public surveys. By default, you can set this to 'q' but should be changed if you decide to change the path of the page “Survey - Start”. This will be used for certain properties and emails that the app creates. This will translate to the following URL structure: https://.betty.app/q/

• Answering_path: this is the slug/path that’s used to generate someone’s unique link for answering a survey. By default, you can set this to 'q-a' but should be changed if you decide to change the path of the page “Survey - Answering”. This will be used for certain properties and emails that the app creates. This will translate to the following URL structure: https://.betty.app/q-a/

• App_id: The app ID is the unique identifier of your application which is available in the application's URL (https://.bettyblocks.com/app) as well as the compiler application's URL (https://.betty.app)

SMTP settings

SMTP settings are used to send emails to end users of the applications. If these are not filled in, the application will not be able to send any user any email. For more info on setting up the SMTP head to this article.

[Start] Action

In the actions, you can find an action by searching for [start]. (“[Start] Initial setup for your app”).

This action will (re)generate all survey tokens and the URLs (based on the URL configuration) and reset any statistics that have been copied over from the template.

This action is to be run only once after the URL configuration has been set up.

Settings models

Settings models are data models that will also copy data into a template application and merge data over the sandboxes of your application. These are used in this template to give you a couple of examples of surveys we utilize in our internal version of this app.

To prevent unexpected results when working in sandboxes, this setting should be removed. You can best remove this setting after you’ve created your required sandboxes so that you can use the example as test data in development.

Note: QuestionType is also a settings model, and it should always remain a settings model as this is heavily intertwined with the application functionality.

The settings models are:

1. QuestionType

2. TemplateSection

3. TemplateQuestion

4. TemplateInteraction

5. TemplateAnswerOption

6. TemplateQuestionnaire

Emails

At certain points of your application, there will be emails sent out to users. As emails are always subject to preferences and wishes, the template has very basic emails configured and we highly recommend changing these templates to your own liking.

The following emails will also have their corresponding application path. This can be used to directly link to the action step if you copy this into your environment URL. (e.g. /actions//steps/)

Invitation for submission

/actions/6d6c18eb9d834786bae53e605ede5aa1/steps/74ec4204855c4a30a1e04fda024e1d55

An authenticated user can create new (survey) invites to invite a specific email address to fill in a certain survey. This invitation will be sent through an email.

Password reset

/actions/645c3ac23d4249fbb317dad3c7349d31/steps/a33091f6eb1b41f1b5800320727513b4

The application has a reset password functionality which will send a user an email when they fill in their email address (and it is actually a known email address in the app)

Account activation on registration

actions/8a4dc4bf1ca64756912aebdb183e3757/steps/d80276efdae844c0bf7056ab889084e9

When a user registers a new account, they will have to follow the reset password flow to actually set a password for their account. This is done to validate email addresses.

Account Activation on Invitation

/actions/7b0e3dcef5f24d3ba28b128c8111454c/steps/b7eb31cd39a14129b0f2c50e025f911b

An authenticated user can also create new accounts through the back office. They will have the option to invite the user to the app in the create form, as well as a button in the detail view after creation.

Initial security setup

Authentication

The back office pages require a user to be authenticated. The template application has a registration page that allows anyone to create an account and manage the surveys and submissions. Note that the first registered user will automatically get the admin role and any user after that will get the webuser role. This is done to provide the quickest route to usability but this should all of course be changed to your own preference.

Note that when a user registers an account, that user will receive an email containing a link to set a password. This is done to make sure an email address is actually valid and owned by that user.

Permissions

As this is a template, the permissions are set up very basic. The template uses only an Admin and a webuser role and the only difference is that the Webuser is unable to make changes to the QuestionTypes. This is done because changing the QuestionTypes will always require involvement from a developer to reflect those changes correctly.

Adding a new question type

This chapter will take you through the steps required to add a new question type to the application. Note that adding a question type can be done through the runtime, but it requires a developer in the application to actually make it work in the application.

Back office page

An authenticated admin user in the compiled application can create a new type on the Question Types page.

If you check the checkbox for “Has answer options”, it will allow the survey builder to add answer options when using this question type. In the template, the only type with answer options is the multiple choice (radio group) type.

Once the type is created, note down the ID of the type you just created. To provide for renaming the question types' labels, all logic is tied to the type ID in the development environment.

Answering page

The way the answering page works is that it loops through all of the questions, and per question then checks the question type with a conditional component to determine the correct input to show. Then every input has its own form to save the given answer correctly. The form is submitted when a user triggers a save on the input. Note the tree view in the following image.

Each question will generate:

• a conditional component to check if the question is visible

• A box encompassing the entire question

• The question’s number/index (in grey)

• The question’s text (the actual question)

• The text is appended with a box component to display:

  • An asterisk (*) if the question is required - checked through a conditional component

  • A small circular progress bar that shows the user when a question is being saved.

• The conditional component per question type

Adding the new type in the data model

Any type of question is eventually saved in two properties on the Answer data model. One that corresponds to the actual type of question (text is saved as a text in the data model; a number is saved as a number) and one consolidated answer. This is a multiline text property that can save any answer, even if it’s not a text. This will for instance save the URL of the uploaded file as text, save the given number as text, or the selected option as text. This consolidated answer is helpful for exporting features as well as only having to select one property in texts when you’re extending on other pages in the application.

1. Navigate to the Answer data model.

2. Add the required property for your new question type.

Adding components on the page

Note: Remember to change the name of most components you add in this walkthrough, so they’ll be easier to locate through your component tree.

1. Navigate to the Survey - Answering Page.

2. The first component to add is a conditional component. Ensure this conditional is inside the DataList for the questions, but outside of any other conditional or component. Use the component tree to validate this is the case.

   

   This conditional is the first place where you’d use the new type’s ID, to check if a certain question is actually linked to the newly created type.

   

3. Next up is adding a form. The best practice is to add a form without linking it to any data. We will do this manually since the data linking through a form’s creation wizard will also cause unnecessary extra data API requests. Once it’s created, also change the name of the component so you can locate it more easily in later steps

   

The form will add error/success message handling automatically, but in the design of this page that should be changed.

5. Create an interaction on the input that will submit the created form on the change

6. Add a hidden input inside the form component and link that to the Question.Token

7. Add another hidden input component inside the form component and link that to the Submission.Token. These hidden inputs are required to find the correct question record in the action in the next steps.

8. Remove all other components (text input, alerts) that are not needed.

That’s all for your page - click the play button to compile and put your changes live on the page.

Note: without a survey token in the URL the compiled page will not work so you will receive an error in the page that opens after compiling. You can ignore the error and close that tab for now, it will still have saved and correctly compiled your page.

Create the action

As the action will be very similar to any other form, you can look at the other form actions for reference as well.

By putting the inputs inside of your form on your form, you’ve configured the action input variables automatically so they are available in your action.

In the page builder, navigate to the form component, and then open the action. Once you're in the action, navigate to the settings in the top right of your screen. As with every action, by default an action is private. So the first you’ll wanna do is to make sure the permissions tab in the settings is set up correctly, according to your desired implementation. Once that’s done, we can build the action itself.

1. Navigate to the Start step where the input variables are available

2. Go to the action variables and create the required records, corresponding to both tokens:

3. When the end user fills in this question, the app needs to save the given answer as an answer record so that's where will start the action:

4. That is the base of your action, but there are a couple more steps you need to add to provide proper validation and the ability to change an answer after initial creation.

Let’s start with the validation. This action should only actually work if the end user is answering a question of this new question type. Especially when working with the application as an API, it can happen that wrongly formatted requests are being sent to your action, so we’ll do a little validation step at the beginning of your action.

5. That’s it for validation. Now, to have the possibility of changing an answer after its initial creation, we’ll have to check if the question record already has an answer connected to it when executing this action.

That’s it for the Answering page. You’ve changed the data model and the page correctly, and have created a new action to reflect those changes as well!

Summary page

On the summary page in your application, an end user will see all of the questions and answers given, before submitting and finalizing his submission. As you’ve added a new question type, you also need to display your newly created question type on that page.

1. Navigate to the ‘Submission - Summary’ page

2. In more or less the same fashion as the Answering page, we’ll add a question type check on this page, and then display the given answer.

You might’ve noticed that it seems like there are a lot of similar-looking text components for all of the different question types and that these could technically be one single component.

Correct, almost. Using separate text components grants you the ability to format or style certain question types differently on this page. For instance, a file upload type needs a button to download that file rather than a text component showing the URL of the file. Maybe in your use case, you would like to display all of the Number answers with a red font - or display all multi-line text answers as a Body 2 style so it’s not as big on the page. That’s what you can do now!

Submissions page

The Survey - Submissions page will show an authenticated user what answers have been given in a certain submission, much like the summary page shows the overview to the submitter. On this page, you’d want to account for your new question type too.

1. Navigate to the “BO - Survey Submissions and Invites” page.

2. Use the wrapper component (the only clickable component on your page by default) to navigate to the details tab of the record view

3. Now unlock the wrapper with the lock button at the bottom.
   ​

   Note: the back office pages are based on the back office page template and come with a wrapper component by default. Learn more about wrapper components here.

4. Repeat step 2 of the Summary page but then apply to this page.

Custom action steps

The creation of submission happens in the action ‘[sub] Generate Submission based on Survey’. This action was initially built with the default action steps available for every developer but this caused some performance issues when working with bigger surveys. Therefore, we’ve created a couple custom custom-coded steps that improve the flow of creating data as well as reduce the amount of Data API requests. For more information on this please refer to https://github.com/Betty-Services/Surveybuilder-dev

Good luck, builder!