Schedule - OpenWilma/parsing GitHub Wiki
Table of contents
- Introduction
- Response
- Explanation
- Some tips
Introduction
Schedule could be obtained in JSON format by requesting (GET) from:
/schedule/export/<your_user_type>/<your_user_id>/ and optional date=12.01.2022 date query parameter
User type consists of basic user type, and adding letter s to user type (excluding passwd).
One exception!
If role is guardians, it should be replaced with students instead.
Response
{
"Schedule":[
{
"ReservationID":5702,
"ScheduleID":514071737,
"Day":1,
"Start":"08:00",
"End":"08:45",
"Color":"#A6CAF0",
"X1":0,
"Y1":0,
"X2":10000,
"Y2":44,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"MA",
"Caption":"MA",
"FullCaption":"Matematiikka",
"Class":"9C",
"Teachers":[
{
"Id":62,
"Caption":"JAA",
"LongCaption":"Jakokulma Jaakko",
"ScheduleVisible":true
}
],
"Rooms":[
{
"Id":195,
"Caption":"001",
"LongCaption":"Cafeteria",
"ScheduleVisible":true
}
]
}
]
},
{
"ReservationID":5708,
"ScheduleID":514071737,
"Day":1,
"Start":"10:00",
"End":"10:45",
"Color":"#A6CAF0",
"X1":0,
"Y1":119,
"X2":10000,
"Y2":164,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"LT",
"Caption":"LT",
"FullCaption":"Liikunta",
"Class":"9C"
}
]
},
{
"ReservationID":5701,
"ScheduleID":514071737,
"Day":2,
"Start":"08:00",
"End":"08:45",
"Color":"#A6CAF0",
"X1":10000,
"Y1":0,
"X2":20000,
"Y2":44,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"MA",
"Caption":"MA",
"FullCaption":"Matematiikka",
"Class":"9C",
"Teachers":[
{
"Id":62,
"Caption":"JAA",
"LongCaption":"Jakokulma Jaakko",
"ScheduleVisible":true
}
],
"Rooms":[
{
"Id":195,
"Caption":"001",
"LongCaption":"Cafeteria",
"ScheduleVisible":true
}
]
}
]
},
{
"ReservationID":5427,
"ScheduleID":514071737,
"Day":3,
"Start":"08:00",
"End":"08:45",
"Color":"#A6CAF0",
"X1":20000,
"Y1":0,
"X2":30000,
"Y2":44,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"Id":20602,
"CourseId":122,
"ShortCaption":"BI",
"Caption":"BI",
"FullCaption":"Biologia",
"Class":"9C",
"Teachers":[
{
"Id":47,
"Caption":"ANT",
"LongCaption":"Ambrosius Anton",
"ScheduleVisible":true
}
]
}
]
},
{
"ReservationID":4853,
"ScheduleID":514071737,
"Day":3,
"Start":"09:00",
"End":"09:45",
"Color":"#A6CAF0",
"X1":20000,
"Y1":59,
"X2":30000,
"Y2":104,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"Id":20605,
"CourseId":130,
"ShortCaption":"GE",
"Caption":"GE",
"FullCaption":"Maantiede",
"Class":"9C"
}
]
},
{
"ReservationID":5703,
"ScheduleID":514071737,
"Day":4,
"Start":"08:00",
"End":"08:45",
"Color":"#A6CAF0",
"X1":30000,
"Y1":0,
"X2":40000,
"Y2":44,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"MA",
"Caption":"MA",
"FullCaption":"Matematiikka",
"Class":"9C",
"Teachers":[
{
"Id":62,
"Caption":"JAA",
"LongCaption":"Jakokulma Jaakko",
"ScheduleVisible":true
}
],
"Rooms":[
{
"Id":195,
"Caption":"001",
"LongCaption":"Cafeteria",
"ScheduleVisible":true
}
]
}
]
},
{
"ReservationID":4999,
"ScheduleID":514071737,
"Day":4,
"Start":"09:00",
"End":"09:45",
"Color":"#A6CAF0",
"X1":30000,
"Y1":59,
"X2":40000,
"Y2":104,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"MA",
"Caption":"MA",
"FullCaption":"Matematiikka",
"Class":"9C",
"Teachers":[
{
"Id":62,
"Caption":"JAA",
"LongCaption":"Jakokulma Jaakko",
"ScheduleVisible":true
}
],
"Rooms":[
{
"Id":195,
"Caption":"001",
"LongCaption":"Cafeteria",
"ScheduleVisible":true
}
]
}
]
},
{
"ReservationID":5704,
"ScheduleID":514071737,
"Day":5,
"Start":"08:00",
"End":"08:45",
"Color":"#A6CAF0",
"X1":40000,
"Y1":0,
"X2":50000,
"Y2":44,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"OP",
"Caption":"OP",
"FullCaption":"Opinto-ohjaus",
"Class":"9C"
}
]
},
{
"ReservationID":5705,
"ScheduleID":514071737,
"Day":5,
"Start":"09:00",
"End":"09:45",
"Color":"#A6CAF0",
"X1":40000,
"Y1":59,
"X2":50000,
"Y2":104,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"OP",
"Caption":"OP",
"FullCaption":"Opinto-ohjaus",
"Class":"9C"
}
]
}
],
"Terms":[
{
"Name":"Syksy",
"StartDate":"2020-06-15",
"EndDate":"2020-12-19"
},
{
"Name":"Kevät",
"StartDate":"2021-01-04",
"EndDate":"2021-06-04"
}
]
}
Explanation on how this works
Let's begin.
Schedule Day
Here's an example schedule "reservation", but we call it as a day:
{
"ReservationID":5702,
"ScheduleID":514071737,
"Day":1,
"Start":"08:00",
"End":"08:45",
"Color":"#A6CAF0",
"X1":0,
"Y1":0,
"X2":10000,
"Y2":44,
"Class":"9C",
"AllowEdit":false,
"AllowAddMoveRemove":false,
"Groups":[
{
"ShortCaption":"MA",
"Caption":"MA",
"FullCaption":"Matematiikka",
"Class":"9C",
"Teachers":[
{
"Id":62,
"Caption":"JAA",
"LongCaption":"Jakokulma Jaakko",
"ScheduleVisible":true
}
],
"Rooms":[
{
"Id":195,
"Caption":"001",
"LongCaption":"Cafeteria",
"ScheduleVisible":true
}
]
}
]
}
ReservationIDis an ID from Wilma's backend, that's the "reservation", TL;DR: When teacher adds new lesson to the scheduleScheduleID- Every user has its own schedule, and this is the ID for thatDay, now this is what I meant by saying, this is a complete mess. Wilma schedule works like this: You have objects called "reservations", which have a day number in it, so if we start the schedule by setting the date to i.e. 19.09.2020 monday,the day 1 = monday, day 2 = tuesday, etc. So You can have for example 4 reservations for Day 1, which is 4 lessons on monday. This is complex, and it should not be this way. (Learn more in the Tips section)StartTime when the lesson starts in formatHH:mmEndTime when the lesson ends in formatHH:mmColorHexadecimal color for the lesson (in my opinion it looks ugly, so I don't use them)X1,Y1,X2,Y2are positions in X and Y axis for Wilma's own UI.ClassClass nameAllowEdit, boolean which indicates should this Wilma user be able to remove anything from his schedule (even if you could, it requires API to do that. We don't have access to any Wilma account that has this enabled, so we are unable to do it the other way)AllowAddMoveRemove, basically same asAllowEdit, but for adding, moving and removingGroups, array of Wilma Courses, or groups. One note: Groups' details change depending on Wilma's internal server settings
Reformat structure
To make schedule's data more understandable, you could format it to a better structure.
We recommend using this structure:
- Day object
- Date string of the day (ie.
yyyy-MM-dd) - An array of every reservation for the day
- In addition, start and end times could include full date in addition with time
HH:mm, which would make it easier to deal with in UI
- In addition, start and end times could include full date in addition with time
- Date string of the day (ie.
With this structure every day in schedule is represented by a date string with full date using formats like yyyy-MM-dd.
Some tips
While working with Wilma's JSON api, one unfortunately bad thing has come to our attention, the level of detail in example: Groups, Exams and others change and vary on some unknown parameters (on the Wilma side, nothing to do with us). When you are writing parsers for Wilma's JSON API or any JSON from Wilma, PLEASE check that these details exist, don't skip that. That could cause crashes and bugs (telling from own experience). A good example would be in Exams. There should be (told by Visma) a course object on every exam (seems logical right?), except sometimes and depending on Wilma server it's just missing. So ALWAYS check for that object's or array's presence before doing something with it.
And about this schedule: Wilma's schedule is as far the messiest thing ever. So when writing parsers, do it the right way after parsing, in example, list of objects which has its Date timestamp (i.e. Monday), and a list that has all lessons for Monday. That's more logical than Visma's approach with its Day integer.
Thank you!