Exporting Reports, Guide for Further Development

Project: TIMCAN

Document creator: Jere Ojala

Created: 23.5.2019

Modified: 6.6.2019

For further queries: tim@jyu.fi

1. Purpose and content of the guide

The report exporting feature compiles and prints the adaptive feedback test results in CSV form. Exporting option can be found on TIM in the Answers tab. In the dropdown menu of user answers list the menu item Create Feedback Report creates a test report. When Create Feedback report is clicked a dialog for the CSV formating is opened where a user can choose the options for it. By clicking OK the browser opens with the results.

The document defines the structure and the location of the report exporting feature developed into TIM by TIMCAN project. The purpose of the document is to give better understanding how the code works and its comments.

2. Structure and location of the test exporting in TIM

The report exporting code is divided in TIM thusly:

• /timApp/answer/feedbackanswer.py contains most of the code of compiling the information and exporting it into CSV form.
• /timApp/static/scripts/tim/answer/feedbackAnswersController.ts handles the allFeedbackAnswerOptions.html options and URL query.
• /timApp/static/templates/allFeedbackAnswersOptions.html contains the HTML for the option dialog window.
• The option of report exporting was added into the already existing file /timApp/static/scripts/tim/answer/userlistController.ts.
• /timApp/tests/server/test_feedback_report.py contains automated tests of the reporting feature.

3. Description of functionality

The code fetches from the database the saved answers of the document or all documents in the folder and the users who answered them. The query is then sorted based primary on users and secondary on time and date they answered.

The script goes through each answer except the first one where it only saves the date. The script checks if the answer is from the feedback plugin.

If the answer is not saved by the feedback plugin the script skips the answer. If the answer is saved by the feedback plugin the script saves

• the correctness of the answer,
• the answer of the user,
• the correct answer and
• the given feedback

from the answer. The script calculates the times between the question was summited and the user continued after reading the feedback by subtracting the previous answer date. After the script has gone through all the answers the answer arrays are returned. Each array is then compiled into the CSV format.

4. Program logic file feedbackanswer.py

/timApp/answer/feedbackanswer.py contains most of the code of compiling the information and exporting it into CSV form. feedbackanswer.py doesn't contain any classes or interfaces.

4.1 Functions

feedbackanswer.py contains the following functions:

• get_all_feedback_answers fetches all answers from database and sorts them by user and then by date. The function also filters answers based on validity.
  

• compile_csv compiles data from answers JSON into CSV form.
  

• print_feedback_report is a routed function to print compiled data. It handles also option parameters. The route is \feedback\report\.

5. Dialog controller feedbackAnswerController.ts

/timApp/static/scripts/tim/answer/feedbackAnswersController.ts handles the allFeedbackAnswerOptions.html options and URL query. feedbackAnswerController.ts is mainly modeled after already existing code allAnswerController.ts.

5.1 IFBOptions interface

The interface contains all the parameters of the exporting options. The functionalities of the option parameters will be handled in the feedbackanswer.py file. feedbackAnswerController.ts only initializes their default values. The interface contains the following parameters:

• period will define from what period answers will be exported.
• valid will define filtering based on the validity of answers.
• name will define how to display the identification of the users.
• periodFrom will define start of the period.
• periodTo will define end of the period.
• scope will define whether to export the whole test or only one task.
• answers will define whether to export all users, all the visible users or only the selected user.
• format will define CSV delimiters format.
• users will define all the visible or selected users depending on the answers option.
• decimal will define decimal format for the time units.

5.2 IFeedbackAnswersParams interface

The interface contains the following parameters for the routing.

• identifier is the number id of the document.
• users is the list of the users.
• url is the URL for the report.
• allTasks is a boolean for showing the possibility of sorting the answers in a report. When exporting answers from a single TIM task it is false. When exporting answers from the Get answers dialog it is true. Because the answer of a single question item of a dynamic feedback test is never exported on its own and the Export to CSV dialog is always used, this parameter is currently obsolete.

5.3 Relevant attributes of the FeedbackAnswersCtrl class

The following attributes are the most relevant of the FeedbackAnswersCtrl class:

• component is the name of the component.
  
• options is the interface that contains all the reporting formating options.
  
• storage is the storage where the previously selected options are stored.
  
• datePickerOptionsFrom handles the period start picking.
  
• datePickerOptionsTo handles the period end picking.
  
• lastFetch stores the last fetched answer.

5.4 FeedbackAnswersCtrl class methods

FeedbackAnswersCtrl class contains the following methods:

• getTitle returns the title of the dialog window.
  
• onInit initializes options, handles the date pickers and compiles the query for the userlist handling.
  
• ok handles events for the OK button.
  
• cancel handles events for the Cancel button.
  

6. Ideas for further development

The ideas for the further development include the following ones.

• Create Feedback Report option should be hidden when the feedback plugin is not in the document,
• The points from the feedback plugin should be added into the feedback report.
• The route function should be moved into the routes.py file.

The function for exporting test results was developed for the Centre for Applied Language Studies. The exporting only works if the feedback plugin is in the document or in at least one of the documents in the folder. The generality of exporting the test results depends on the generality of the feedback plugin.

7. Relevant materials

Apart from the document, maintainers might find useful information from the following materials:

• User Manual for Creating Adaptive Feedback Test in the TIM https://tim.jyu.fi/view/ kurssit/tie/proj/2019/timcan/kayttoohjeet/instructions and
• source code in GitLab https://gitlab.com/jatakuiv/tim.