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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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:

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.

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:

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.

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

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.

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 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:

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/{{action_id}}/steps/{{step_id}})

/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.

/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)

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.

/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.

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.

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.

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.

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.

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:

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.

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.

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

4. Add the correct input component for your new question type inside the form component

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.

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!

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.

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!

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.

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!