fuhrmanator / course-activity-planner

Tool for instructors to plan course activities and synchronize the data with syllabus, LMS, etc.

This project is affiliated with the Maison du logiciel libre (ML²) at .

Table of Contents generated with DocToc

• course-activity-planner
  • How to use
    • General principle
    • Start/End of activities
    • Relative date or time modifiers
    • Absolute time modifier
    • Defining new activities
  • Development setup
    • Run unit tests
    • Run the linter
  • Production setup

course-activity-planner

Tool for instructors to plan course activities and synchronize the data with syllabus, LMS, etc.

Moodle courses can be cloned and updated with new activity dates from a calendar. Why?

How to use

General principle

Moodle activities can be planned relative to Seminars, Practica and Laboratories. Each activity adapts its start and end dates with the calendar of specific dates.

<activity to plan> <start at activity> <end at activity>

Ex: Quiz 1 is opened on Seminar 1 and closed right before Practicum 2 would be possible with this line: Q1 S1 P2

• MQ1 stands for Moodle Quiz 1
• S1 stands for Seminar 1
• P2 stands for Practicum 2

Generic activites which are not linked to Moodle content can also be created.

By default, Quizzes and Exams can be planned without any Moodle file.

Start/End of activities

Adding F to an activity will read the finishing time of the activity. Adding nothing or S will read the start time.

Ex: Quiz 1 is opened right after Seminar 1 and closed right after Practicum 1 would be Q1 S1F P1F

Relative date or time modifiers

Amounts of time can be subtracted or added to activities.

Supports + or - combined with

• minutes: m
• hours: h
• days: d
• weeks: w

Ex: 1 hour after Seminar 1 would be S1+1h.

Ex: 15 minutes before Practicum 2 would be P2-15m.

Ex: Quiz 1 is opened 1 hour after Seminar 1 and closed 15 minutes before Practicum 2 would be Q1 S1+1h P2-15m

Absolute time modifier

The exact hours can be set to an activity.

Ex: the day of Seminar 1 at 23:55 would be S1@23:55.

This can be used along with relative date or time modifiers.

Ex: the day before Seminar 1 at 23:55 would be S1-1d@23:55.

Please Note when used with a relative modifier, the time modifier must be last.

S1-1d@23:55 is valid

S1@23:55-1d is invalid

Defining new activities

Activities can be configured by the administrator. Please refer to examples in python/config/activities.

Development setup

• Create a google application with Identity Toolkit API access. Create an oauth2 client as a web application and save the client id. This id needs to be put in config/.

• Setup a python virtualenv

cd python && virtualenv-3.4 env

• Activate the python virtualenv

. env/bin/activate

• Install pip dependencies

pip install -r requirements.txt

• Run it

./course_activity_planner.py

• Install bower dependencies

cd .. && bower install

Run unit tests

• Run the test suite

nosetests

• Optionally, you can get a coverage report

nosetests --with-coverage

Run the linter

pep8 && flake8

Production setup

Please see deploy/README.md

Screen shots

course-activity-planner's Issues

Exams should be defined by one date

E1 S6 instead of E1 S6 S6F

The difficulty is that the Exam activity is defined dynamically from a configuration file. Currently, the activity loader assumes all user-defined activities have 2 dates.

Syntaxe pour la configuration des délais pour les dates d'ouverture et de fermeture d'une activité

Cette partie n'a pas pu être implémentée dans le système ActivitETS par manque de temps.

Voici son fonctionnement :

Afin que l'utilisateur du système ActivitETS puisse définir les dates de commencement et de fin des activités comme il le souhaite, un système pouvant être comparé à celui du logiciel Microsoft Project pourrait être implémenté. Ce dernier permet de définir les relations d'une activité avec ses prédécesseurs et ses successeurs. Voici les quatre types de dépendances d'activités que l'on pourrait utiliser :
• Finish to Start : FS
• Start to Start : SS
• Finish to Finish : FF
• Start to Finish : SF

Ces dépendances pourraient être encore plus spécifiques en ajoutant, par exemple, un delta pour le début d'une activité, sa fin ou les deux. Une syntaxe permettrait de facilement configurer le plus précisément possible ces dépendances.
En voici plusieurs exemples, suivi de la signification de chaque propriété :

Modèle de la syntaxe : AA;B;XXXX (voir exemples Figure 9)

1. AA : représente le type et le numéro de la séance :
   • C correspond à une séance de cours
   • L correspond à une séance de laboratoire
   • T correspond à une séance de TP
2. B : représente le début (S pour Start) ou la fin (F pour Finish) d'une séance.
3. XXXX : représente le délai par rapport à la séance :
   • chiffre et d : jours
   • chiffre et h : heure
   • chiffre et m : minutes

Lorsqu'on veut mettre un délai en jour(s), on peut ensuite spécifier l'heure exacte avec @hh:mm. Si on ne spécifie rien, le délai sera défini à la date de la séance moins le nombre de jour(s) du délai. Par exemple le délai pour la date de fin d'une activité : L2;S;-1d@23:59 correspond à la veille (-1d) du début (S) de la séance de laboratoire 2 (L2) à 23 heures et 59 minutes (@23:59).

Grâce à cette syntaxe, l'enseignant pourrait véritablement configurer les dates des activités comme il le souhaite. Un procédé d'auto complétion pourrait aussi l'aider lors de l'écriture de la syntaxe.

US4 - Create a relative planning from an old moodle course

This is a nice to have. This US should be implemented last.

As an instructor I want to create a relative planning from a Moodle course so that I don't not have to manually enter the relative planning.

• A Moodle course (MBZ) is uploaded
• Activities from MBZ are displayed
• A relative planning course is created from the absolute activities of the MBZ
• The relative planning is saved with a name

Acceptance criteria:

• The instructor does not have to click more than 10 times
• Feedback is provided to the instructor
• The instructor is not aware of the relative planning syntax

Délivrer un programme permettant de parser un document XML provenant de Moodle.

Développer un programme pouvant prendre en argument un document XML provenant de Moodle et parser ce dernier afin de récupérer ses informations (type d'activités, dates des activités).
Lien vers le plan d'itération!

Include the Moodle File activity?

In our initial analysis, we didn't consider Moodle Files as an activity. However, in Moodle, they can have dates for their availability (defining a period when a file can be downloaded). Future versions of CAP could consider this, although it's probably a very infrequent use case.

Première ébauche de l'architecture du logiciel

Délivrer une première ébauche de l'architecture du logiciel (diagrammes et technologies utilisés).
Lien vers le plan d'itération!

Multiple digit delta for days incorrectly parsed

I have a quiz at the end of the semester that needs to go until the final exam. Since I don't know when the final exam is, I just leave the quiz open for 12 days or so:

MQ14 S13F S13F+12d

However, when I look at the calendar, it's set to close TWO DAYS after (not 12):

2016-07-27 08:45    Seminar 13 opens
2016-07-27 12:15    Quiz 14 opens Seminar 13 closes
2016-07-29 12:15    Quiz 14 closes

Is it possible CAP is only parsing the single digit before the 'd'?

Simplify GUI for final steps

Currently there are three buttons for saving at the end:

My suggestion is to simplify this into two buttons:

PREVIEW (which implies a save, shows the PlanETS and regular previews) and DOWNLOAD MBZ (which implies a save).

US3 - Apply a relative planning to a moodle course

As an instructor I want to apply a relative planning for a section to a Moodle course and an ICS of the meetings for this section.

• An ICS file (containing only meetings) and Moodle course (MBZ) are uploaded
• Activities from the ICS file and MBZ are displayed
• A relative planning course is selected
• The relative planning is applied to the MBZ and ICS and the instructor downloads the files

Acceptance criteria:

• The instructor does not have to click more than 10 times
• Feedback is provided to the instructor
• Warnings are displayed if the activities don't match up (ICS, moodle course and relative planning)
• MBZ can be imported in Moodle without any warnings or error
• ICS contains full activity names and absolute dates

Updated MBZ should have course info in file name

Currently, an MBZ is downloaded as "updated.mbz" -- the course information should be in the file name, such as LOG210-2016-02-01-cap-20160422.mbz, where LOG210-02-01 is course id, semester, session (group) and the date at the end is the date of the plan.

Errored plannings are listed

Plannings with invalid calendars or MBZ are in error but are still registered and listed.

The problem is that the create route does not check the validity of the files. It is only checked when getting the planning as it reads the activities and calendar.

user story no 1

As an instructor who teaches the same course in different offerings with different schedules, I want to update dates and times of synchronized activities (in Moodle, SIGNETS and PlanETS) so that the process takes little time and is error-free.

Task List:

• use case Moodle - update activity dates in a Moodle course backup file (XML)
  • display activities
  • change dates
  • save dates to new backup file (XML)
• use case Moodle - synchronize activity dates with new course schedule
• use case SIGNETS - synchronize activity dates with new course schedule

Acceptance criteria:

• The instructor does not have to click more than 10 times.
• The dates and times of the synchronized activities (in Moodle, SIGNETS and PlanETS) are adjusted according to the schedule of the course offering.

Ajouter au programme une fonction pour changer les valeurs des dates des activités Moodle. Créer le nouveau fichier XML.

Les dates des activités peuvent être changées dans le document XML depuis le programme, et un nouveau document XML peut être produit avec les nouvelles dates. Le nouveau fichier pourra être importé manuellement dans un premier temps dans Moodle et on vérifiera que les nouvelles dates soient correctes.
Lien vers le plan d'itération!

US2 - Create relative planning

As an instructor I want to create a new relative planning so that it can be used later to plan a new course.

• Assign a name to the relative planning
• Save the relative planning

Acceptance criteria:

• The instructor does not have to click more than 10 times
• Syntax is simple and respects a similar syntax
• Feedback is available to the instructor as the relative planning is written (calendar or gantt chart TBD)
• Errors in the syntax and loopholes in the planning are detected and the instructors is warned

Saved planning should only save the text of the planning

As a user who saves a planning, I'm surprised when I open a saved planning and I see the following:

Why are there saved Moodle events? Saved ICS events? It was my understanding that only the text of the planning would be saved.

It seems very complicated to remember all the details, such as the MBZ, the ICS, etc. The purpose of a saved planning was to re-use it from semester to semester, or from one group to another. So the ICS and MBZ save makes no sense to me.

Upload images to analysis/design docs

I'm following advice from http://solutionoptimist.com/2013/12/28/awesome-github-tricks/

Support both languages in calendar parser

Xavier's tool can generate both english and french event descriptions.

Currently, the parser only searches for french strings.

Use a grammar for the Plan language

It would be useful to define a simple grammar for the plan language. Documenting the language would be easier and changes can be more easily coded.

Have a look at the PEG.js online tester for an example of a simple grammar parser. There is something for Python, but I'm not sure how easily it can be used. Perhaps start with a PEG.js version and convert? Whatever the way, this kind of parsing is more robust and easier to modify I think.

I hacked up the following on http://pegjs.org/online:

/* test for CAP DSL */
/* currently parsing works, but no results generated */ 
/* Javascript goes inside the {} */

Expression
  = Rule*

Rule
  = head:Activity tail:_ TimingExpression _ EOL {
    }

Activity
 = head:ActivityCode tail:Integer {
   }

TimingExpression 
  = (_ Timing)*

Timing
/* Case for Session, Labs, Practica */
  = head:MeetingSequence TimeModifier? {
  }

ActivityCode 
  = ('E' / 'Q' / 'H')

MeetingSequence
  = ('S' / 'L' / 'P') Integer

TimeModifier
  = ('S' / 'F') (('-'/'+') DeltaTime / ('@' HHMM)) ?

DeltaTime 
  = Integer ('m' / 'h' / 'd' / 'w') 

/* http://stackoverflow.com/a/20123018/1168342 */ 
HHMM
  = ([0-1]?[0-9] / '2'[0-3]) ':' [0-5][0-9] { return text() }

Integer "integer"
  = [0-9]+ { return parseInt(text(), 10); }

EOL
  = [\n]

_ "whitespace"
  = [ \t]*

which parses these examples:

E1 P6
Q1 S1F S2S@4:00
H3 S4S+2h

Support other timezones than 'America/Montreal'

As of now, everything is hardcoded and interpreted as Montreal local time.

The timezone should be an option or in a configuration file.

Let user upload multiple ICS for multiple groups

It would be a nice feature to upload multiple ICS files to the same planning.

Each calendar would be linked to a group.

Use icon (favicon)

I hacked up an icon for CAP (it's a start). There's a useful favicon generator (all platforms) at http://realfavicongenerator.net/

Here's the zipped SVG (github won't allow uploads of SVG?) and a PNG. Note that I reused icons from CC 3.0 sites (the SVG contains the references for attribution, so we need to put those on the web site of CAP if we use this icon).

CAP_icon.zip

US2 - Upload MBZ file

As an instructor I want to upload a course (Moodle backup file) to the server so that it can be used later on to plan a new course.

• Working upload form with a progress bar (feedback)
• Assign a name to the course
• The server saves the association

Acceptance criteria:

• The instructor does not have to click more than 10 times
• Feedback is provided to the instructor
• The association is saved (database or google drive TBD)