search

erasmus-without-paper / ewp-specs-api-iias

Specifications of EWP's Interinstitutional Agreements API.
MIT License
4 stars 13 forks source link

Making changes in the approved agreement #92

Closed janinamincer-daszkiewicz closed 1 year ago

janinamincer-daszkiewicz commented 1 year ago

This issue is continuation of the discussion from https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/41, limited to changes in the approved version of the IIA, other than termination.

janinamincer-daszkiewicz commented 1 year ago

There are two options:

  1. Changes in IIAs are rare and should be treated as exception. Approved IIA cannot be changed. If changes are necessary, IIA should be terminated and the new IIA should be signed.
  2. Changes in IIAs happen often and they should be supported. Option (1) is not acceptable. Users want to trace (minor) changes as being part of the existing IIA.

@pleys, please check with Business Process Owners what is their recommendation.

If we choose (1), solution described in https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/41 solves the problem.

If we choose (2), we first have to agree on what kind of changes can be treated as minor and handled by (2).

The possible solution to (2) is versioning of IIAs:

Comments from providers shared in chat on 2022-10-19 (see the whole content of the chat in the shared drive):

Please share your opinion in this issue. We will discussed this topic further during the Infrastructure Forum meetings in 2022 and will vote on the proposal either on 2022-11-16 or (final date) 2022-12-14.

demilatof commented 1 year ago

I have fully explained my proposal here and answered in chat about versioning ("Why versioning? ...").

As concern

  1. Changes in IIAs are rare and should be treated as exception. Approved IIA cannot be changed. If changes are necessary, IIA should be terminated and the new IIA should be signed.

I think that the number of changes in IIA should make no difference: what have been agreed is agreed and impacts in the internal system. If changes happen often, this mean the exchange of a huge of useless data (we are interested in what is in effect, not in what was in effect). Moreover the first point is based on the possibility that changes in IIAs are rare. But what kind of changes we consider? If A partner changes a contact, this doesn't much matter (the cooperation conditions hash code already ignores it). Therefore, we provide a new XML, if asked, with the same hash code and updated contacts. We should ask the administrative staff, but mine has already confirmed that this is the more frequent event.

If A partner makes a change that impacts the hash code, the new IIA is something different. This event could happen, even if is less frequent. Our internal system requires that a given IIA id identifies uniquely a given set of cooperation condition rules. Stating that IID-ID 1234 provides 3 places until 2023/2024 and after that 4 places would be a big mess. Much better close and create e new IIA with a new IIA-Id

jiripetrzelka commented 1 year ago

I suppose we are discussing solely changes that are part of cooperation-conditions and need to be approved, not changes e.g. to contacts.

My understanding is that changes in IIAs happen quite often and some kind of versioning is a necessity in terms of internal processes within each mobility system.

When it comes to the question of what to publish to EWP, I think that sticking to the original IIA ID gives much more clarity to the counterparty. The partner does not have to guess if a new IIA with a new ID is a replacement of another IIA or a completely new IIA or a duplicate caused by user error or mobility system error (these errors are unfortunatelly still very common).

Next, I suggest to get inspired by the versioning present in LAs, which works quite well. We could, for example, extend the cooperation-conditions element into three subtypes:

Based on the presence/absence of the above elements, it would also be clear in which state the IIA is: If there was just cooperation-conditions-proposal, it would be a ready for approval (original IIA). If there was just cooperation-conditions-first-version, the IIA's original version would be approved. If there was cooperation-conditions-first-version + cooperation-conditions-proposal, the original version would be approved and an amendment would be ready for approval. After that, there would be the cooperation-conditions-first-version + cooperation-conditions-approved-amendment. And so on.

And just like in LAs, only the last approved amendment would be displayed.

janinamincer-daszkiewicz commented 1 year ago

I assume that for backward compatibility element cooperation-conditions would be equivalent to cooperation-conditions-first-version? Could you give an example demonstrating your proposal? At which level these elements (cooperation-conditions-proposal and cooperation-conditions-approved-amendment) would be placed? On a global level for all mobility-specs? Mobility-specs don't have ids yet, we would have to add ones. Separately for each mobility-spec to show the action on this one?

demilatof commented 1 year ago

When you wish to introduce versioning being inspired by the versioning present in LAs, do you take into account that they are really different processes? The LA follows the story of a student, and versioning is really important. But every change impacts only the student and not other activities.

When we change an approved IIA we affect a lot of internal process that is evolving asynchronously and decoupled from EWP Network. And versioning doesn't protect them from changes. E.g.: we use IIA IDs to build the manifest, to open the applications, to make the selections, to fill the same LA. Every single task has different timings, but all of them are tied to the same ID.

What could happen if the same IIA ID today can offer 2 places and tomorrow only one? What of our internal process must be tied to the 2 places version and what process must be tied to the new single place version? Versioning could be understood by human, but not easily followed and implemented in an asynchronous environment. Versioning requires a version number and a validity date, but nevertheless it's not enough. Indeed, once we agree that an IIA can be changed thanks to versioning, we have to accept that sometimes it can change two or three times in a week.
We cannot accept to keep the same IIA Id to identify different agreements and we cannot reconsider our full system in a few weeks to follow new solutions that could be avoided.

Moreover, what is the interest in transmitting every time the previous conditions? The agreement in effect brings the current conditions. The previous are kept in internal system to conclude the internal process and could be provided on demand.

Every internal system is different, a versioning at EWP level is too much intrusive. I think that every internal system is the only one that could trace the different versions (present IIA ID - previous IIA ID). And if the partner wants to look at a closed IIA, it could ask for the old IIA ID (even if there are a few reasons, because the partner has its copy, that should be closed on its turn).

A good implementation in the internal system doesn't have any problem to automatically close an IIA and reopen an identical one for the changes. The new IIA IDs are the versioning you are looking for. If we close and reopen for the changes we save a lot of the specifications we have used until now.

If we introduce versioning we are not able to implement before a year. In the meantime, we will not be able to exchange nothing in EWP Network because we cannot keep trace of versioning in our system.

jiripetrzelka commented 1 year ago

Below is an example of my proposal. I have changed the names of the elements a bit so that conditions-hashes would not be affected by the change in the name of the cooperation-conditions element.

  1. Draft

    <agreement-draft>
<cooperation-conditions>...</cooperation-conditions>
<conditions-hash>000</conditions-hash>
</agreement-draft>

  2. Ready for approval

    <first-version-proposal>
<cooperation-conditions>...</cooperation-conditions>
<conditions-hash>111</conditions-hash>
</first-version-proposal-proposal>

  3. Approved

    <first-version-approved>
<cooperation-conditions>...</cooperation-conditions>
<conditions-hash>111</conditions-hash>
</first-version-approved>

  4. Approved and amendment ready for approval

    
<first-version-approved>
<cooperation-conditions>...</cooperation-conditions>
<conditions-hash>111</conditions-hash>
</first-version-approved>
... 222 

5. Approved first version and approved amendment
... 111 ... 222 

6. Approved first version, approved amendment and another amendment ready for approval
... 111 ... 222 ... 333 

7. Approved first version and approved last amendment
... 111 ... 333
janinamincer-daszkiewicz commented 1 year ago

cooperation-condition element may carry 10 different mobility-specs, with no ids. We want to change one number (from10 to 5) in one of the mobility-specs. How would the amendment-proposal look like?

jiripetrzelka commented 1 year ago

@demilatof Here are some counterarguments:

What could happen if the same IIA ID today can offer 2 places and tomorrow only one? What of our internal process must be tied to the 2 places version and what process must be tied to the new single place version?

You could add a validator that does not allow the coordinator to approve the IIA amendment with fewer number of places in case the number of existing successful applications/nominations would exceed this new limit. You would need such a validator also in case you were creating a new IIA with a new ID and not a new version of an existing IIA.

Indeed, once we agree that an IIA can be changed thanks to versioning, we have to accept that sometimes it can change two or three times in a week.

That's exactly what I see with some IIAs today. If the partner decides to change the IIA 10 times before approval, they can do it with a new version of an existing IIA in the same way that they could do it with a new proposal with a new IIA ID.

Moreover, what is the interest in transmitting every time the previous conditions? The agreement in effect brings the current conditions. The previous are kept in internal system to conclude the internal process and could be provided on demand.

I don't think that would be too much additional data. My guess is that including the PDF is much worse if you counted every byte transmitted.

A good implementation in the internal system doesn't have any problem to automatically close an IIA and reopen an identical one for the changes. The new IIA IDs are the versioning you are looking for.

I don't think so. A new IIA ID would mean that you would have to re-assign the IDs in all referenced records, such as nominations and then invoke CNRs of all referenced records that would be affected. Then your partner would also have to re-assign all IDs in referenced records and I think this would generally lead to quite a lot of confusion. Not to think about the extra work to link the matching IIAs together again.

jiripetrzelka commented 1 year ago

cooperation-condition element may carry 10 different mobility-specs, with no ids. We want to change on number (from10 to 5) in one of the mobility-specs. How would the amendment-proposal look like?

The amendment-proposal would be a copy of the previous approved version with just this one change.

demilatof commented 1 year ago

@jiripetrzelka I think you don't fully understand the problem of an existing internal system. I apologize if I'm too direct, but your solution is really chaotic in my opinion. In real life someone could put in draft, ready for approval, back in draft and so on. If I follow on my system a partner that has no clear idea, I complicate my system and my office work. All that said, you counterarguments for me are weak:

@demilatof Here are some counterarguments:

What could happen if the same IIA ID today can offer 2 places and tomorrow only one? What of our internal process must be tied to the 2 places version and what process must be tied to the new single place version?

You could add a validator that does not allow the coordinator to approve the IIA amendment with fewer number of places in case the number of existing successful applications/nominations would exceed this new limit. You would need such a validator also in case you were creating a new IIA with a new ID and not a new version of an existing IIA.

Why should I do so? I may stipulate now that the new IIA will be in effect next year, with less places. For the incoming year I've the old IIA with old IIA Id and in the meantime I can manage the new IIA (with less places) thanks to its new IIA id. How could you do with versioning? Another example, the change could be about ISCED-F. With the same IIA ID and with versioning, how can you distinguish in your system if a student mobility is tied to the old or new ISCED-F?

Indeed, once we agree that an IIA can be changed thanks to versioning, we have to accept that sometimes it can change two or three times in a week.

That's exactly what I see with some IIAs today. If the partner decides to change the IIA 10 times before approval, they can do it with a new version of an existing IIA in the same way that they could do it with a new proposal with a new IIA ID.

Yes, but with a new IIA ID we have no problem for the old IIA ID, that keeps going on for a year. Because the new IIA ID will require a new approval, it doesn't matter if there will be several changes in a week until there will be a new approval. And even if there will be changes after the new approval, they don't make problems until the new IIA ID will have produced an effect (most probably, with applications). We could have ten new IDs, but only last could be important. With versioning every change impacts on a working system due to the same ID.

Moreover, what is the interest in transmitting every time the previous conditions? The agreement in effect brings the current conditions. The previous are kept in internal system to conclude the internal process and could be provided on demand.

I don't think that would be too much additional data. My guess is that including the PDF is much worse if you counted every byte transmitted. For me your example contains already too much data, if not for a transmission, surely for storing multiple update and representing them correctly to the user.

A good implementation in the internal system doesn't have any problem to automatically close an IIA and reopen an identical one for the changes. The new IIA IDs are the versioning you are looking for.

I don't think so. A new IIA ID would mean that you would have to re-assign the IDs in all referenced records, such as nominations and then invoke CNRs of all referenced records that would be affected. Then your partner would also have to re-assign all IDs in referenced records and I think this would generally lead to quite a lot of confusion. Not to think about the extra work to link the matching IIAs together again.

Absolutely not! You are saying the exact opposite of the main purpose of keeping old IIA ID! The advantage of closing an IIA is that all the processes in course keep having their old ID and their old rule. All the new will follow the new rules and therefore will have the new IIA ID. The great confusion will be brought by several versions that a user has to follow to understand if and what is changing. If you close an IIA you make a final dot and you start again, as it were a new agreement. It could even be identical, it doesn't matter. The user will be sure that nothing will make problem with current procedures. I don't understand where you see extra work to link the matching IIAs together again, just email the new IIA ID to facilitate the operation, if you wish.

But I agree that generally matching IIAs together (when you know nothing of the partner's IDs) is a heavy duty; this is one of the great weaknesses of the EWP Network.

One more consideration, less technical but more practical: the EWP network in my opinion should not encourage too many changes in an IIA. A change should occur seldom and without involving the partner in a ping pong to follow my afterthoughts

umesh-qs commented 1 year ago

I do not see any need to

Below is an example of my proposal. I have changed the names of the elements a bit so that conditions-hashes would not be affected by the change in the name of the cooperation-conditions element.

  1. Draft
<agreement-draft>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>000</conditions-hash>
</agreement-draft>
  1. Ready for approval
<first-version-proposal>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>111</conditions-hash>
</first-version-proposal-proposal>
  1. Approved
<first-version-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>111</conditions-hash>
</first-version-approved>
  1. Approved and amendment ready for approval
<first-version-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>111</conditions-hash>
</first-version-approved>

<amendment-proposal>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>222</conditions-hash>
</amendment-proposal>
  1. Approved first version and approved amendment
<first-version-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>111</conditions-hash>
</first-version-approved>

<last-amendment-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>222</conditions-hash>
</last-amendment-approved>
  1. Approved first version, approved amendment and another amendment ready for approval
<first-version-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>111</conditions-hash>
</first-version-approved>

<last-amendment-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>222</conditions-hash>
</last-amendment-approved>

<amendment-proposal>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>333</conditions-hash>
</amendment-proposal>
  1. Approved first version and approved last amendment
<first-version-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>111</conditions-hash>
</first-version-approved>

<last-amendment-approved>
  <cooperation-conditions>...</cooperation-conditions>
  <conditions-hash>333</conditions-hash>
</last-amendment-approved>

This is a very complicated and unnecessary. Each system might be already keeping the history if changes in API responses, not only for IIA but also for other API. New status filed should serve the purpose. We are strongly against this proposal.

jiripetrzelka commented 1 year ago

This issue started with the question whether changes are rare or not. Well, in case of Masaryk University, about 200 IIAs out of 2000 IIAs were amended during the period 2014-2021. 10 % is, in my opinion, not an exception. If you disagree, please state your quota and what is the highest percentage of amended IIAs that you would still consider to be an exception.

I have looked at some of the amendments. They mostly concern the number of persons or months/days. For example, an IIA was signed for 2014-2021 and, in January 2016, they needed to change the number of students from 2016/17 onwards from 2 to 3. In some IIAs, they did this again later, for example in January 2017, they would increase the number from 2017/18 onwards to 4.

Another example I found was that they needed to decrease the number of months from 12 to 10.

Of course, in the olden days, IROs created amendments mainly for these important things, while now we have to consider anything that changes the hash and think about amendments for minor changes such as changing the other-info-terms.

In the original post, Janina mentioned the possibility of termination of the original IIA and creating a new IIA in case changes are rare. Let's assume that someone argues that changes are rare indeed or just denies Janina's assuption altogether and wants to use terminations + new IIAs for all changes regardless of how common they are.

There are two problems. First, termination was never supposed nor used for the purpose of creating amendments. I think that we should follow the practices of IRO and not use termination for something it was not supposed to be used for. Second, termination is required to be given at 1 September of the preceding academic year at the latest, while changes can be made up to January. Obviously, because in January XXXX, nominations for XXXX/XXXX+1 start and I would assume that the necessity to make some changes appears around this time.

@demilatof Could you please clarify what you mean by "closing" an IIA? I assume it is not an equivalent of unilateral "termination". So what is it then? Some special kind of change that could be agreed upon by both parties up until January XXXX and that would stipulate that all mobilities from XXXX/XXXX+1 would become void? How would this change be confirmed by the other party if not by confirming some changed hash?

In our system, I see that most new IIAs are being signed either for the entire period 2021-29 or for at least 5 years. So what you, demilatof, suggest, would lead to about 10 % of these IIAs to be divided into 2 or possibly more IIAs in the years to come. I see that it would, in a way, be a clean solution. It would certainly require quite a lot of discipline from IROs (which could be attained by validators). It would not allow them to make minor changes retrospectively. For example, if there was a student mobility for 2021-29 defined and IROs would find out during nomination for 2023/24 that they have forgotten for example to state a language requirement or some detail in the other-info-terms and there would already be, say STA mobility bound to the IIA in 2022/23, they would still have to cut the IIA in two, "close" the original IIA in 2022/23 and create a new IIA from 2023/24. The more forgotten details, the greater risk of the IIA having to be split later.

I generally don't like the idea of an IIA being split into more IIAs. An IIA corresponds to a specific cooperation between specific units and coordinators consider it to be one cooperation and want it to treat like that. But I guess you could still keep the links of all the parts in the system and help IROs to keep track of IIAs that belong together.

@demilatof Please confirm whether I have understood correctly your idea and how exactly you would handle the "closing".

Now, taking the idea further. Let's say that we are still not happy with the solution above because of the necessity to split IIAs. If we already assume this high level of discipline, i.e. no changes later than 31 January for the next academic year, we could still think of changes in a way that would define:

So, for example, in January 2023, the amendment-proposal would consist of this information:

These two pieces of information will have to be transferred in any case. What is the benefit of transferring the first information in the original IIA and the second information in a new IIA? This would only make sense in case you would find a solution in which the information that mobilities from 2023/24 become void would not require an approval from the counterparty. Then, yes, the original IIA could be kept "clean" to a certain degree, that is, a new status field might be enough. But what if the partner later comes and argues that they have not approved the closing of the IIA from 2023/24 and that in fact they consider the second IIA to be an addition, not a replacement of the original IIA?

jiripetrzelka commented 1 year ago

I think I have found the answer to the question above:

The amendment could be a document whose hashed and approved part would contain:

By approving the amendment, partner would confirm the closing of the original IIA while the original IIA could remain intact.

demilatof commented 1 year ago

@jiripetrzelka I disagree not with the number of changes, but with the fact that we should choose a solution according the frequency of changes, as proposed by Janina, without keeping in account the effect of a choice in every internal system. I understand the timings decided by IRO, but IRO knows the impact of a change in an internal system? With papers we can adjust almost everything, without papers we must be more compliant with IT implications. And the same IIA id cannot represent two different situations in the meantime, depending on the context (IIA management, application, nomination and so on). Not without a whole review of the internal system. But I cannot believe that someone asks us to rebuild our internal system in two months when these issues should be arose two years ago!

For me an IIA should be in effect until both of the parties decide to change it ("closing" in my vision). Therefore we should have a Closing CNR and a Closing Approval, similar to Approval CNR and Approval with the difference that they must contain the last academic year of validity. If you like to read more https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/83#issuecomment-1221635924

If the closing is accepted, we could add two elements to the IIA Get Response, outside the cooperation condition to not change the hash:

I understand that this solution could appear "heavy", but it avoids a lot of complications, first of all I think it can answer your last question "But what if the partner later comes and argues that they have not approved the closing of the IIA from 2023/24 and that in fact they consider the second IIA to be an addition, not a replacement of the original IIA?". Once both of the parties agree on closing, what happens next doesn't matter: a new agreement, the same but changed, the same identical because of a second thought. If there isn't a real closing, a partner should not create a modified version of the IIA.

If we didn't have other processes, I would accept continuous changes. But IIA are agreements and we should respect them until both parties agree to change something. The problem arises when a partner makes changes and the other disagrees. We lost the initial agreement, the one that is in effect, and could be cumbersome to roll back even if we keep track of changes thanks to versions.

Obviously we could accept some changes (ISCED, languages, increase in number of places or months) and not others (less places). But, again, this option requires a deep analysis whilst deadline is coming.

Just to do a bit of brainstorming, another solution could be that every time an IIA is approved, the approval produces automatically N sub agreements (with N sub IIA-Id), one for every mobility year. If a change is made before January it modifies all sub IIAs, if it is made after January it modifies only N-1 IIAs, whilst the first IIA, that is producing effectw in the current academic year, is not touched (the different IIA Ids save internal systems).

Again, my main interest is not in how we can track changes, keeping the same IIA Id, but avoid that the same IIA-Id represents at the same time two different conditions (typos or not)

spinho-uporto commented 1 year ago

I think the changes we are going to decide should take into account the impact on IRO services.

Why not continue with the same process they had before, with agreements and addendums, both signed?

Our IRO, whenever there were changes to the initial agreements already signed, created addendum to add more cooperation conditions to those made available in the agreement. They never had situations where they have to delete/change the initial conditions. In situations where the changes to the agreements do not fit into an addendum, how have other institutions done until before EWP?

I think that if the situations of changes that cannot be made through an addendum are few, there is no need to drastic changes in the functioning to which the IRO are accustomed. Perhaps for these cases the agreement has to be terminated and another one made.

I suggest that the addendums continue to exist and be signed just like the agreements. These would have their own iia_id identifier. A new element could be created in the XML to link to the original agreement.

I'm afraid that very complicated changes will make the IRO's job bigger and more difficult than it was when they have to sign in pdf.

demilatof commented 1 year ago

@spinho-uporto About the IROs... Just out of curiosity, your IRO knows what involves the master-master model to set up the EWP Network? In my opinion, this is a short list of what an IRO (e.g. A) has to do:

And then your IRO has to repeat this task list over all their partners. Am I wrong?

janinamincer-daszkiewicz commented 1 year ago

I will try to summarise:

  1. @demilatof - the proposal is expressed in https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/83#issuecomment-1221635924, and summarised in the next post. Generally the idea is to disallow changes to IIAs, and in case some changes are needed, terminate the old IIA (4 new APIs) and create the new one (@jiripetrzelka calls this 'splitting IIAs).
  2. @jiripetrzelka argues that changes concern app. 10% of IIAs, splitting is not a good solution, better to handle changes by amendments to existing IIAs (keeping the original IIA id), in a way similar to what we have for LAs (may be something simpler can be elaborated).
  3. Others e.g. @umesh-qs, @demilatof, @spinho-uporto are not in favour of amendments similar to LAs as too complicated.

Is that correct?

demilatof commented 1 year ago

@janinamincer-daszkiewicz

I will try to summarise:

For me, you have correctly summarised, but perhaps there are only 2 new APIs number, as I explained here https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/83#issuecomment-1304954640

spinho-uporto commented 1 year ago

@demilatof

About the IROs... Just out of curiosity, your IRO knows what involves the master-master model to set up the EWP Network?

There was a session with them to show the changes they were going to see in the agreements and the steps they would have to follow. They were told that each partner would continue to have the agreement in their system. More technical issues were not discussed, like master-master model .

In my opinion, this is a short list of what an IRO (e.g. A) has to do:

  • inspecting all their IIAs with B institute
  • downloading B's IIAs (with A)
  • joining their IIAs with B's IIA one by one (or contact the partner to know its IIA id for a given IIA)
  • for each matched IIA, sending an Approval CNR
  • for each above Approval CNR, receiving an approval (this task could be transparent, but only it everything goes well)
  • for each matched IIA, waiting for an Approval CNR (sent by B partner)
  • for each Approval CNR, examining the IIA and send Approval

And then your IRO has to repeat this task list over all their partners. Am I wrong?

The last two steps seem to me to be repeated from the previous two. But that's basically it.

spinho-uporto commented 1 year ago

@janinamincer-daszkiewicz

  1. Others e.g. umesh-qs, demilatof, @spinho-uporto are not in favour of amendments similar to LAs as too complicated.

Is that correct?

Yes, that's correct. In the past, LAs already assumed this type of changes, not the agreements.

umesh-qs commented 1 year ago

@janinamincer-daszkiewicz Yes that is correct.

jiripetrzelka commented 1 year ago

@janinamincer-daszkiewicz Right, but I would like to elaborate a bit more because we are discussing two sub-questions without having them properly decomposed:

1. Amendment strategy - what can be amended: a) Complete replacement - This way all hashed/approved contents from the original IIA could be replaced with an amendment, including data from past academic years. Pros: Maximum flexibility, limited need to split cooperation-conditions into more entries. Cons: Potential to change something in the past (informed IROs and validators would be necessary), for some systems it would be harder to implement. But I don't think it would be impossible.

b) Complete replacement for future, no replacement for past - This approach would take into consideration the deadlines for introducing changes at the level of technical specification and would enforce that nothing could be changed retroactively. This is more or less what @demilatof suggested, I guess. Pros: A more defensive approach that would be more in line with legal reality. Cons: Cooperation-conditions would have to be split more often. (Why? Because in case you already have one condition for 2021-29 and in 2023 you want to change, say, other-info-terms, you would still have to split the conditions into 2021-23 and 2023-29 and add the other-info-terms just to the second condition).

c) Addition-only - This is what @spinho-uporto suggested. Pros: The original IIA can remain intact. Cons: Limited expression power. For example, if you have IIA for BA and realize you want to add MA, it won't work.

d) There may certainly be other strategies. - For example, Janina mentioned in one of her previous posts that "Mobility-specs don't have ids yet". So if they had, it would create the possibility for more granular expression of what is being changed.

My preference is option a).

2. Division of documents: a) IIA and its amendment(s) in one document (XML) including history - The IIA Get endpoint would return both information about the original IIA and all its amendments (or only the latest amendment). This is what I elaborated above and what resembles the way LAs are defined. Pros: Partner sees clearly what belongs together. Cons: More data transfer. According to some, too complicated and not suitable for master-master principle.

b) IIA and its amendment(s) in one document (XML) without history - The IIA Get endpoint would return only the latest version of the IIA, possibly the amendment. This is basically what is happening now with mobility systems that allow changes even after the IIAs are approved by both parties. I guess that it is one of the ways that IROs of some systems will use in January 2023 to amend their existing IIAs. Pros: We could use what is already implemented. Cons: The original approved IIA is no longer available in the Get endpoint.

c) IIA and its amendment(s) in separate documents (XML) - The IIA Get endpoint would return the original IIA and to get its amendments you would have to make another IIA Get request. Depending on the "Amendment strategy" the amendment could either resemble the IIA Get XML (addition-only strategy) or there could be a new IIA Amendment API introduced with XML contents tailored specifically for amendments (i.e. all XML elements except cooperation-conditions would be omitted and the reference to the original IIA ID would be added). Pros: The original IIA XML could remain intact. It would also resemble the legal practice, i.e. separate documents with separate signatures/approvals. Cons: Necessity to correctly match the amendment with the ID of the original IIA.

Although in one of my previous posts I elaborated the option a), I now think that c) might be better. BUT: I also think that b) is currently the only sensible way for IROs to make amendments in January 2023 and considering that it would require the least extra work to implement, I think that opponents of option b) should state their reasons for disapproving this option as clearly as possible. The arguments for this option are: If you keep all logs and all versions of IIAs ever received from your partner, you can always track exactly what has been approved and the fact that partner changes the contents of the IIA Get endpoint to an amended version should not be a problem for you. After all, the IIA can disappear for various other reasons, for example if the counterparty changes its provider. But that does not mean that previously approved IIAs are no longer legally binding and logs of communication are the proof of that.

demilatof commented 1 year ago

I appreciate @jiripetrzelka's analysis, but damn, we are so later... All these scenarios are real and requires a deep analysis to understand the impact both on the internal system and on the EWP infrastructure and how much time do we need to adapt everything.

Belenchusky commented 1 year ago

I would like to explain what it means to my IRO colleagues when an agreement terminates before its expiration date. In our system we understand that if that happens it is because the relationship with that partner in relation to the content of that IIA has ended before the agreed date and that I am not going to renew it again.

If I want to modify the current agreement because they change the number of mobilities for example, why don't we modify it instead of terminating an agreement and create another one with the same modification? Our users find it very useful to see how the IIA has been changing throughout the academic years.

If they are two different agreements, how to maintain the relationship between one and the other? This is why I understood from the beginning that if I change something in a current agreement I have to approve the agreement again, but the same one: same id, same code because otherwise it is impossible to keep the history of the changes.

I know that with the current specification it is difficult to make a modification in this sense because as Janina said, the mobilities do not have identifiers. But the idea would be to be able to express the same as observed in the image that I accompany of our current system, where it is observed that in period 2014-2015 / 2018-19 there were 4 mobilities of 6 months, which became in the academic year 2019-20 to 6 mobilities of 5 months. imagen

I do think that this is the scenario to which we must try to converge and not terminate agreements and create others to replace them.

In addition, in case an IIA terminates it is necessary that the partner confirms that it has received the termination. I think that sending only one CNR is not enough and it can create undesirable situations when a university receives nominations from students that are not expected because an IIA ended without the confirmation of the other one.

demilatof commented 1 year ago

If I want to modify the current agreement because they change the number of mobilities for example, why don't we modify it instead of terminating an agreement and create another one with the same modification? Our users find it very useful to see how the IIA has been changing throughout the academic years.

An example could be more clear: you have a student mobility for years 2022/2023-2027/2028 for 3 places. You start the applications allowing 3 places for students and you receive 3 instances that your office accepts (three winners).

Now you want to reduce the places from 3 to 2 for the student mobility. You have only an element that spans over all the academic years. If you change something you have to change it for all the years. Ok, let's do. Now you have 2 places and 3 student that you declared as winners.

We have 2 kinds of problem:

  1. technical (your software can manage more winner than places?)
  2. legal (you declared 3 places when you opened the application service and you reduce them after they are terminated)
demilatof commented 1 year ago

If we have to decide for amendments, I think that now we have an example of how a change in a specification may interfere with another aspect and therefore with the internal implementations. As @janinamincer-daszkiewicz remind here we voted for the second solution described here

Therefore, today more than a month ago, we are dealing with a mobility that in IIA is coded for (e.g.) 3 places, but now we want to amend it and reduce to 2 places. The mobility will remain the same. This may be wrong and ambiguous, because it states, even in the past, that we had 2 places and it's not true.

I think that a clean solution to amend an IIA, with the respect of the above vote about consecutive academic years is:

  1. splitting the involved mobility in 2 parts
  2. keeping the first part with the old conditions and the academic years they are still valid for (e.g. a.y. from 2022/2023 to 2023/2024)
  3. replicating the mobility with the new conditions and the academic years they will be valid for (e.g. a.y. from 2024/2025 to 2027/2028)

The parties must be responsible to not overlap the academic years, because the overlapping may mean that the places available are the sum of the two mobilities.

Doing so we satisfy who wants an amendment without changing the IIA (and the IIA ID) but even who wants that the changes don't affect the mobilities in effect. We are just working on cooperation conditions

Obiously, if the change concerns only an academic year in the middle (e.g. 2024/2025), we have to derivate 3 mobilities from the original one, to respect the new directive that forbids holes in the academic year range. So we should have:

  1. old mobility, 3 places, 2022/23-2023/2024
  2. new mobility, 2 places, 2024/2025-2024/2025
  3. new mobility, 3 places again, 2025/2026-2027/2028

Could the above scenario be a valid solution?

Belenchusky commented 1 year ago

I see your point @demilatof. That is my proposal too.

milsorm commented 1 year ago

I truly understand if the intention is to make an amendment of the whole IIA from both parties, BUT imagine the situation when both partners approved their IIA and several days later one of HEI sends IIA CNR with updated version (but not planning amendment, just change the original one). What with that situation (also #83 looks like trying solve this issue, but definitely not)?

a) changes in non-hashed fields - accept or not? give some notice to somebody?

b) changed in hashed fields - disapprove the whole IIA and restart the process? What is process recommendation?

c) no changed but IIA CNR - test it automatically and ignore it? or consider as a) field?

Currently if something is approved by both sides we ignore later IIA CNR but is it fine? That can leads to situation to offering two different version in same network but one side is thinking it is approved.

May be if amendments in any form will be exists we can go according the new scenarion but what with current implementations? Can we ignore IIA CNR after both-party-approval?

janinamincer-daszkiewicz commented 1 year ago

If you keep all logs and all versions of IIAs ever received from your partner, you can always track exactly what has been approved and the fact that partner changes the contents of the IIA Get endpoint to an amended version should not be a problem for you.

@jiripetrzelka Let's assume that we allow to make changes in the approved agreement. and that this is responsibility of each partner to keep track of all once approved versions (making snapshots). Please elaborate the scenario when partner A wants to make changes and partner B doesn't want to accept them. IIA is approved by both, then A makes changes, sends CNR. B calls IIA get but doesn't not want to approve. What next?

jiripetrzelka commented 1 year ago

@jiripetrzelka Let's assume that we allow to make changes in the approved agreement. and that this is responsibility of each partner to keep track of all once approved versions (making snapshots). Please elaborate the scenario when partner A wants to make changes and partner B doesn't want to accept them. IIA is approved by both, then A makes changes, sends CNR. B calls IIA get but doesn't not want to approve. What next?

Disapproval would follow the same logic as diapproval of IIAs before they have been mutually signed/approved. In this example, B would inform partner A that they do not agree to the changes and would either ask partner A to revert their IIA Get to the signed version, or, if an amendment has been agreed on, they would specify what changes partner A has to do before partner B approves the amendment.

This information would be passed from partner B to partner A either by e-mail or it could be done with a new Comment API, whose output could be:

<iias-comment-response>
    <comment>
        <iia-id>82a94c1684ce-947c-7ac9-cd7f-287f065a</iia-id>
        <conditions-hash>3d3310935590256ecff21549b45eb4e1662b0f2a2aafcb7d91ea5f271f4d9e07</conditions-hash>
        <explanation>Please add MA study level to SMS mobility as we agreed by e-mail.</explanation>
    </comment>
</iias-comment-response>
janinamincer-daszkiewicz commented 1 year ago

If we decide to have a new IIA Comment API, wouldn't it be more natural to use it for sending comments on local IIA and on partner's IIA and to not share a comment via IIA get?

jiripetrzelka commented 1 year ago

If we decide to have a new IIA Comment API, wouldn't it be more natural to use it for sending comments on local IIA and on partner's IIA and to not share a comment via IIA get?

It would require an additional Comment CNR and Comment Get request. That may be overkill if we want just plain comments without history and assume that adding a comment to local IIA is part of the IIA editing workflow that results in partner's IIA Get anyway.

demilatof commented 1 year ago

If we decide to have a new IIA Comment API, wouldn't it be more natural to use it for sending comments on local IIA and on partner's IIA and to not share a comment via IIA get?

It would require an additional Comment CNR and Comment Get request. That may be overkill if we want just plain comments without history and assume that adding a comment to local IIA is part of the IIA editing workflow that results in partner's IIA Get anyway.

I hope no... It could sound quite stupid a system where I have to notify that I have something to tell you, please ask me for it... And only finally I communicate to you what I need to tell you from the beginning.

I hope that such a comment API could be quite immediate: a post with IIA_ID, HEI_ID (still necessary?) and the message.

Anyway, I'd like better if I could add a message in the response when I ignore the approval

janinamincer-daszkiewicz commented 1 year ago

It would require an additional Comment CNR and Comment Get request. That may be overkill if we want just plain comments without history and assume that adding a comment to local IIA is part of the IIA editing workflow that results in partner's IIA Get anyway.

I agree, just wanting to make sure. Anyway, whether we share a comment via IIA get or IIA Comment get, that would be the same comment, I hope. Otherwise that might be confusing for the user.

milsorm commented 1 year ago

Can somebody give me proper answer to my comment month ago here?

https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/92#issuecomment-1333949166

umesh-qs commented 1 year ago

@milsorm I guess this is still under discussion. But this is what we do in MoveOn a) Accept it. No changes in hash so not need to go for re-approval b) Accept it and reset approval since hash has changed. Re-approval needed c) Ignore if there is no change

milsorm commented 1 year ago

@umesh-qs c) is technically complicated but from business perspective I see the same steps. OK, we will do it.

janinamincer-daszkiewicz commented 1 year ago

The discussion continues in https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/99.