-
Notifications
You must be signed in to change notification settings - Fork 0
Recipients
In order to send a message in Wilma, you should get recipients via this URL:
https://<your_wilma_server>/messages/recipients/?format=json
WIP: Search function has been discovered!
Recipients may vary from this example! There's some stuff not uncovered yet, unfortunately.
This documentation has all what we know about the recipients request.
Be prepared for missing JSON arrays/objects
Recipients for a student (type 2):
{
"ShowMyGuardian":"",
"MyGuardianID":"4291",
"MyGuardianClassID":"187",
"MyGuardianTitle":"Huoltajasi Tapola Titta, 9C",
"GuardianRecords":[
{
"Id":"4291",
"Caption":"<USERNAME>",
"Role":"r_guardian",
"PasswdID":"56",
"ClassID":"187",
"Title":"<USERNAME> (Titta Tapola, 9C)"
}
],
"MyTeacherID":"4291",
"MyTeacherTitle":"Opettajasi Tapola Titta, 9C",
"MyTeacherCaption":"Omat opettajat",
"IndexRecords":[
"Please see \"IndexRecords\" down below"
]
}
Here's another one:
{
"ShowMyGuardian":"",
"MyGuardianID":"5678",
"MyGuardianClassID":"111",
"MyGuardianTitle":"Huoltajasi <STUDENT>",
"GuardianRecords":[
{
"Id":"5678",
"Caption":"<GUARDIAN>",
"Role":"r_guardian",
"PasswdID":"7654",
"ClassID":"111",
"Title":"<GUARDIAN> (<STUDENT>)"
}
],
"MyTeacherID":"5678",
"MyTeacherTitle":"Opettajasi <STUDENT>",
"MyTeacherCaption":"Omat opettajat",
"IndexRecords":[
"Please see \"IndexRecords\" down below"
]
}
Please, ignore "booleans" that tell you to show something i.e. ShowMyGuardian.
ShowMyGuardian should mean that you can show parents in recipients list.
One problem, there can be different versions of ShowMyGuardian, i.e. ShowAnotherGuardian, and others that we don't know.
Better to check if GuardianRecords exists, it's more reliable.
About titles, i.e. MyTeacherTitle or MyGuardianTitle. I think there's no point of using them. They can spontaneously be missing even if GuardianRecords exist.
MyTeacherID is for fetching student's teachers (teachers who teach that student).
IndexRecords is an array of "schools", i.e. if Wilma profile works in two different schools, he/she would have two items in IndexRecords.
This is an example how one IndexRecords may look like (there are different variations of them, depending how Wilma backend is configured):
{
"Id":"12",
"Caption":"Esimerkkilän peruskoulu (0-9)",
"ShowTeachers":"",
"ShowWorkplaceInstructors":"",
"ClassRecords":[
{
"Id":"177",
"Caption":"1A",
"AllowClass":"",
"ClassTitle":"1A",
"AllowSupervisor":"",
"SupervisorID":"3",
"SupervisorTitle":"Koruommel Kirsti (KOR)",
"SupervisorSchoolIDs":"3,12"
},
{
"Id":"178",
"Caption":"1B",
"AllowClass":"",
"ClassTitle":"1B",
"AllowSupervisor":"",
"SupervisorID":"18",
"SupervisorTitle":"Liikkuja (API-TESTI) Liisa (LIS)",
"SupervisorSchoolIDs":"1,12"
},
{
"Id":"180",
"Caption":"2A",
"AllowClass":"",
"ClassTitle":"2A",
"AllowSupervisor":"",
"SupervisorID":"5",
"SupervisorTitle":"Pajala Palle (PAL)",
"SupervisorSchoolIDs":"3,12"
}
]
}
Here's another one:
{
"Id":"23",
"Caption":"Jokelan yläaste",
"ShowTeachers":"",
"TeacherRecords":[
{
"Id":"2048",
"Caption":"Ahonen Elina (AHE)",
"SchoolIDs":"23,50",
"AllowTeacher":""
},
{
"Id":"1548",
"Caption":"Aksinovits Larissa (AKS)",
"SchoolIDs":"19,18,35,31,33,27,41,21,42,23,28,29,34,32,51",
"AllowTeacher":""
},
{
"Id":"1604",
"Caption":"Berg Henri (HEB)",
"SchoolIDs":"50,23",
"AllowTeacher":""
},
{
"Id":"245",
"Caption":"Kiuru Kim (KKI)",
"SchoolIDs":"23,50",
"AllowTeacher":""
},
{
"Id":"1369",
"Caption":"Pöyhönen Timo (TIP)",
"SchoolIDs":"23,50",
"AllowTeacher":""
},
{
"Id":"1912",
"Caption":"Rautio Noora (NR)",
"SchoolIDs":"51,51,23",
"AllowTeacher":""
},
{
"Id":"193",
"Caption":"Räsänen Petteri (PRÄ)",
"SchoolIDs":"23,50",
"AllowTeacher":""
},
{
"Id":"495",
"Caption":"Sajaniemi Hanns-Jyrki (HJS)",
"SchoolIDs":"23,41,28",
"AllowTeacher":""
},
{
"Id":"954",
"Caption":"Sarapik Sanna (SAR)",
"SchoolIDs":"23",
"AllowTeacher":""
}
],
"PersonnelRecords":[
{
"Id":"411",
"Caption":"Brandt Britt-Marie (BRI)",
"SchoolIDs":"23",
"AllowPersonnel":""
},
{
"Id":"519",
"Caption":"Haanpää Krista (KHa)",
"SchoolIDs":"50,23",
"AllowPersonnel":""
},
{
"Id":"185",
"Caption":"Heinonen Arja (AH)",
"SchoolIDs":"28,34,32,18,29,38,36,31,35,41,42,40,41,23",
"AllowPersonnel":""
},
{
"Id":"157",
"Caption":"Hemminki Heidi (HMH)",
"SchoolIDs":"23",
"AllowPersonnel":""
},
{
"Id":"221",
"Caption":"Häkkinen Annukka (A.H)",
"SchoolIDs":"50,23",
"AllowPersonnel":""
},
{
"Id":"471",
"Caption":"Karhu Mervi (MER)",
"SchoolIDs":"23",
"AllowPersonnel":""
},
{
"Id":"597",
"Caption":"Korkolainen Niina (NII)",
"SchoolIDs":"23,50",
"AllowPersonnel":""
}
]
}
(No worries about people's names above. They're published here, so I am not "leaking any data": Public List of Teachers)
As we can see, recipients list vary between Wilma servers.
You may ask, how can I get missing recipients (example1)?
Simple, more requests!
Request to get teachers: https://<your_wilma_server>/messages/recipients/teachers/<INDEX_RECORDS_ID>/?format=json
Request to get own teachers (using MyTeacherID): https://<your_wilma_server>/messages/recipients/teachers/<MyTeacherID>/?format=json
Request to get personnel: https://<your_wilma_server>/messages/recipients/personnel/<INDEX_RECORDS_ID>/?format=json
Request to get workplace instructors: https://<your_wilma_server>/messages/recipients/workplaceinstructor/<INDEX_RECORDS_ID>/?format=json
What about classes? What if my wilma account can show different classes?
Here's an example class:
{
"Id":"178",
"Caption":"1B",
"AllowClass":"",
"ClassTitle":"1B",
"AllowSupervisor":"",
"SupervisorID":"18",
"SupervisorTitle":"Liikkuja Liisa (LIS)",
"SupervisorSchoolIDs":"1,12"
}
To get all student recipients from that class, we take the Id, and do a GET request:
https://<your_wilma_server>/messages/recipients/class/<Id>?format=json
And we get:
{
"StudentRecords":[
{
"Id":"3899",
"Caption":"Hotakainen Hannu",
"ClassID":"177",
"AllowStudent":"",
"StudentTitle":"Hotakainen Hannu, 1A"
},
{
"Id":"3736",
"Caption":"Ihalainen Irmeli",
"ClassID":"177",
"AllowStudent":"",
"StudentTitle":"Ihalainen Irmeli, 1A"
},
{
"Id":"4226",
"Caption":"Jantteri Jari",
"ClassID":"177",
"AllowStudent":"",
"StudentTitle":"Jantteri Jari, 1A"
}
]
}
Besides classes, you can fetch groups (courses) via this URL:
https://<your_wilma_server>/messages/recipients/groups/<REGION>?format=json
Regions specify which groups you want to get.
Here's list of them:
- Group ID, i.e
145 -
past- Past groups -
current- Current groups -
future- Future groups
Here's an example (past, current or future):
{
"ShowOtherTabs":"",
"GradebookName":"",
"CourseTitle":"",
"CourseType":"",
"StudentCount":"",
"Begins":"",
"Ends":"",
"TeacherLinks":"",
"ShowPrintoutsLink":"",
"GradebookHeaders":[
{
"Id":"2",
"Caption":"Nimi"
},
{
"Id":"3",
"Caption":"Kurssin nimi"
},
{
"Id":"6",
"Caption":"Tyyppi"
},
{
"Id":"9",
"Caption":"Koko"
},
{
"Id":"11",
"Caption":"Alkaa"
},
{
"Id":"12",
"Caption":"Päättyy"
},
{
"Id":"13",
"Caption":"Opettajat"
}
],
"PeriodGroups":[
{
"Slug":"\/!01118",
"FullCaption":"FY 9C FY3",
"Caption":"FY 9C FY3",
"NotCommitted":"",
"ID":"20717",
"PrintoutRecords":[
{
"Id":"6",
"Caption":"Päiväkirja, aihealueet",
"TargetId":"20717"
},
{
"Id":"7",
"Caption":"Päiväkirja, arvosteluruudukko 35 riv",
"TargetId":"20717"
},
{
"Id":"8",
"Caption":"Päiväkirjalomake opettajalle",
"TargetId":"20717"
},
{
"Id":"12",
"Caption":"Päiväkirja, aihealueet, vaaka",
"TargetId":"20717"
},
{
"Id":"7",
"Caption":"Päiväkirja, arvosteluruudukko 35 riv",
"TargetId":"20717"
},
{
"Id":"8",
"Caption":"Päiväkirjalomake opettajalle",
"TargetId":"20717"
}
],
"FullView":""
}
]
}
I don't know what every variable mean in Wilma, as this doesn't have any documentation written by Visma.
But I can tell at least, that PeriodGroups contains groups
Another example (Group ID):
{
"StudentRecords":[
{
"Id":"894",
"Caption":"Hanska Hanski",
"ClassID":"304",
"AllowStudent":"",
"StudentTitle":"Hanska Hanski, Tuki 7-9",
"AllowGuardian":"",
"GuardianTitle":"Huoltajat: Hanska Hanski, Tuki 7-9",
"GuardianRecords":[
{
"Id":"894",
"Caption":"Hanska Rouva",
"PasswdID":"42",
"ClassID":"304",
"Title":"Hanska Rouva (Hanski Hanska, Tuki 7-9)"
},
{
"Id":"894",
"Caption":"Hanska Herra",
"PasswdID":"44",
"ClassID":"304",
"Title":"Hanska Herra (Hanski Hanska, Tuki 7-9)"
}
]
},
{
"Id":"4291",
"Caption":"Tapola Titta",
"ClassID":"187",
"AllowStudent":"",
"StudentTitle":"Tapola Titta, 9C",
"AllowGuardian":"",
"GuardianTitle":"Huoltajat: Tapola Titta, 9C",
"GuardianRecords":[
{
"Id":"4291",
"Caption":"<USERNAME>",
"PasswdID":"56",
"ClassID":"187",
"Title":"<USERNAME> (Titta Tapola, 9C)"
}
]
}
]
}
Here we get details about students in the group
Great, we have now loaded all possible recipients (as far as I know can be fetched), what's next?
In order to tell Wilma that this message has ie. guardian as a recipient, we submit recipient tags which contain user type and their ID.
Tag for:
<ID>is recipient's ID
Name: r_guardian
Value (to all guardians): <ID>
Value (to single guardian): <ID>_<PasswdID>
Guardian PasswdID can be found in group students list, and in student's parent list.
Name: r_teacher
Value: <ID>
Name: r_personnel
Value: <ID>
Name: r_group
Value: <GROUP_ID>
Name: r_groupguardian
Value: <GROUP_ID>
Name: r_schoolworkplaceinstructor
Value: <ID>
(list is incomplete at the moment. You can find these in Wilma webUI in a browser by inspecting the recipient element)