Administration
The first version of the diary-survey-bot required editing the survey as a json files. While it did work fine, it was always clear that this way was not feasible for bigger projects. Therefore the survey-editor was created. While still using the same format it makes the whole process of creating surveys a lot more smooth and it should catch most errors while still allowing a lot of flexibility.
The graphic below should give you a quick overview of the basic data structure that is used for the surveys:
- day: Represents the day of the study. Make sure to put the day elements in ascending order.
- blocks: Contains a list of block nodes.
- meta: Contains meta information for better overview (not mandatory).
Example day node:
{
"day": 1,
"blocks":
[
{
-- block node 1 --
},
{
-- block node ... --
},
{
-- block node N --
}
]
}
-
time: currently this element awaits a keyword, that is defined in SCHEDULE_INTERVALS in the admin/settings.py file. There you can define your own time intervals in the format ["hh:mm", "hh:mm"] or fixed schedules in the format "hh:mm". Make sure to make your interval at least 30min long.
-
settings: Here certain properties for a block can be set. List of current options:
-
MANDATORY: Marks the block as mandatory. The next block is only getting scheduled when the current block is complete and a question contains the command: Q_ON
-
questions: Contains all the question elements of the block.
-
meta: Contains meta information for better overview (not mandatory).
Example block node:
{
"time": "TIME_KEYWORD",
"settings": [["MANDATORY"]],
"questions":
[
{
-- question node 1 --
},
{
-- question node ... --
},
{
-- question node N --
}
]
}
- text: Contains the message text, that shall be asked.
- meta: Contains meta information for better overview (not mandatory).
- choice: Contains nested lists of answer possibilities which are used to create a custom keyboard within Telegram. Dynamic keyboards can be created within the python file survey/keyboard_presets.py and have to be registered in the CUSTOM_KEYBOARD dictionary.
- variable: A keyword that will be stored in the corresponding column of the .csv file for better analysis and navigation. (not mandatory)
-
condition: Conditions can be used to store certain requirements that can
be used in the future.
(Example: User says he is single:"condition": [["single", "#is_single"]]) -
condition_required: Previously defined conditions can be put here and
if the user does not fulfill them the question will be skipped for him.
(Example: User said he is single earlier. Only ask this question if user is single
"condition_required": ["#is_single"]) -
commands: Commands are basically signals for the program to trigger special
events. List of all (current) commands and their usage:
- FORCE_KB_REPLY: The user has to choose an option from the Keyboard to proceed.
- Q_ON: See BLOCK settings - MANDATORY
- COUNTRY: Signals that the user will respond with his country: Relevant for database.
- AGE: Signals that the user will respond with his age: Relevant for database.
- GENDER: Signals that the user will respond with his gender: Relevant for database.
- TIMEZONE: Signals that the user will respond with his timezone: Relevant for database.
- ["DATA", "DATA_NAME", "COMMAND"]: Signals that a certain operation shall be executed onto a custom data-structure. (See Survey Specific Functions).
Example question node:
{
"text": "Sample Text",
"choice": [
["Choice 1 "],
["Choice ..."],
["Choice N "]
],
"condition_required": ["#IDENTIFIER"],
"condition": [["Sample Choice 1", "#IDENTIFIER"]],
"commands": [["FORCE_KB_REPLY"],["COUNTRY"]]
}
The survey-editor is written in python3 using the pyqt5 Qt wrapper. It should work on most platforms and delivers an alternative way of generating surveys. Understanding the functionalities of the bot will make navigating and designing your surveys a lot easier.
There are two ways to use the survey-editor.
-
Download the build and execute the survey-editor.py script. If it does not work check if you have installed all the prerequisites.
(mainly pyqt5:pip3 install pyqt5) -
Use the executable for Windows/Linux. In the directory tools/builds/ you can find executables for the mentioned platforms which should function as standalone programs. If those do not work for your platform, you can easily create your own builds using pyinstaller.
Simply choose a folder for your project. If the folder is empty the program will prompt you with a default language choice. If given a a valid ISO-639 code your basic project is created. It will consist of a at least one question_set_xx.json, a config.json file and a template.json file.
The config.json file of your project has the following format:
{
"default-language": "en",
"project-name": "example-project",
"custom-keyboards": [
KB_COUNTRY,
KB_TIMEZONE
],
"editor-mode": "Translator"
}
You can either edit the json-file directly or do it within the editor.
"custom-keyboards": [] : this list shall contain all custom/dynamic keyboards
that are defined on the bot side.
Read more about custom keyboards here.
"editor-mode": "Translator/Administrator": currently not implemented yet.
The main/day view is divided by three columns. The left allows you to open the project,
add/remove languages and access the settings.
The center column displays all the days of the surveys. The number of the day is an offset to the start. The move buttons allow you to change the order of the days without changing the general schematic. The shift buttons allow you to increase/decrease the day number while retaining the relative offset between the days.
The right column displays all of the properties of the selected day. The block list can be reordered via drag-and-drop. The blocks of day can be accessed via this list.
The coloring of the list items indicates its status. Green: free (of detectable) errors. Red: has some errors. This is the same for the Block/Question View.
The block/question view is has a column on the left that lets you
cycle through the questions of the block. One thing to note is, that
you are responsible for the correct time order of the blocks since
they are keywords and therefore are not automatically checkable.
The main-window lets you edit the selected questions in all languages. The command/meta/variable properties will be the same for all languages and therefore set across them all.
For more information on condition/condition_required/commands/ see the the data-structure description above.
There is a very simple method to create templates for reoccurring
days/blocks/questions/choices. You can find the pattern in the image above
for spread across the applications for all those possible reoccurring
models. If you have the impression while editing you survey that you
might need this model again simple name it and store it. To reuse it
later simply load it then and the properties of the model will take on the
properties of the template.
- Start with the default-language and try to get it as close to the final one as possible.
- Now you may add the additional languages and they will be marked as "to be translated" this allows you to track your progress easier.
- When finished adjust the settings of the bot to your studies needs.