search

stichtingsem / technology-prototype

Source code for any services or APIs created in the technology track in Summer 2020
6 stars 1 forks source link

Define School Data entities from SIS #28

Open cliftonc opened 4 years ago

cliftonc commented 4 years ago
niesink commented 3 years ago

Based on the data available in the SIS and several existing API's I think this might be a suitable model/schema:

image

Editable source of the above image can be found here: https://yuml.me/edit/e3150b0c

I've tried to recreate this as an OAS schema definition here on stoplight: https://lukedjn.stoplight.io/docs/sisdata/sisdata/sisdata.yaml and in this yaml file: sisdata.txt

I'm curious to hear what you all think, did I miss crucial entities or properties? Or perhaps I've included too much non-crucial data?

cliftonc commented 3 years ago

@niesink looks like a great start - interested in comments from the other @stichtingsem/technology-track members. Can you connect Stoplight to this github repo and put the files here?

niesink commented 3 years ago

@cliftonc sure, no problem, see: https://github.com/stichtingsem/technology-prototype/pull/30

HJTLN commented 3 years ago

@niesink looks good to me, however to prevent assuming to understand: what is subject-choice in this context?

niesink commented 3 years ago

@HJTLN a subject-choice translates to a vakkeuze in Dutch. Meaning a specific student chooses to follow a specific subject (e.g. Physics) at a specific level (e.g. HAVO). It has an optional reference to a class, as especially in the months/weeks leading up to a new schoolyear a student may have made their subject-choices but they might not be enrolled in a certain class/group for that subject yet. I'm obviously open to other suggestions, both for naming (coursechoice maybe?) and for the model itself.

I'm also fine with adding e-mail address if this is required for digital delivery. It should be noted however that this field will have to be optional as, at least in our SIS, there might not be an e-mail address registered for a student.

niesink commented 3 years ago

I've created a PR that adds an email address to a student (and fixes some camelCase-naming) in #31

A new version of the visual representation of this model: image

incl. the editable source: https://yuml.me/edit/ffa31caa

edwinverwoerd commented 3 years ago

This data is for the MP I hope, otherwise we have a problem with the date of birth. And I see that this is an replacement of the current UWLR-FDE profile. Is that correct??

I also see that the name field is an string. I know that many systems now put the firstname ,... lastname together in 1 field. I hope that we can split this to the normal NEN standard for profile data to Firstname = String ; Lastname = String and "tussenvoegsel"=String.

What is the definition of educational code in this dataset?

cliftonc commented 3 years ago

This is the full dataset, once we create the scopes we can define what data is actually available to each scope.

cliftonc commented 3 years ago

@niesink looking at the data above I think we have (potentially) three scopes from a data availability perspective:

The logical mapping here is then:

LMS / LP - only request las.user-identification and optionally las.class-subject-membership (if they need it) MP - requests all

Related: https://github.com/stichtingsem/technology-prototype/issues/32

@edwinverwoerd does this match your expectations? Happy to talk through how the Oauth scopes will be used to restrict access to data if there is still any confusion?

cliftonc commented 3 years ago

This data is for the MP I hope, otherwise we have a problem with the date of birth. And I see that this is an replacement of the current UWLR-FDE profile. Is that correct??

I also see that the name field is an string. I know that many systems now put the firstname ,... lastname together in 1 field. I hope that we can split this to the normal NEN standard for profile data to Firstname = String ; Lastname = String and "tussenvoegsel"=String.

What is the definition of educational code in this dataset?

Commenting on the name part, I think we should explore and be clear on why it is needed.

Learning Platform / LMS:

Marketplace:

mcginkel commented 3 years ago

Is the postcode and housenumber "Minimal data"? I undestand that a distributer needs it, but a learning application has no need to have that data. Does every learning app needs the same data? Do they all classes or just the classes for the subjects they provide courses for?

edwinverwoerd commented 3 years ago

I'm starting to worry a bit about the data set. It now seems that the data set as described is generic for all parties (services). This does not seem right to me. An LP does not need a zip code or date of birth to play the content. The MP does need this data for its purpose (process). So we are dealing with different profiles. If the goal of this issue is to make 1 standard generic definition and then designate a specific profile depending on the process step, fine. But then we must describe this well to avoid confusion.

mcginkel commented 3 years ago

Yes that is what I would add. Th UWLR-L way (make profiles and supply field values based on the profile) is not my preference. I would split this into 3 seperates: SIS2LA, SIS2LMS, and SIS2MP, each with own set of fields

cliftonc commented 3 years ago

I feel we are miss understanding the steps:

Happy to get on a call to discuss - as this is the fundamental security and privacy model we previously agreed.

cliftonc commented 3 years ago

@mcginkel re.

I would split this into 3 seperates: SIS2LA, SIS2LMS, and SIS2MP, each with own set of fields

This is exactly the three scopes I define above, though I would prefer we describe them based on the purpose, not on the name of the consuming service as that provides more flexibility in the long run (discussion can happen here: https://github.com/stichtingsem/technology-prototype/issues/32)

edwinverwoerd commented 3 years ago

I think that it is good that we define the several scopes so that we do not have an discussion what is in it. Maybe it is a good idea to have a call so that we also can take notes of the "functional" data scope from the finance track.

And I think that for security in relation to the consent that the school should give on the use of a scope it is also good to give them a logically understandable name / label,

niesink commented 3 years ago

In addition to the healthy discussion on the use of oauth scopes (which seems to have reached on conclusion, apart from the exact definition of the scopes) I think the only still outstanding question is:

What is the definition of educational code in this dataset?

What I meant by that is the 'elementcode' of the 'opleiding', as defined here: https://wetten.overheid.nl/BWBR0042332/2020-07-01 In other words 0372 for a student that's enrolled in 'HAVO Economie & Maatschappij'.

However I'm not completely convinced this information is necessary for either MP or LA. Perhaps the list of subject-choices ( = 'vakkenpakket') is sufficient?

niesink commented 3 years ago

I noticed that the entity Class now has a start- and enddate. I'm not sure this is accurate/relevant. I think what's more important is that start- and enddate of the 'enrollment'/participation of a certain student in a class. Similar to subject-choices a student can change class at any moment during the school year.

Related to this I think we have to consider the concept of reference dates when specifying the API. When retrieving the details of a student it does not seem relevant to exchange what subjects or classes the student took part in 4 years ago. At the same time, especially for the marketplace, future subject-choices can be very relevant while ordering learning materials for next school year, so it's not an option to only include 'active' subject choices/classes. Including an optional reference date (that defaults to 'today') in the different /student/-calls might be a useful solution.

cliftonc commented 3 years ago

I noticed that the entity Class now has a start- and enddate.

I copied this from your picture - feel free to remove.

Agree re. reference dates. Could you do it based on school year vs a specific date? e.g. it defaults to the current, but you can specify one?

Are you able to make the change in Stoplight or do you want me to?

hhaarsma commented 3 years ago

I see the use of Class, for the learnign application of Noordhoff there have been talks about classes vs groups; is this something we should address? With groups we may be more flexible; for instance at the school of my kids (primairy education) they have their normal classes, but for reading they rearrange all students in groups based on their level with reading (so that is cross class/year).

hhaarsma commented 3 years ago

Is the postcode and housenumber "Minimal data"? I undestand that a distributer needs it, but a learning application has no need to have that data. Does every learning app needs the same data? Do they all classes or just the classes for the subjects they provide courses for?

In addition, is DateOfBirth required?

niesink commented 3 years ago

I copied this from your picture - feel free to remove.

@cliftonc ah yes, I see now, my mistake. I think we should remove it, are you able to do that. If not I will try to do so tomorrow.

As for the reference date, yes we might be able to use a school year instead. This would mean by default you only get subject-choices for the current school year, but you'll still have to look at the start and end dates of the subject choices to figure out which ones are 'active' today.

@hhaarsma I agree on the groups vs. class thing. That's the reason I didn't assign a specific level or even subject to a class. I think you're right that it is quite feasable that students of different levels, years and even official subjects are grouped in the same class. I'm fine with renaming the entity Class to Group if that helps by the way.

On the subject of dateOfBirth I'm not really sure, I think that's for the LA's and MP's (and perhaps LMS's) to answer? It might be relevant when determining the role/rights of the student's parents, as this depends on whether or not the student is above or below 16/18 years of age?

cliftonc commented 3 years ago

@niesink happy to make the changes, I'll also amend class to group - is it useful to add a type? e.g. class or work-group - is this type of information in the SIS generally?

niesink commented 3 years ago

@cliftonc at least in our SIS this information/distinction is not present as such, also I'm not sure if it's relevant for the use case of the LA or LMS. And I think the whole concept of a Class/Group is irrelevant to the MP as they're probably only interested in subject-choices, but I might be wrong there.

cliftonc commented 3 years ago

Ok, I've pushed the changes into the same PR we were using earlier based on this thread to keep it together:

https://github.com/stichtingsem/technology-prototype/pull/40/files

^ I assumed (perhaps wrongly?) that if we add some sort of schoolYear concept we would also want it on the entities that have start/end dates - this may be duplication, but I suspect better to have an explicit value?

niesink commented 3 years ago

Yeah that might be useful. Only consequence we should be aware of is that such an entity can now no longer span multiple school years?

I believe that in our SIS subject-choices sometimes do span multiple years especially in the upper levels (bovenbouw) where a student has one subject-choice for their 4th and 5th year.

The fact that we've implemented this model internally in our SIS of course doesn't mean we can't translate such a multi-year subject-choice into seperate subject-choices, but I think it's something to take note of.

cliftonc commented 3 years ago

Maybe 'schoolPeriod'? So you can have more than one per year.

niesink commented 3 years ago

I'm not sure I understand what you're proposing. The constraint we've introduced is only having one school year per subject-choice, not having only one subject-choice per school year, I think? Could you maybe give an example of what you mean by schoolPeriod?

cliftonc commented 3 years ago

I just mean to make it more generic, not change the constraint. schoolYear implies that the period within which a subject-choice can exist must be a year, which for some areas isn't true - so making it schoolPeriod means that you could use values like 2020-H1 or the like (more than one planning period per year), and it can make sense still in that context. Exactly same purpose, just a bit more flexible. I have no idea how the SIS model this all of course, so will rely on your judgement and hope others also chime in!

niesink commented 3 years ago

Ah yes I see what you mean.

In our SIS a subject-choice is not really linked to such a period (or even a school year), it just has a start and enddate. We could of course use a school year or period to filter subject choices, but it's probably hard to 'invent/generate' a schoolPeriod as a property for a subject choice that only has a start and end date.

I'm also not sure if the MP's/LA's/LMP's would use this schoolPeriod property, so it might not be worth it at this time to come up with a meaningful 'algorithm' (to determine the schoolPeriod given a certain start and end date).

So I think my suggestion for now would be to only use schoolYear as way of easily specifying a 'reference period/range' when requesting a list of subject-choices and not implement it as a property of a subject choice (instead letting a subject choice just have a start and enddate).

hhaarsma commented 3 years ago

On the subject of dateOfBirth I'm not really sure, I think that's for the LA's and MP's (and perhaps LMS's) to answer? It might be relevant when determining the role/rights of the student's parents, as this depends on whether or not the student is above or below 16/18 years of age?

DateOfBirth is now in the student-delivery part, so the LA will not receive this information; this is only for the marketplace. I am just wondering if the marketplace needs this information.

hhaarsma commented 3 years ago

With respect to the schoolPeriod I am wondering to what extend it is needed. If we only communicate the current situation, then it is relevant for the system that is providing the data to apply filters. But if this data is required, then I would suggest to use a start and an end date, then we have the most flexible situation that is less likely to require a change (if it will be used later in a not foreseen way).