Choose a data structure for <timeline> element

wrygiel commented 8 years ago

I am moving this thread from email to GitHub, for future reference. I have removed personal data from PDF screenshots.

Message

From: Janina Mincer-Daszkiewicz <jmd@mimuw.edu.pl>
Date: Sun, Jun 26, 2016 at 8:14 PM
Subject: Use cases for discussion about timelines

During the meeting in Warsaw we discussed so called 'timeline' proposed by Wojtek.

We decided that WP4 and WP3 will deliver examples which will help us to make the final decision.

In the attachment you will find two simple (typical) LAs from the USOS database. These are so called "LEARNING AGREEMENT DURING THE MOBILITY".

To understand the columns 'Reason for change' you need the following dictionary (this comes from the European Commision):

Deletions (D) 1 Previously selected educational component is not available at the Receiving Institution 2 Component is in a different language than previously specified in the course catalogue 3 Timetable conflict 4 Other (please specify)

Additions (A) 5 Substituting a deleted component 6 Extending the mobility period 7 Other (please specify)

Screenshot of LA1.pdf

LA1.pdf

Screenshot of LA2.pdf

LA2.pdf

Wojtek's proposal

Initial version here (obsolete).
And a better one here (based on Janina's suggestions).
Matija's proposal

here

wrygiel commented 8 years ago

I have posted my example (link above).

Let's wait for Matija's alternate proposal before we start discussing.

StefanJahnke commented 8 years ago

The European Commission has a 'Learning Agreement template' that should be our standard for the fields. It includes a standardised table for the Learning Agreement changes as well.

You can find it in attachment of the Desk Research or in the dropbox folder: https://www.dropbox.com/sh/c9p2v8srdqfjm6b/AAB6luvrR1KvR3cVB-Tqzq_8a?dl=0

janinamincer-daszkiewicz commented 8 years ago

Does it differ from what we have? I thought that our implementation in USOS is compliant with the regulations.

StefanJahnke commented 8 years ago

The USOS version has two tables:

Table of the "previous" or "cancelled" version with an overview of all courses taken at the receiving institution that were in the "previous" or "cancelled" agreement and an indication of which is the particular ones removed and for what reason
Table of the "final" version of the Learning Agreement with an overview of all courses taken at the receiving institution, including the newly added ones with an indication that they are the added ones and the reasons for why they are added

The Learning Agreement template has also two tables for the changes:

Table of all changed courses at the receiving institution with an indication whether they have been removed or added
Table of all changed courses at the sending institution

While the USOS file is in a way conveying the same information, it is more complex and includes way more information than in the two tables provided in the LA template. At the same time it does not have any information of potential changes to the courses that might change at the sending institutions. This is probably rarely the case (pure speculation), but on a contractual level makes sense to be added, as the block of courses taken at a receiving institution also need to correspond with a block of courses at the sending institution. Should courses (and therefore also Professors) change, it might lead to ECTS recognition issues, which can be avoided with having such changes also indicated in the 'Learning Agreement changes template'

We unfortunately can't speak of 'compliance', as there is no rule that the LA template needs to be used. The guidelines indicate that the information in the LA template should be considered minimum but even with less information, there is no enforcement of which information institutions put in the Learning Agreement. This also means that more information on the Learning Agreement or the Learning Agreement changes are not inherently wrong. At the same time I would like to quote Anthony: "As long as there is a standard set by EU/EHEA documents, we should try to adhere to it." We should only change this approach if we have good arguments for why we should do things differently.

janinamincer-daszkiewicz commented 8 years ago

Stefan, the USOS example is only the "During the mobility" part of the LA.

StefanJahnke commented 8 years ago

That's what I have been describing as well. Find here once again the Learning Agreement template attached. You can find the part I have been describing under "During mobility" learning-studies_en.docx

wrygiel commented 8 years ago

@StefanJahnke, do you think that the example sent by Janina could influence the structure of <timeline/> subelements?

Note, that this topic was not supposed to be about the contents of the LA itself, but the general way of representing how changes in EWP entities should be recorded (in both LAs and IIAs). And the contents of the LA (to be used in EWP) have not been modeled yet. We cannot really discuss missing data in the model before such has been proposed by WP3.

janinamincer-daszkiewicz commented 8 years ago

I ask Klementyna and Kamil for opinion.

mpuzar commented 8 years ago

I have now uploaded an example on how we think the changelog/timeline should be done. It is much simpler to implement and read, and there is no need to compute the current version each time.

The example is based on Wojtek's example and should be almost directly comparable. Please avoid discussing here as to which data/tags the LAs should or should not have, this topic is only about the technical API and how to handle changes/versioning. https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/blob/master/timeline-examples/timeline_norway.xml

wrygiel commented 8 years ago

Okay then, @erasmus-without-paper/all-members, please take a look at both examples (I have copied permalinks to issue's description too) and comment on which you like better.

WP4's example (mine)
WP3's example (Matija's)

BTW, @mpuzar, the example you have posted is not what you have proposed in Warsaw. The way you explained it then, you didn't want the changelog to be included in the document, and you wanted each <timeline/> entry to simply keep a copy of the entire document at given date (and you wanted the server to make diffs of such documents whenever it needs to extract the list of changes). Your current example is not so different from what we had in mind in the first place!

Key differences:

WP4's proposal requires us keep separate commit-dates and author-dates, as explained here. WP3's proposal keeps author-dates only.
WP4 proposes to reuse common vocabulary from Version Control systems (commits, revisions, tags, see Common Vocabulary section on this wiki page). WP3's proposal tries not to refer to such terms.

Similarities:

Both proposals describe the timeline as a set of deltas.
In WP4's example I have focused on the <timeline/> element only, but - as we have discussed in Warsaw - I also think that we should include the current revision of the document in its entirety (as Matija did) so that simpler clients won't be required to parse the entire timeline before they can read the latest document state. So, keep in mind that WP4's example describes the <timeline/> element only, but timeline is only a part of the <response/>.

Other stuff (probably not important at this point):

I believe that Matija's example does not differentiate between approving nominations and LAs, which will probably be required. There's only a single <approve> element (in our proposal we have two - <approve-nomination/> and <approve-learning-agreement/>).

mpuzar commented 8 years ago

It might have been a misunderstanding. I have no problem with having a changelog inside the document, as long as the receiver doesn't have to parse it unless it is really interested in it (which was my main objection to your initial proposal).

I am also fine with the other possibility discussed in Warsaw, that is to keep a copy of the entire document and let the receiver do the diffs if necessary.

I am also fine with a combination of the above: complete copies AND changelog.

mikesteez commented 8 years ago

I agree with @mpuzar. As a client, I don't want to parse the document to get the current version. We need a changelog and that could be kept separately.

wrygiel commented 8 years ago

@mikesteez, perhaps you have missed this quote from above:

In WP4's example I have focused on the <timeline/> element only, but - as we have discussed in Warsaw - I also think that we should include the current revision of the document in its entirety (as Matija did) so that simpler clients won't be required to parse the entire timeline before they can read the latest document state. So, keep in mind that WP4's example describes the <timeline/> element only, but timeline is only a part of the <response/>.

So, just to make it clear: both of our proposals include the current version, along with the timeline. However, there are some other differences which we would like you to comment on.

georgschermann commented 8 years ago

WP4's proposal requires us keep separate commit-dates and author-dates, as explained here. WP3's proposal keeps author-dates only. WP4 proposes to reuse common vocabulary from Version Control systems (commits, revisions, tags, see Common Vocabulary section on this wiki page). WP3's proposal tries not to refer to such terms.

I don't think its much of a difference, WP4s proposal only wraps the "custom term"-elements into "VCS common term"-elements

the only difference I see is in keeping two different dates for each entry the actual change date and in addition the commit/transfer date, which I don't know if is really needed if we keep the transfer date for each entry i would probably put it beside the change date to flatten the elements but thats only a personal preference i think

mpuzar commented 8 years ago

I agree that we don't need two dates, I have no preferences as to which one to keep (I guess they will be pretty much similar anyway).

@wrygiel - initially, the current version was only optional in your proposal, that is why I reacted to it. It must be mandatory.

wrygiel commented 8 years ago

if we keep the transfer date for each entry i would probably put it beside the change date to flatten the elements but thats only a personal preference i think

The reason why I propose to keep them separate is that a couple of changes can be transferred at a time. Each such change may - in theory - have a different date, and a different author. But when they are committed, they will always be commited at once (by a single HEI). So, even if we resign from commit-dates, I still think that commiter-HEI should be connected to the <commit> (or <timeline_entry>) object.

Do we need them? I'm not sure. It depends on the diversity of the clients. If some partners attempt to design "network-failure-resilient" clients then commit-dates and author-dates may diverge. But - most probably - no such clients will exist.

initially, the current version was only optional in your proposal, that is why I reacted to it. It must be mandatory.

We have misunderstood each other then. I did imply that it can be derived either way, but I also voted to make it mandatory.

erasmus-without-paper / general-issues