search

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

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

Rejection / termination of IIAs #41

Closed georgschermann closed 1 year ago

georgschermann commented 4 years ago

As briefly discussed in the last meeting an issue was brought to our attention, that some Universities may want to terminate or reject IIAs in addition to the approval ( #30 ). This cannot be done at the moment in a clean way. How would you handle termination / rejection?

  1. Send a CNR and set in-effect to false? - maybe for termination, but what about rejection?
  2. Send a CNR and remove all cooperation-conditions? - could be very misleading.
  3. Add possibility for terminate / reject to the approval API?
  4. Just flag them internally and ignore them forever / e-mail the partner?
MartaJuzepczuk commented 4 years ago

Send a CNR and set in-effect to false? - maybe for termination, but what about rejection?

According to the description of the in-effect element, it is not even good for termination.

Send a CNR and remove all cooperation-conditions? - could be very misleading.

You are right, does not seem a good idea for me too.

Add possibility for terminate / reject to the approval API?

We could add such possibility, but I see some problems. In the approval API we use CNR + get approach. So to be able to send rejection response we have to keep the rejected agreement. For how long?

The rejection reponse limited to the "REJECTED" flag is also not very interesting, so partners would probably have to communicate outside the network. Or we should make the approval/rejection response more complicated, which we probably do not want to.

Just flag them internally and ignore them forever / e-mail the partner?

Maybe this is a good idea?

sascoms commented 3 years ago

Not sure if a bit late on this issue but:

1st suggestion is: How about a status API for IIAs and also other APIs with similar content.

Status codes can be listed on the specs/xsd file: such as "rejected", "approved", "terminated", "pending", etc.

Cons: Implementing a new API?

2nd and better solution would be to add a status field to the get endpoint.

rejected (alternatives: approved, terminated, pending, etc.) This approach would not need a new API or CNR. Normal IIA-CNR would be enough to let the partner there is a change about the IIA and they need to re-fetch it and check the changes. Pros: Shorter implementation time both for developers and the API maintainers. What would you think?
kamil-olszewski-uw commented 3 years ago

In my opinion, a situation where agreement is terminated is not a standard situation in which no other communication channel is necessary. So, once it has been agreed that the agreement is terminated, perhaps one party will only need to modify the end dates and the other will download them through the EWP?

In the case of rejection, adding a field to the status in which the value "rejected" could appear would mean that the university that does not want a specific agreement would have to keep it in its system only to send it with the "rejected" status in get response .

sascoms commented 3 years ago

I agree that it is not a standard situation but this still can occur and EWP should cover such situations, too, with solutions as possible as keeping the things simple.

Setting an end date or a previous academic year for the agreement is an option and would work. But I would rather go with -if possible and agreed- a status field as it will fix and cover these situations in a more flexible solution.

And just out of curiosity question: Do you physically delete the terminated or ended agreements from your database? Or do you use any archiving options for mobilities data consistency?

kamil-olszewski-uw commented 3 years ago

Currently, our system (USOS, used in many Polish universities) does not include the option of archiving agreements. As far as I know, old agreements are not removed either, or at least the University of Warsaw does not remove the old ones.

Each agreement is linked in our system to one or more exchange programs (such as Erasmus+, govenment sponsored agreements, individual agreements etc.). Currently, we send only Erasmus+ agreements via EWP.

kamil-olszewski-uw commented 3 years ago

Regarding rejection: If two universities exchange an agreement that will not be signed later, the agreement should be locally deleted as non-valid after some time. A possible "rejected" status would require keeping the agreement in the system of university which does not want this agreement.

Regarding termination: On reflection, we see the need to provide information about the termination of agreement. We are considering adding a new API for this purpose if other colleagues believe it will be necessary. But what about not agreeing to termination? Can one of the parties disagree? If so, the matter becomes more complicated and it may turn out that it is impossible to get things done without communication channels other than EWP, which I wrote about earlier in this issue.

janinamincer-daszkiewicz commented 3 years ago

Ad. Regarding rejection: Which means that in our opinion we do not need special 'rejection' operation. The agreement which is not needed need not be officially 'rejected'. It will just disapear at some moment and the partner asking about it wil get the answer 'there is no such agreement'.

Ad. Regarding termination: We do agree that such extra possibility in the form of a separate API may be of use. If there will go more voices supporting this idea we will eventually add a new API for that. This should however not influence the existing APIs.

umesh-qs commented 3 years ago

In our opinion, a status flag in the existing IIA API is much cleaner and leaves no scope for any ambiguity.

j-be commented 3 years ago

It was brought to our attention, that we have such use-cases as well, being:

Is there any recommendation on how to handle these scenarios in a clean way?

lioliosn commented 3 years ago

Unilateral termination of the IIA is part of the official template, so there should definitely be a status flag for "termination" for covering this use-case. Rejection is another use-case and should be treated diferrently, with a diferrent status flag. To be honest, a timestamp of a "termination" status flag is also a must from a template perspective because you need to make sure that you have notified your partner at least a year earlier.

janinamincer-daszkiewicz commented 3 years ago

Please, whoever is following this issue, share your opinion. If possible before the end of September.

georgschermann commented 3 years ago

We currently handly rejection with an internal flag, parter is not notified about this. Termination is done via a change of the academic terms, but could be ignored by the partner at the moment. Both are use cases of many Universities. Another use case is the deletion/rejection/termination of errroneous agreements, so without a years notice, this is also currently done with internal flags only.

lioliosn commented 3 years ago

We currently handly rejection with an internal flag, parter is not notified about this.

Rejection is a serious action and partners should be notified.

Termination is done via a change of the academic terms, but could be ignored by the partner at the moment.

I believe you mean that you change the duration of the agreement. In that case, how do you know that it has been terminated and it was not so from the beginning? Notification for termination is a contractual obligation and should be clearly communicated to the partner and its receipt should be confirmed somehow.

Both are use cases of many Universities.

Some uses cases are often based on erroneous interpretations of the obligations.

Another use case is the deletion/rejection/termination of errroneous agreements, so without a years notice, this is also currently done with internal flags only.

I believe that only rejection and then deletion is appropriate for erroneous agreements (on the premises that we are talking about agreements with errors that could not be fixed). Termination means that an IIA has been checked and put into place and that at some point we agree to terminate it. It is not erroneous, it is just not desired any more.

sascoms commented 3 years ago

I agree that there should be a status flag. A status flag can have different status types.

If this status flag is included in the iia-get endpoint/content, then we will not need a new API for this.

Also for termination related statuses, there is a need of a termination date field.

See below:

status types:

Notes for fields:

One important point is that this status field should exist for both partners. In other words, each partner shall include the status field and the date related to the termination.

And a good place to put these fields would be the partners section of the iia-get content.

And when these status/date fields are modified/updated on a partner's system, that partner should definitely need to notify the other partner with an IIA-CNR. This way the other partner will fetch the IIA and see the termination related fields and do the necessary updates on their system. If no CNR, the partner will not know or be informed about a termination decision from their partner.

Hope it is clear.

@janinamincer-daszkiewicz Why the end of September? Shall we expect new changes or a new version?

PS: we need a iia-notes field to be added to the get API and I will open another issue for this.

fmapeixoto commented 3 years ago

I believe that to move forward with terminating the IIAs, with the specifications that already exist, a new API is needed for informing the other partner that a specific IIA as been terminated (neither the approval CNR API ou the normal API should be used for this). Also, if we cannot use the in-effect tag, we would need an extra parameter to flag this situation in case some partner does a get request of an IIA that has been already terminated.

Nevertheless, if the idea is to review all the methods and procedures, and launch a new version without backward compatibility, perhaps all the APIs should be reviewed, along with all the processes, to check what makes sense to maintain or not, and add/remove/change the APIs accordingly.

georgschermann commented 3 years ago

@lioliosn I was speaking only about the technical level, and there are currently no technical means for these scenarios/notifications. @fmapeixoto adding a status field/element would be either backwards compatible or at least non-breaking, see https://github.com/erasmus-without-paper/ewp-specs-architecture#backward-compatibility-rules

lioliosn commented 3 years ago

@georgschermann Thanks for clarifying, although my intention was to highlight the need for alignment between technical and business level.

janinamincer-daszkiewicz commented 1 year ago

Some changes in the IIA and IIA Approval APIs will take place by the end of 2022. It makes sense to group them to make the change in the major number of the APIs once.

During the Infrastructure Forum meeting on 2022-10-19 we discussed the following issues:

  1. It should be possible to renegotiate/expand/pause the terms of the agreement approved by both institutions in the course of the cooperation leading to a new approval by both partners. The template stipulates: “The partners commit to amend the table below in case of changes in the mobility data by no later than the end of January in the preceding academic year”.
  2. It should be possible to terminate an agreement. The IIA template stipulates: “It is up to the involved institutions to agree on the procedure for modifying or terminating the inter-institutional agreement. However, in the event of unilateral termination, a notice of at least one academic year should be given. This means that a unilateral decision to discontinue the exchanges notified to the other party by 1 September 20XX will only take effect as of 1 September 20XX+1. The termination clauses must include the following disclaimer: "Neither the European Commission nor the National Agencies can be held responsible in case of a conflict”.
  3. It should be possible to delete an agreement that was never approved by both parties and to notify the partner about it.

The possible solution, discussed in this issue and during the mentioned meeting, is to add a state field to IIA. The possible values for this field and their meaning are yet to be defined. Let start from the following draft proposal:

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.

States will not solve the need to make changes in the approved agreement. This topic will be discussed in a separate issue: https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/92.

demilatof commented 1 year ago

I don't know what is the regulation in other countries, but in Italy we have to keep track of every document exchanged for several years. Therefore, my main difficulty has been (and still is), to store every communication in a database, even if the EWP doesn't require it. E.g: I can receive a document, make a decision and in the meantime receive a different document that could be incompatible with the previous decision. I must be able to inspect what previously happened.

Therefore, I have had to solve this problem in our system, because the deadline is coming. I think others have had to do in a similar way. The states could be useful two years ago, now it could be too late. We have our old system that contains more agreements than what we expose to EWP; what we expose to EWP is no more an IIA draft. The states should be implemented in the internal system: until an IIA is in draft mode, it should not be exposed to EWP. This rule should resolve draft and ready states.

Approved: can I really rely on this state to be sure that an IIA is approved? I think that this state already exists and is the "In Effect" element. We set it to true when our copy is approved by the partner, that should do the same when we approved its copy. If we both answer to the IIA-Get with the same couple of IIA-Id (our ID, partner's ID) and both of response declares the IIA "in effect", I consider it as Approved. On my opinion a problem could arise when we call partners' IIA Approval API and the response contains the wrong IIA ID or hash code, because we could think it has misinterpreted our request or approved an old copy of our IIA (right ID, wrong hash code).

Deleted could be useful only if the IIA has never been approved; something approved could not be deleted, but only modified, or better (for easier management on my mind) closed. But if an IIA has been deleted it might be because it contains something that we don't want to share anymore, therefore we don't want that the IIA Get Response contains the full IIA marked as deleted. I think that "deleted" could be contained in the response as for unknown ID (and status 200). That is, empty response for unknown ID, deleted for an IIA that is no more sharable

Terminated could be redundant if it refers to the natural deadline (last academic year in cooperation conditions). Could be useful if it was renamed "Terminated-after-academic-year" and it contained the last academic year it will be (or was) in effect, if it will be introduced the possibility to change an IIA by closing the one in effect and creating a new one.

jiripetrzelka commented 1 year ago

I think that:

kamil-olszewski-uw commented 1 year ago

Regarding the "draft" status. This is a temporary working name and may not fully reflect the reason why the status was proposed. I was thinking about the name "work in progress", which is not perfect either.

Of course, the brand new IIA, while entering into the system, should not be made available via EWP. Let us assume, however, such a situation that an unsigned IIA is already in the systems of universities A and B. Both universities provide their copies via EWP. University A proposed changes. University B has downloaded these changes, but needs to think about them. During this time, B should rather not hide its copy of IIA from the partner, but make it available with the status "draft" (or "work in progress" or whatever we will call it) until B processes the IIA on its side.

Another example is the automatic download of IIAs by the Dashboard and sharing them via EWP before the Dasbhoard user even sees the downloaded IIA. Some other developers and users find this solution controversial, and both sides have meaningful arguments for and against it. If the status discussed here existed, the problem would be solved by itself.

jiripetrzelka commented 1 year ago

I guess there may indeed be use cases in which the draft status could be useful. Apart from the mentioned use case I can think of partner A exposing their draft and partner B being able to import it to their system, which could reduce the workload of partner B a bit (provided that their mobility system offers some import functionality, of course).

Anyway, I would still prefer a solution in which the status would be inferred from the contents of the IIA and not a solution in which the status would be declared explicitly by some status element. But this is rather a technicality.

Another, more important question is, what shall we do in the meantime until these changes are present in production implementations of the majority of providers. My personal guess is that even if we agree on a new specification, it will take at least a year before a considerable number of nodes will have them implemented. And during this time coordinators will need to create amendments. I think we need to think of some guidelines for using the current specification in order for coordinators to be able to handle amendments especially in the first half of 2023.

My suggestion is to explicitly allow IIA changes after the IIA has been signed/approved by both parties. Some (and I hope most) systems allow this. Some, such as Dashboard, don't. I don't really understand why this should be disallowed. But if there are good reasons for this restriction, it would at least help to know which system allows this and which does not. Otherwise "my" coordinators create an amendment and then have to guess why the counterparty does not see the changes - is it because the other system decided this is not possible after the IIA is signed by both parties? Or is it another technical issue?

demilatof commented 1 year ago

We can discuss whatever we want, but the model master-master and the asynchronous operations will always require to introduce a new workaround. E.g.: we introduce the states to solve the problem of informing the counterpart if our IIA is still in draft or ready for approval. What happens if we realize that we made a mistake after having declared the IIA "ready for approval" and the partner has downloaded it? Probably we will put it again in draft mode, but in the meantime the partner could have already downloaded a "ready for approval" IIA.

Therefore, we have complicated the present model without solving the starting problem.

In my opinion, we could not rely on EWP for solutions that its model cannot satisfy. It's up to us implement them in our system. When we wish we download the partner's copy, if available, and we associate it to our IIA ID.

Then we couple our and partner's IIA-ID and we send a CNR approval; we have to save in our DB that we sent the CNR approval, the IIA ID and the conditions hash of the partner's IIA (the one we intend to approve). When the partner is ready, it calls the Approval API in our system.

At this point we have to download again the IIA and check its hash code against the one we saved when we sent the CNR approval. If they match we can answer with the approval response providing the partner's IIA ID and hash code. If they DOESN'T match, we give an empty response and status 200 (it would be better a different code or a description in the answer, such as: "IIA changed in the meantime; we will examine it again soon").

We have to inform immediately our operator that the partner's IIA is changed so that he/she could examine the new IIA and send a new CNR Approval. A more accurate solution could require an extra proprietary hashing to consider other information, such as contacts. But since EWP gives importance only to cooperation conditions, the cooperation condition hash code could be enough.

janinamincer-daszkiewicz commented 1 year ago

In https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval/issues/5 the discussion goes in the direction of keeping/sharing statuses (and comments). Here I rather see arguments against statuses.

I agree with Jiri, that it would be great to have a solution in which the status would be inferred from the contents of the IIA and not a solution in which the status would be declared explicitly by some status element. That would be like having virtual statuses with a meaning based on the other attributes of an IIA.

Let's look into statuses again:

  1. Draft is actually not necessary if we agree that these IIAs should not be published to the counterparty. True, but from the discussion in this issue it seems to me that sometimes it is better to have a copy which is draft and can be shared with the partner or to step back from ready to draft for some reason. I am not in favour of the solution in which IIA once exposed to the partner all of a sudden disappears from the network.
  2. Ready for approval could be inferred from the presence of the cooperation-conditions-proposal element, as I suggested in https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/92#issuecomment-1290987626. Let's come back to this after we come to an agreement in the referenced issue.
  3. Approved could be similarly inferred from the presence of the cooperation-conditions-first-version element. Let's come back to this after we come to an agreement in the referenced issue.
  4. Terminated - You still need to know the academic year from which the IIA is supposed to be terminated so there will have to be another element with this information and based on the contents of this element you can infer at which point in time the IIA becomes terminated. That's true.
  5. Deleted - Maybe Http 404 with some predefined developer-message (or predefined error code) would be sufficient and also more generally applicable to other APIs where clients may need to understand better why a record is not present in the counterparty's response. Anyway, we have to differentiate between IIA which never existed and IIA which has been deleted. So we have to keep some info about it in the local system.
jiripetrzelka commented 1 year ago
  1. Deleted - Maybe Http 404 with some predefined developer-message (or predefined error code) would be sufficient and also more generally applicable to other APIs where clients may need to understand better why a record is not present in the counterparty's response. Anyway, we have to differentiate between IIA which never existed and IIA which has been deleted. So we have to keep some info about it in the local system.

Yes, but you could decide to keep just the IDs of deleted records and not the entire record.

demilatof commented 1 year ago

@janinamincer-daszkiewicz

1.Draft is actually not necessary if we agree that these IIAs should not be published to the counterparty... I am not in favour of the solution in which IIA once exposed to the partner all of a sudden disappears from the network.

I think that unfortunately nothing can assure that a partner suddenly removes an IIA from the network; with or without statuses

I've already expressed my opinion against statuses; what I notice is that there could be a lot of new elements to keep track of statuses. Since the system is master-master how should we align these elements in our IIA with the similar elements in the partner's IIA? Every step (status) in our IIA must have its corresponding status in the partner's IIA? What happens if someone skips a step/status?

umesh-qs commented 1 year ago
  1. Deleted - Maybe Http 404 with some predefined developer-message (or predefined error code) would be sufficient and also more generally applicable to other APIs where clients may need to understand better why a record is not present in the counterparty's response. Anyway, we have to differentiate between IIA which never existed and IIA which has been deleted. So we have to keep some info about it in the local system.

Yes, but you could decide to keep just the IDs of deleted records and not the entire record.

If entire record is not kept then how would the IIA response look like? Rather make use of changes proposed in https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval/issues/5 for IIA status

umesh-qs commented 1 year ago

We can discuss whatever we want, but the model master-master and the asynchronous operations will always require to introduce a new workaround. E.g.: we introduce the states to solve the problem of informing the counterpart if our IIA is still in draft or ready for approval. What happens if we realize that we made a mistake after having declared the IIA "ready for approval" and the partner has downloaded it? Probably we will put it again in draft mode, but in the meantime the partner could have already downloaded a "ready for approval" IIA.

Therefore, we have complicated the present model without solving the starting problem.

In my opinion, we could not rely on EWP for solutions that its model cannot satisfy. It's up to us implement them in our system. When we wish we download the partner's copy, if available, and we associate it to our IIA ID.

Then we couple our and partner's IIA-ID and we send a CNR approval; we have to save in our DB that we sent the CNR approval, the IIA ID and the conditions hash of the partner's IIA (the one we intend to approve). When the partner is ready, it calls the Approval API in our system.

At this point we have to download again the IIA and check its hash code against the one we saved when we sent the CNR approval. If they match we can answer with the approval response providing the partner's IIA ID and hash code. If they DOESN'T match, we give an empty response and status 200 (it would be better a different code or a description in the answer, such as: "IIA changed in the meantime; we will examine it again soon").

We have to inform immediately our operator that the partner's IIA is changed so that he/she could examine the new IIA and send a new CNR Approval. A more accurate solution could require an extra proprietary hashing to consider other information, such as contacts. But since EWP gives importance only to cooperation conditions, the cooperation condition hash code could be enough.

Wouldn't IIA status in IIA Get API clubbed with proposed changes in https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval/issues/5 address all the concerns?

demilatof commented 1 year ago

Wouldn't IIA status in IIA Get API clubbed with proposed changes in erasmus-without-paper/ewp-specs-api-iias-approval#5 address all the concerns?

As I said here https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval/issues/5#issuecomment-1298731674 I don't think that Approval API could be used to reject an IIA. The specifications say that Approval API is for approving:

This API allows HEIs to approve agreements sent by their partners https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval

And the same specification already considers what to do for an IIA that cannot be approved:

Values of iia_id that are not known by the server as owner_hei_id's agreements or not approved (yet or at all) MUST be ignored. Servers MUST return a valid (HTTP 200) XML response in such cases, but the response will simply not contain any information on these missing entities.

Why should we change the specifications when they already contemplate our needs, just adding a comment in the response for unknown/not approved IIA ID?

umesh-qs commented 1 year ago

@demilatof If you go through the discussion under https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval/issues/5, it suggests changes in the approval API to call it IIA status API or a new status API altogether.

Changes in specification is needed to cover more IIA status and not only approval or rejection. Will comment tell me that the IIA is deleted permanently and no longer available?

demilatof commented 1 year ago

@umesh-qs I think that it is not acceptable that 2 months before the deadline we are thinking of renaming an API and changing its behavior, or introducing a new API to change completely the flow of the procedure (more status, more complexity).

Moreover, an approved IIA should never be deleted. This action should be forbidden, even if there is no one that could forbid it. Instead an IIA that is not yet approved could be deleted and its IIA Id would become unknown.

Now we have to decide at what step we have to face the problem:

  1. when A sends a CNR to B but B has deleted the IIA?
  2. when B replies to A with Approval, but A decides that the approval mismatch for some reason?

In the first case we can modify the empty response to CNR request, in the latter case we have to modify the empty response to Approval request. These moments are critical to except something, but until now there is no room to object anything to a single request.

E.g: if we wish to detail the status 200 for unknown IDs, we can use a comment. We can even add a sub element in the empty response (and status code 200) to manage every possible event that is not an approval. Please see the second piece of code in the following example

 <iias-get-response
    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-iias/blob/stable-v6/endpoints/get-response.xsd"
    xmlns:ns2="https://github.com/erasmus-without-paper/ewp-specs-types-contact/tree/stable-v1"
    xmlns:ns3="https://github.com/erasmus-without-paper/ewp-specs-types-phonenumber/tree/stable-v1"
    xmlns:ns4="https://github.com/erasmus-without-paper/ewp-specs-types-address/tree/stable-v1">
<additional-info>
  <status>
        deleted <!-- (or "unknown" or "hash-changed" after CNR and so on) -->
  </status>
  <message>
       A brief description of the problem
  </message>
</additional-info>

</iias-get-response> I understand that it is not much different from your proposal, but this solution really extends the current API and does not rewrite it.

Last but not least: I'm the only to think that EWP master-master model generates a huge number of problems in the real world? Sometimes I loose myself in following and forecasting what could happen while we are comparing the partner's version, sending approval CNR, waiting for approval doing, the same switching our roles...

Belenchusky commented 1 year ago

I completely agree with @demilatof that it is already too late to incorporate states in the IIA APIs. We all had to find solutions to the problems presented here and develop our systems according to the existing rules of the game. Such important changes at this time could throw away the work of many months.

I understand what @kamil-olszewski-uw is saying, but systems that automatically incorporate proposals from IIA partners, without prior validation by anyone, have this problem. I have verified that the Dashboard works like this and from my point of view that is its problem and therefore it must be the Dashboard that must change its operating model and not the rest. In our case, we designed a model that does not automatically incorporate the proposals of the IIAs of the partners, which makes our users have more work, but we did it precisely in this way to avoid the problems that are being exposed here.

Regarding an accepted agreement that is no longer valid (Terminated), I understand that it is a modification of the existing one because we need to know the academic year from which the IIA is supposed to be terminated and both parties must agree depending on the before the termination is requested. From my point of view it is not a state.

Delete in our case as unfeasible if we have already started negotiating, and even less so, if it has been approved at some point, because our agreements are directly connected to the mobility we offer students. What is renewed is what is in the application and can never be erased.

So please, let's not talk about the possible states, I think the first thing is to determine if the states are necessary or not, and our opinion is that they are not.

janinamincer-daszkiewicz commented 1 year ago

I will try to summarise. I see two proposals here:

  1. @janinamincer-daszkiewicz, @jiripetrzelka , @umesh-qs - let's exchange information about the 'state' (virtual state?) of the IIA,with some 'comment', using a separate, dedicated IIA, called IIA Status (+CNR), see https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval/issues/5#issuecomment-1299041941. Jiri suggests to deduce statuses from the other attributes of IIA. In my opinion this is up to implementation how these statuses are obtained, but we should specify the acceptable options.
  2. @demilatof, @Belenchusky - let's not introduce statuses but exchange comments as part of IIA get or IIA Approval get. In https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/41#issuecomment-1301847416 it is called 'additional-info' and carries 'status' and 'message'.

It looks like we all agree that we need some way to exchange something we call 'status' and 'message (comment)' but differ in a vision were to put it: in a separate API or in existing APIs.

Do I understand it correctly?

I also think that we all agree that:

  1. Delete may happen but it is allowed only before Approval took place.
  2. Terminate may happen and happens in real live. We have to find a way to handle it. The date of termination is crucial.

There are two opinions on the Draft versions of IIA:

  1. Draft versions of IIA should not be exposed in the network.
  2. It is sometimes useful to mark IIA as Draft and keep it exposed in the network.
janinamincer-daszkiewicz commented 1 year ago

@demilatof

I'm the only to think that EWP master-master model generates a huge number of problems in the real world?

No. Many, many years ago I suggested to have a central server for handling IIAs. Everybody likes Google docs with its shared-edit mode. In fact we have such a server .. the Dashboard. We all could edit our IIAs in the Dashboard and then import them to our local system to base our other processes on them. That would solve some of the problems, but would introduce others. The problem with IIAs is, that they depend on many other pieces of information we would have to store in the Dashboard and keep up-to-date: contacts, organizational units etc. The problems of deleting, terminating and modifying would have to be solved in the Dashboard anyway and all these changes imported to the local system somehow. The local systems would have to synchronize new versions of the IIA coming from the Dashboard with the local versions. Still some work to be done but import would be in the read-only mode, may be easier to handle.

sascoms commented 1 year ago

@demilatof

You are not alone :) and you will never walk alone ;)

Please check the link below for our EWP Technical Problems report that we published in January. https://www.linkedin.com/feed/update/urn:li:activity:6892099182832754688 page 5 -> master-master model

We have not published it in the public report but you can check the screenshot below from our solution proposals from the internal copy: erasmusjet--special-ewp-iaa-solution-proposal

And the interesting thing is that as 31 December 2022 is the deadline for digital IIAs renewal, the maximum number of fully approved IIAs percentage is not more than 25-30% in all countries (except for 2-3 countries).

I think the EWP+ Consortium should think and analyze why the fully approved numbers are sooo low and what mistakes were made so far. Although I think it is tooo late for this :S

demilatof commented 1 year ago

@janinamincer-daszkiewicz

In fact we have such a server .. the Dashboard.

In my opinion the Dashboard could be the solution if it was implemented better than that it is. We have tested for some months the Dashboard, but it was not adequate to the needs of institutions with a lot of agreements and Learning Agreement. Too few facilitations for IRO needs.

Anyway, a central server would have solved the problem. Obviously it should have to store contacts, agreements, organization units and so on. But this is exactly what we miss now. I think it could be enough a bit of attention in implementing something to facilitate data importing (only for the first setup) and exporting (every time we need to update our internal system).

jiripetrzelka commented 1 year ago
  1. Ready for approval could be inferred from the presence of the cooperation-conditions-proposal element, as I suggested in Making changes in the approved agreement #92 (comment). Let's come back to this after we come to an agreement in the referenced issue.
  2. Approved could be similarly inferred from the presence of the cooperation-conditions-first-version element. Let's come back to this after we come to an agreement in the referenced issue.

I would like to suggest an alternative solution for you to consider:

Ready - I guess the prerequisite to reach this state in most system is some kind of internal signature of the IIA by IRO. So why not reflect this in the specification and have a field for exposing the date (or timestamp) on which the IIA has been signed by the owning party? If present, the IIA would be "ready". If absent, the IIA would be "draft".

Approved - In a similar vein, there could be a new element in IIA Get that would reflect that the owning party has at some point in history managed to obtain the approval of the given IIA revision from the counterparty.

In case of the (now presumably unlikely) event of introducing XML signatures, the draft/ready/approved states could again be somehow inferred from the presence/absence of the XML signatures.

janinamincer-daszkiewicz commented 1 year ago

After yesterday's meeting with BPO and today's meeting with the Dashboard team we consider the following approach (just the draft idea).

  1. There are no drafts, only these IIAs are exposed in the network which (according to the intention of the exposing party) can be approved by the party's partner.
  2. We add comment field to IIA (outside hashed part) and exchange it via IIA get.
  3. Before the IIA is approved (by both partners) it can be deleted. We 'delete' our copy of the IIA by responding to IIA get with:
    • Option 1 - 'zombie' IIA (IIA with all optional fields removed);
    • Option 2 - a list of requested IIAs and (in another element) a list of ids of deleted IIAs.
  4. IIA can be terminated. We have an extra element in IIA, an optional date with the last academic year of the validity of the agreement. If IIA is not terminated, the field is empty. We tell the partner that we want to terminate IIA by filling the date and sharing it with the partner via IIA get. This is an additional element, outside hashed part of IIA. The original hash does not change. We approve this terminate proposal by sending IIA Approval CNR and responding to IIA Approval get with a termination date.
  5. After termination of IIA we will most probably sign a new IIA with changes in mobilities for the remaining academic years. A local system can easy that by supporting copy/paste of the old terminated agreement's remaining academic years to the new agreement (with the new id). The local system may keep track of the sequence of agreements.
  6. What should we do if the agreement has been approved but the partner tells in the comment that exceptionally they would like to send 1-2 more students. If we don't mind, we share our consent. Do we have to re-approve such IIA? What would we do in the old paper time? The BPOs answered - nothing, the paper version would stay as it was. We suggest to do the same in EWP. Be flexible if the end user does not have problems with that. But if they do not want such change - they can force terminate and start the new IIA.

This proposal is a compromise, but a pragmatic one. We do not introduce states, we do not introduce new APIs, we add a couple of new elements to the existing APIs. And we agree to some flexibility (if the users want it). Please, share your thoughts.

demilatof commented 1 year ago
  1. There are no drafts, only these IIAs are exposed in the network which (according to the intention of the exposing party) can be approved by the party's partner.

It seems to me that this is quite different (and less problematic) from what you announced here Saying that in the EWP network the A partner exposes IIAs that can be (downloaded and) approved by the B partner is different from saying that A partner exposes IIAs that are ready for approval.

  1. Before the IIA is approved (by both partners) it can be deleted. We 'delete' our copy of the IIA by responding to IIA get with:
  • Option 1 - 'zombie' IIA (IIA with all optional fields removed);
  • Option 2 - a list of requested IIAs and (in another element) a list of ids of deleted IIAs.

I don't understand the first option: if we remove all the fields that are optional, how can we distinguish if we simply want to remove them or if we want to declare the IIA deleted? The second option is not good in our implementation: we manage only an IIA per Get.

What about a third option, similar to what has been proposed for the IIA termination? We could add in the partner section an extra element, an optional date that the partner that deletes the IIA can fill with the timestamp of deleting. If the IIA is not deleted, the field is empty.

What we have to do with Index API? Shall we list the deleted IIAs too or only the valid IIAs, even if the deleted IIA could be retrieved with the IIA Get API anyway?

  1. IIA can be terminated. We have an extra element in IIA, an optional date with the last academic year of the validity of the agreement. If IIA is not terminated, the field is empty. We tell the partner that we want to terminate IIA by filling the date and sharing it with the partner via IIA get. This is an additional element, outside hashed part of IIA. The original hash does not change. We approve this terminate proposal by sending IIA Approval CNR and responding to IIA Approval get with a termination date.

I suggest to put this element in the partner section, so that we can see which partner has terminated the IIA (they both could terminate the IIA). I think it could be more linear if we use a new CNR, IIA Terminate CNR and IIA Terminate to separate the behaviors. Otherwise every time we receive an IIA Approval CNR and we answer to an IIA Approval calling, we have to download the IIA to inspect if it contains the new extra element filled in. We would avoid this check or the extra API if we could add a parameter to Approval CNR and to Approval API request, but I understood that this is not an option.

I also suggest to add an extra element in the partner section, that is still optional, with the termination date. This element could be filled in only after a partner approved the termination.

  1. What should we do if the agreement has been approved but the partner tells in the comment that exceptionally they would like to send 1-2 more students. If we don't mind, we share our consent. Do we have to re-approve such IIA? What would we do in the old paper time? The BPOs answered - nothing, the paper version would stay as it was. We suggest to do the same in EWP. Be flexible if the end user does not have problems with that. But if they do not want such change - they can force terminate and start the new IIA.

This seems to me a good compromise

umesh-qs commented 1 year ago

After yesterday's meeting with BPO and today's meeting with the Dashboard team we consider the following approach (just the draft idea).

  1. There are no drafts, only these IIAs are exposed in the network which (according to the intention of the exposing party) can be approved by the party's partner.
  2. We add comment field to IIA (outside hashed part) and exchange it via IIA get.
  3. Before the IIA is approved (by both partners) it can be deleted. We 'delete' our copy of the IIA by responding to IIA get with:
  • Option 1 - 'zombie' IIA (IIA with all optional fields removed);
  • Option 2 - a list of requested IIAs and (in another element) a list of ids of deleted IIAs.
  1. IIA can be terminated. We have an extra element in IIA, an optional date with the last academic year of the validity of the agreement. If IIA is not terminated, the field is empty. We tell the partner that we want to terminate IIA by filling the date and sharing it with the partner via IIA get. This is an additional element, outside hashed part of IIA. The original hash does not change. We approve this terminate proposal by sending IIA Approval CNR and responding to IIA Approval get with a termination date.
  2. After termination of IIA we will most probably sign a new IIA with changes in mobilities for the remaining academic years. A local system can easy that by supporting copy/paste of the old terminated agreement's remaining academic years to the new agreement (with the new id). The local system may keep track of the sequence of agreements.
  3. What should we do if the agreement has been approved but the partner tells in the comment that exceptionally they would like to send 1-2 more students. If we don't mind, we share our consent. Do we have to re-approve such IIA? What would we do in the old paper time? The BPOs answered - nothing, the paper version would stay as it was. We suggest to do the same in EWP. Be flexible if the end user does not have problems with that. But if they do not want such change - they can force terminate and start the new IIA.

This proposal is a compromise, but a pragmatic one. We do not introduce states, we do not introduce new APIs, we add a couple of new elements to the existing APIs. And we agree to some flexibility (if the users want it). Please, share your thoughts.

How do we handle a scenario where IIA is shared in network but then want to stop sharing until some more modifications are done? Also will the IIAs that are closed will be shared for ever. If not then how to handle that in IIA Get response?

janinamincer-daszkiewicz commented 1 year ago

How do we handle a scenario where IIA is shared in network but then want to stop sharing until some more modifications are done?

The idea is that if you once announced something as ready for approval you expose this version until you are ready to enter changes and start exposing new version which would be ready for approval.

I am aware that in some scenarious this gives less flexibility but otherwise we would have to accept the idea of drafts and come back to discuss states and how to share them. So what I propose is a compromise, may be the acceptable one.

Also will the IIAs that are closed will be shared for ever. If not then how to handle that in IIA Get response?

Yes, anyway we should never reuse the identifiers of the deleted agreements so it makes sense to keep them in some form.

janinamincer-daszkiewicz commented 1 year ago

It seems to me that this is quite different (and less problematic) from what you announced https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/74#issuecomment-1308302261 Saying that in the EWP network the A partner exposes IIAs that can be (downloaded and) approved by the B partner is different from saying that A partner exposes IIAs that are ready for approval.

It only means that my English is not good enough to express my thoughts properly. I do not see the difference between the two and that was not my intention to differentiate between them. I am looking for the solution which would support the requirement of BPOs

We could add in the partner section an extra element, an optional date that the partner that deletes the IIA can fill with the timestamp of deleting. If the IIA is not deleted, the field is empty.

The idea was to keep in the local system after deletion the smallest requested set of data. May be zombie plus the date. May be providers will vote for tle list of deleted ids. There is still time to elaborate this idea in more detail.

We would avoid this check or the extra API if we could add a parameter to Approval CNR and to Approval API request, but I understood that this is not an option.

My proposal is (see p. 4): We approve this terminate proposal by sending IIA Approval CNR and responding to IIA Approval get with a termination date.

demilatof commented 1 year ago

The idea was to keep in the local system after deletion the smallest requested set of data. May be zombie plus the date. May be providers will vote for tle list of deleted ids. There is still time to elaborate this idea in more detail.

I think that is upon the local system deciding how much set of data keeping.

My proposal is (see p. 4): We approve this terminate proposal by sending IIA Approval CNR and responding to IIA Approval get with a termination date.

Doing so there is no discussion about the termination date; once we respond to IIA Approval with a termination date, the partner could only receive that date, even if it could be unacceptable. And then what they could do?

janinamincer-daszkiewicz commented 1 year ago

I think that is upon the local system deciding how much set of data keeping.

Yes and no. The partner should know what to expect.

Doing so there is no discussion about the termination date; once we respond to IIA Approval with a termination date, the partner could only receive that date, even if it could be unacceptable. And then what they could do?

The termination procedure starts with sending IIA CNR, then IIA get will get IIA with the termination date. Approval procedure of the termination starts later and partners use for that IIA Approval with the termination date. See p. 4 in https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/41#issuecomment-1309468065.

demilatof commented 1 year ago

I think that is upon the local system deciding how much set of data keeping.

Yes and no. The partner should know what to expect.

This simply means that the idea should be to exchange after deletion the smallest requested set of data. We can state the amount of data to be exchanged from systems, not the amount of data to be kept (stored) in the local system

Doing so there is no discussion about the termination date; once we respond to IIA Approval with a termination date, the partner could only receive that date, even if it could be unacceptable. And then what they could do?

The termination procedure starts with sending IIA CNR, then IIA get will get IIA with the termination date. Approval procedure of the termination starts later and partners use for that. IIA Approval with the termination date. See p. 4 in #41 (comment).

Therefore, we inject in an approved IIA a termination date before there is a real agreement on this by both parties. And we have to:

  1. send the IIA CNR
  2. receive sooner or later an IIA Get
  3. receive sooner or later an Approval CNR
  4. call partner's Approval API that responds with a termination date

What happens if between point 2 and 3 we change the termination date? Until the partner doesn't send us an Approval CNR we can change our mind. We can even send a new IIA CNR but, you know, there is no guarantee that it could be received. After that we receive an Approval CNR (but the partner is still working on the first termination date). We call the partner's IIA Approval and only after that it has answered us with the old termination date we can realize that it is wrong. And we cannot do nothing, because the IIA Approval is conclusive. Keep in mind that we can have months between a CNR and the following step and in the meantime something could be changed.

But the IIA Approval allows only the server to perform controls, whilst who calls the Approva API cannot say anything more, even if the received response contains invalid or old parameters.

Another problem is: what happens if a partner changes the IIA not only to insert a termination date, but even to change anything within or without cooperation conditions Are we sure that all systems will manage correctly this possibility, or we accept the risk that someone sees the termination date and it switches its system to "termination mode", approving the IIA without further controls?

I would like a system where there is only a Termination API per server, that affect the IIA only after both parties call the API each other.

  1. A makes a request to the B's Termination API sending

    • B HEI ID, B IIA ID, B IIA hash code
    • A HEI ID, A IIA ID, A IIA hash code
    • termination date (that must even be saved on the local system)

  2. if B recognizes the IIA as approved (by means of the IIA-IDs and the IIA hash codes), it stores the requested termination date as pending request and answers to A with status 200 (and the same parameters received). If B has a previous pending request it answers with an HTTP 400 status (Invalid parameters) and a message (e.g. "Pending request with termination date: ")

The Termination API should be called only once, until the other part doesn't do the same. It's upon the Termination API server to implement the control.

On its turn, B calls A's Termination API; if A has previously sent a request to the B's Termination API, now check if the received IIA identifiers and termination date is the same it sent before. If they match, A answers with status 200, the IIA identifier received, the termination date and a status parameter "confirmed".

Once the termination date is confirmed (that is, the two termination date, sent and received, are equals) the Termination Date can be injected in the IIA; it is not necessary to download the new IIA, but when it will be downloaded it will contain the termination date.

Once both parties have a couple (date sent, date received) they could even start again the process to agree for a different termination date (thanks to a timestamp, the termination in effect will be the more recent).

janinamincer-daszkiewicz commented 1 year ago

What happens if between point 2 and 3 we change the termination date?

The same can be said about changing details of IIA while in the meantime the partner starts approval of the old version.

And we cannot do nothing, because the IIA Approval is conclusive.

We will not approve partner's copy but will come back to negotiations.

demilatof commented 1 year ago

What happens if between point 2 and 3 we change the termination date?

The same can be said about changing details of IIA while in the meantime the partner starts approval of the old version.

Exactly; and what happens?

And we cannot do nothing, because the IIA Approval is conclusive.

We will not approve partner's copy but will come back to negotiations.

We may have already approved the partner's copy (master-master model...) And the fact that we don't approve the partner's copy because he made an error with our copy is a misuse of the approval system.

From EWP Mobility Process Explained:

Each partner should behave in the same way and independently:

This means that if the partner's copy that we have downloaded is correct, we should approve it.

janinamincer-daszkiewicz commented 1 year ago

Proposals listed in https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/41#issuecomment-1309468065 has been discussed during the Infrastructure Forum meeting on 2022-11-17.

In subsequent posts I will describe change proposals in more detail. Please, whenever you comment reference the particular post.

janinamincer-daszkiewicz commented 1 year ago

COMMENT

We add a new attribute of IIA, named \<comment>. It will be placed at the end of \<iia> as optional. The namespace will not change, the version of IIA will change from 6.2.0 to 6.3.0.

See: https://github.com/erasmus-without-paper/ewp-specs-architecture#backward-compatibility-rules: Adding a new optional element to an XML file is backward-compatible. Client implementers MUST ignore unknown elements. If an element has not existed in version 1.0.0, but you want it to exist in the next version, then you can tag the next version as 1.1.0.

Scenario

  1. Partner A wants to share a comment with partner B, any time. Enters comment to the local system, sends IIA CNR.
  2. Partner B calls IIA get, reads the comment. Can check hash to make sure if anything else has been changed. It is up to partner B to decide what do do with the comment from partner A. Probably it will be stored in the local system, together with other attributes of the A's copy of IIA stored at partner B, e.g. iia-id-A, hash-A.
  3. Partner A can change the comment any time, any way, e.g. append a new comment or replace the old comment with the new one.
  4. The same can take place in the opposite direction.

Local implementations may differ, but in the specification we will offer some recommendations.

Example implementation The system keeps a history of the exchanged comments and displays them to a user in a messenger-like format: partner's comments aligned to the left, local to the right. There will be a timestamp attached to each comment - the time the comment was created (our comment) or delivered (partner's comment). Only the last our comment is editable, this one is shared with the partner. The old ones are in read-only mode. The user can decide if they want to edit the last comment or created the new one.

Please share your comments.

demilatof commented 1 year ago

I'm not in favour of the XML signature, and in my opinion, this field puts and end point to the discussion because we cannot think about signing the IIA Xml each time a new comment is added.

As concern the comment element, my opinion depends on what we aim to do with it. If it is only a comment, without special task (e.g., a special task could be the capacity of modifying an approved IIA, without touching cooperation conditions) I've nothing against it. I only think that we need some further improvements to avoid the confusions of several comments one after the other.

We have to be clear if a new comment must be appended or can replace the old comment. If it can replace the old one, A can think to be on WhatsApp and keep on adding comments in a few minutes, but what B could finally receive will be something like "best regards" because the IIA-Get retrieves only the last comment. If we think that the comment will be used only occasionally to clarify something about the IIA, the simple comment could be enough. If it is intended as a communication system along to the IIA, I don't think it's enough. But this must be stated in the specifications, because once we give an instrument, anyone can implement, use ad abuse it as he/she wants.