ADAPtive QUESTionnarie is a web-based microservice tool that permit the creation of adaptive tests, surveys, and questionnaires based on a pool of questions and a graphical model.
The idea behind this project, is to have a simple way to assess the skill level of a person based on a series of questions. A skill is considered a particular detail of a person that can be identified with the right questions. The adaptive engine aims to find the optimal question for a user in order to maximize the score of the skills.
This repository is composed by three different modules:
Backendthat contains the adaptive engine;
Exchangelibrary, a Java library that can be used to build remote clients for the adaptive engine; and
Experimentsmodule: a module that uses the
Exchangelibrary to perform academic experiments with adaptive surveys.
In addition, the
Backend module is also available as a Docker image and in a ready to use
This tool allows the user to build a survey with an adaptive choice of the questions. In other words, the next questions depends on the model and the previous answers of a person.
For each survey/questionnaire, a unique
access code allows multiple person to complete the questions in an anonymous
way. Each survey has its own
model that can be crafted to the specific scenarios and questions available.
Some configurations are available, such as:
- limiting the adaptivity using minimum and maximum number of question, and minimum and maximum scoring parameters;
- limit the order of the questions can be posed;
- group the questions by skill, depending on the structure of the used model.
Each answer given by a person update its internal
state. The history of all the answers given and the states produced
can be used to follow the evolution of the distributions of probability associated with the questionnaire.
Once compiled, the simplest way to run the tool and access to the demo page is to first set these two environment variables:
DB_DBMS=memory MAGIC_API_KEY=<put there a random string>
These two settings allows the application to run with an in-memory database and init the remote api key.
Finally, run the build jar as following:
java -jar adapquest-backend.jar
The demo page will be accessible at the url http://localhost:8080/demo/.
This configuration is not suitable for a production environment and should be used only to check the demo or be used for experiments. For something production-ready-more-or-less rad the next section.
The easiest way to run the tool, is to use the Docker image. Using the provided
docker-compose.yaml it is possible
to have a running application in few minutes reachable on port
The stack is composed by a database for storing the questions and the session and the backend engine. We
Postgres 13.1 but any other SQL-based engine supported by Hibernate should be compatible.
Refer to the Wiki for more details on the
It is possible to use Keycloak as identity provider instead of the simple APIkey internal mechanism.
In order to do so, the following environment variables must be set:
KEYCLOAK_ENABLED: "true" KEYCLOAK_REALM: "<realm>" KEYCLOAK_AUTH_SERVER_URL: "<url>" KEYCLOAK_RESOURCE: "<client-name>" KEYCLOAK_PRINCIPAL_ATTRIBUTE: "preferred_username"
To control the roles, set the following two environment variables to the correct roles:
ADAPQUEST_KEYCLOAK_ROLE: "user" ADAPQUEST_KEYCLOAK_ADMIN: "admin"
user role is who performs the survey; the
admin role is who can add and manage surveys.
Both these variables can be used in a
If you write a scientific paper describing research that made use of the
AdapQuest tool, please see
the CreMA library citation note.