user manual.md

User Manual

Introduction

Note: in the following section the links will use "your-domain.com" as domain in links, replace it with your actual domain to get the correct links

• The personality test system is intended to allow customizable personality tests to be displayed, answered and evaluated
  • Access to execute a personality test is granted using a token
• A token can be created at https://your-domain.com/token.html, if you got a valid username and password
• On the start screen at https://your-domain.com/index.html a token (→ about tokens in database) can be entered to execute a personality test, which consists of:
  • One PERSONAL_DATA_TEST, which collects base data about the person
  • Any number of PRE_COLLECT_TESTS, which collect any unevaluated data
  • One EVALUABLE_TEST, which can contain evaluable questions, which will be evaluated
• After answering all questions, the user will be redirected to the result side, showing a PDF with the results (generated by the server)
  • The user is only able to generate the certificate, if the token isn't expired and has at least one usage left (a token can have multiple usages)

General database structure

user table

• Contains usernames & hashed passwords for authorization of token creation
  • Note: the password will be encrypted, so you can (& should) neither read nor change the password like the other values in the database (in case you need another user or like to change username or password, you probably should ask a developer)

token table

• Contains the tokens, consisting of the actual token, information regarding usages & expiring, and the tests, which should be answered
  • Each token got exactly one PERSONAL_DATA_TEST (to identify person) and EVALUABLE_TEST (which will be evaluated), but there can be any number of PRE_COLLECT_TESTS

test table

• Contains the names (to identify the test), descriptions (which define the questions, etc.) and categories of the tests
  • The test category can be:
    • PERSONAL_DATA_TEST: for tests which are used to create a row in table "person" (the test structure & question names must match the API)
      • If you want to create a PERSONAL_DATA_TEST you should probably copy the description of an existing one and adjust it to your needs (→ how to add or change tests)
    • PRE_COLLECT_TEST: for tests which won't be evaluated (can have any structure)
    • EVALUABLE_TEST: for tests, which should evaluate answers that have a single numeric answer value (non-numeric or multi-value answers will be ignored)

Test answer tables

• Table "person": contains the data about a person, which has answered a personality test (the person will be referenced in the actual test_answers)
  • Note: column "gender" must only contain "m", "w" or "s"
• Table "test_answer": contains an answer for a PRE_COLLECT_TEST or EVALUABLE_TEST, a reference to the person, which has answered the test, and a reference to the test, which was answered

Evaluable answer tables

• Table "evaluable_test_answer": references test answers (in table "test_answers"), which can be evaluated
• Table "evaluable_question_name": list question names and their question categories (which can be anything)
• Table "evaluable_question_answer": include the numeric answers for an "evaluable_question_name" of an "evaluable_test_answer"

Database connection

Install pgAdmin

• Download pgAdmin installer here
• Run installer and click through it until it's finished
• Now pgAdmin should be installed, so test starting it
  • To start on:
    • Windows: press the Windows key (which opens a menu), type "pgAdmin" (which should start a search), check whether pgAdmin is shown as "App" ("App" should be standing below pgAdmin) and click on it
    • MacOS: open the "Finder", select "Applications" and search for "pgAdmin" (possibly with a following number after the name) and open it
  • When you start pgAdmin the first time, you will be asked to enter a master password - enter it and remember it, you will need it each time, you start pgAdmin

Add database

• Start pgAdmin and enter the master password selected by you earlier
• Follow the instructions in this answer to add the database connection
  • Choose by yourself, whether you want to save the database password or not
  • Note: the credentials of the database will change regularly, they may have to be changed in future
• After the instructions click "Save" to save the database connection
• Now the servers can be found on the left side of the window
  • There should be an entry with the database name, which you just set (you may need to unfold the server entry to see the database)

Access database in pgAdmin

Find tables

• Tables can be found here: Servers > <SERVER_NAME> > Databases > <DATABASE> > Schemas > public > Tables
  • With <SERVER_NAME> being your chosen server name and <DATABASE> being the database name from the database credentials

Show & export data

• Find the table to show data from (→ how to find tables)
• All data inside a table can be shown by: right click on table > View/Edit Data > All Rows
  • Alternatively the "View Data" button can be used - it's the second button at the right of the "Browser" label, showing a table (marked orange in image):
• The shown data can be downloaded as CSV by clicking F8 or the download symbol at the right top, second from left (marked orange in image):
  • The downloaded CSV file can be imported to excel by following the instructions here or by following the next bullet points
    • In Excel: Data (de: Daten) > Get Data (de: Daten abrufen) > From File (de: Aus Datei) > From Text/CSV (de: Aus Text/CSV)
    • Select the exported CSV file in the opened menu, click import and a preview will be shown
      • In case the preview is displayed wrongly, the "Delimiter" (de: Trennzeichen) may have to be adjusted
      • In case the preview is displayed correctly, click "Load" (de: Laden) to import the table
• If the data you want to access exist as "Heroku Dataclip", you can also access it directly on Heroku Dataclips website
  • Select a dataclip in the list to show its data; in the shown data the "CSV" button can be used

Change & save data

• In the shown table (→ how to show data):
  • Rows can be added by scrolling to the bottom of the table and entering the values in the empty fields of the last row
  • Values can be changed by clicking on them twice
    • After clicking, you can either enter a new value into the table directly or a small window will pop up, offering you to enter a new value
  • Rows can be deleted by clicking on the most left number of the row and clicking the "Delete" button above the "Query Editor" (marked orange in image):
• To save the locally changed values to the database click F6 or the "Save Data Changes" button above the "Query Editor" (marked orange in image):

Specific tasks

Add or change tests

• Create or adjust your test using the survey creator of SurveyJS
  • In case you want to change an existing test: open table "tests" (→ how to find tables) in pgAdmin, search the row of the test you like to change, doubleclick the value of "description_json" and copy the content of the pop-up window into the "JSON Editor" tab of the website linked above (then navigate back to tab "Designer" to change test)
  • The "name" and "category" of an evaluable question will be extracted from the names (set in survey creator) of the question, and its rows (if the question contains rows)
    • If evaluable tests have the same names for their evaluable questions (which return single numeric answer values), the answers with the same question name will be linked in the database
    • If you don't specify any question names in the survey creator, it will set the names by itself matching their order ("question1", "question2", ...) - so evaluable questions will then be linked by their order
• After changing: select the "JSON Editor" tab, select all text (from { to }) and copy the selected JSON description
• In pgAdmin open table "tests" (→ how to find tables) and show its data (→ how to show data)
• Now either:
  • Replace another test: find the row of the test to replace, paste in its "description_json" column the description you previously copied and save the change (→ how to change & save data)
    • You may change the "category" as well, but be careful - if the test was already or is still used in tokens this probably causes errors!
  • Add a new test: add a new row with the following values and save the change (→ how to change & save data):
    • Enter your new test name (which must not exist before) to column "name"
    • Enter the JSON description (you previously copied) to column "description_json"
    • Enter a category (which must be PERSONAL_DATA_TEST, EVALUABLE_TEST or PRE_COLLECT_TEST) to column "test_category"

Adjust token

• Disable expiring: open table "token" (→ how to find tables)
  • Find the row of the token you want to change, doubleclick the value in the "creation_timestamp" column, delete its value in the pop-up window (after deletion value should be "[null]") and save changes to database (→ how to change & save data)
• Adjust remaining usages of token: change "max_usage_count" value of row in "token" table (→ how to change & save data)
  • Delete the value to have unlimited usages (after deletion value should be "[null]" , not "0" or another number)

Database backups

• Open https://dashboard.heroku.com/apps/your-app-name/resources with your-app-name being the name of your Heroku app and click on your "Heroku Postgres" database
• In the website you will be redirected to, select the "Durability" tab - here you can:
  • Create database backups by clicking "Create Manual Backup"
  • Download or Delete database backups with the "Download" and "Delete" buttons next to the shown backups
    • There are only backups shown, if you have created one already

Grant developer access to heroku (server)

Note: you can only add a collaborator, if you already have access

• Click "Add Collaborator" at https://dashboard.heroku.com/apps/your-app-name/access with your-app-name being the name of your Heroku app
  • Enter email address of the developer and click "Save changes"