Added scheduler documentation in docu/scheduler.md.

mfcb
1 parent 2324efe2
Showing 2 changed files with 25 additions and 0 deletions
docu/project_documentation.md
docu/scheduler.md
@@ -17,6 +17,7 @@ Pushing into this repository will automatically trigger a rebuild of the product
 - Common - holding common classes used by all other subprojects
 - [Drools](drools.md) - Business Rules Management System used to generate the right answer
 - Global - global available services
+- [Scheduler] (scheduler.md) - Scheduling EJB, used to create and handle reminders.
  
 #### Natural Language Processing
 - [ApiAi](apiai.md) - simple RESTEasy client application calling googles Api.ai API
+#Scheduler
+
+##Concept
+The Scheduler service is used to give users the ability to create scheduled reminders. For example, a user of the BeuthBot might want to be informed of the canteen menu on a daily basis. For this he would send a message to the bot, asking it to send him the menu every morning at nine o clock.
+If Rasa identifies this message as an attempt to create such a reminder, it will extract a `createReminder`-intent, along with entities for `date`, `time`, `cycle` and `event`.
+
+##The reminder object
+The `date`-entity contains the given day on which this reminder should be sent.
+`time` contains the time at which the reminder should be sent.
+`cycle` contains a value defining the interval at which the reminder should be sent. This can either be `DAILY`, `WEEKLY`,`MONTHLY` or `ONCE` for reminders that should only be sent on one specific date.
+The `event-entity contains the object of which the user wishes to be reminded. Currently, only canteen-menu-reminders are supported, but this can expanded to any type of object (e.g. course-timetables), given the data-infrastructure.
+
+##Scheduler class
+The Scheduler-class is implemented as a singleton, using the `@Singleton`-annotation, along with a `@Startup`-annotation to make sure an instance of it is created during startup, without the need to be instantiated by another service.
+
+###Creating reminders
+A reminder is created via the `createReminder`-function, which requires a `TaskMessage` and `AppUser` as parameters. The `TaskMessage`-object is required to read out the entities mentioned above, which are used as parameters to create a new instance of a `Reminder`-object which is then stored in the reminders-array and inserted into the database.
+The `createReminder`-function returns the created reminder object which can then be further used by the Drools-service to create a response for the user. Should errors occur along the way, the function returns null, giving Drools the opportunity to tell the user that creation of the reminder has failed. This functionality could be expanded to explain to the user what exactly went wrong.
+
+###Sending reminders
+To send users the reminders they have asked for, the Scheduler-class makes use of the EJB-annotation `@Schedule`, which is set to fire once every minute, searching the database for Reminder-objects whose `date` and `time` settings match the timestamp at which the function has fired, and if so, forwards this information to Drools, where the appropriate messages can be created and relayed to the users.
+
+###Deleting reminders
+If a user wishes to no longer be reminded of these events, he can ask the bot to stop sending him reminders, which will cause drools to fire the `delete reminder` rule, in turn causing the schedulerService to sift through all reminders associated with this user and removing them.
 \ No newline at end of file