Rejection / termination of IIAs

[georgschermann]

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]

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]

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]

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]

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]

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]

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]

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]

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

[j-be]

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

• IIA is "deactivated", meaning it is not in effect anymore from now on (keep in mind, that in-effect in XSD states "is or once was", so by spec it can't be used for this)
• Single cooperation change, like "used to have 10 total months, now is 15"

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

[lioliosn]

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]

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

[georgschermann]

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]

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]

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:

• terminated (+ date of termination field is required along with)
• pending-termination (+ a termination date in the future is required along with)
• active/valid
  (... can be extended)

Notes for fields:

• "pending-termination" or any similar status together with a termination date will let partner know on which date this agreement will be terminated on its partner side. So for example, if my partner's status=pending-termination + termination date= 2022-06-30, then I will know that my HEI can use this agreement for mobilities until that date and after that date, the agreement will become terminated.

• Along with this, the academic years should be updated to be consistent with the termination date.

• "terminated" status will let partners know this agreement is terminated and it was terminated on the given termination date.

• active/valid status will state that this agreement is still active or valid (not terminated) in each partners side.

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]

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]

@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]

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

[janinamincer-daszkiewicz]

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:

• Draft - the IIA is available to the partner who can get it any time, but the local copy is not yet ready for approval, may be it has not yet been seen by human nor analysed (see discussion in Which IIAs should be published to the counterparty? #89).
• Ready (for approval) - this IIA is ready to be approved, details have been discussed by humans and generally agreed, now its time to carry out the approval process.
• Approved - this IIA has been approved by the partner.
• Deleted - this IIA has been deleted; this is the final state.
• Terminated - this IIA has been terminated; this is the final state.

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: #92.

[demilatof]

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]

I think that:

• Draft is actually not necessary if we agree that these IIAs should not be published to the counterparty.
• 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)
• Approved could be similarly inferred from the presense of the cooperation-conditions-first-version element.
• 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.
• 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.

[kamil-olszewski-uw]

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]

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]

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]

In erasmus-without-paper/ewp-specs-api-iias-approval#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 Making changes in the approved agreement #92 (comment). 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]

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.

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

[demilatof]

@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]

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.

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 erasmus-without-paper/ewp-specs-api-iias-approval#5 for IIA status

[umesh-qs]

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 erasmus-without-paper/ewp-specs-api-iias-approval#5 address all the concerns?

[demilatof]

@demilatof

Because the CNR may arrive or not, I would not reccommend to send it, we simply delete the not yet approved IIA.

According to specificaton you should always send CNR when the object changes. It is true that in rare occasions the CNR will get lost but in majority of cases it will reach the target and you partner will know immediately that the object has been deleted.

I understand, but normally we have a CNR to inform that something has changed and we can understand what by calling a second API (e.g. IIA Get).
But if we delete an IIA, the second API will tell us nothing, because the IIA has been deleted.
We cannot distinguish between a deleted IIA and nonexistent IIA (that is, a wrong IIA Id).

It seems to me that you rely on the fact that the other partner has previously downloaded/considered the IIA, but we cannot be sure.
Therefore it would receive a CNR for something that it could not be able to understand: "you send me an IIA CNR and when I do an IIA Get I discover that its IIA Id is unknown? Are you joking?"

Another example: by mistake your system generates 100 IIAs; you delete them and then you have to send 100 CNRs to the partner that after that will perform 100 IIA-Gets... to obtain nothing?

[janinamincer-daszkiewicz]

I understand, but normally we have a CNR to inform that something has changed and we can understand what by calling a second API (e.g. IIA Get).

In that case CNR would indeed inform about the change - deleted IIA.

Another example: by mistake your system generates 100 IIAs; you delete them and then you have to send 100 CNRs to the partner that after that will perform 100 IIA-Gets... to obtain nothing?

To inform your partner that all these IIAs have been deleted.

[demilatof]

I understand, but normally we have a CNR to inform that something has changed and we can understand what by calling a second API (e.g. IIA Get).

In that case CNR would indeed inform about the change - deleted IIA.

But a CNR don't tell if it is about a changing or a deletion...

Another example: by mistake your system generates 100 IIAs; you delete them and then you have to send 100 CNRs to the partner that after that will perform 100 IIA-Gets... to obtain nothing?

To inform your partner that all these IIAs have been deleted.

To inform your partner of something that could have never seen and therefor is not interested in...

It seems to me that you are not interested in the confusion that could bring the fact that I receive a CNR for something that I've never seen and that I will not be able to see anymore...
To be more clear: you tell me that IIA with Id 123 is changed (CNR cannot tell that is deleted); ok, I perform an IIA get and you answer me that ID 123 is invalid or unknown. What should I think? Your system has deleted an IIA that I didn't know or your system fails when I've called the IIA Get and I've to repeat the call later?
If you want a CNR I suggest you to use a different one, such as IIA-Deleted-CNR, so that the information is in the API name if we cannot add to the CNR request.
I hope you understand why I say that a CNR is a poor notification system... It brings too little information.
If we want a CNR system, we have to provide a different CNR for every kind of CNR notification (changes, deletions and so on).

[janinamincer-daszkiewicz]

Please read specification of CNR in the EWP Network.

Thank you very much for all these questions. Could you tell us what solution you prefer from those listed?

[demilatof]

Please read specification of CNR in the EWP Network.

Thank you very much for all these questions. Could you tell us what solution you prefer from those listed?

I have read. Did you?
https://github.com/erasmus-without-paper/ewp-specs-api-iia-cnr

The IIA-CNR requires only: notifier_hei_id and iia_id.
When we call IIA-Get we cannot distinguish between an unknown IIA Id and a deleted IIA; but we have received a CNR!

We should have the IIA exposed in some way, but we cannot because the BPO said that we can expose only IIAs that can be approved (and a deleted IIA cannot be approved).
It seems to me that you'd like to ignore the questions that are essentials for us to implement a decision chain in our internal system: the other system is failing when it tries to serve us a changed IIA or it doesn't serve us the IIA because it was deleted?

I voted for 1-a), but I think we need correctives because these specifications introduce ambiguities.
If there is no place for discussion, A B or C for me is the same; I'll implement a workaround even for this task, as I have to do for every critical point of EWP specifications.

[umesh-qs]

I agree that unintentionally somebody may post IIA which should have not been posted. If that happens, such IIA may be deleted. Do you see better solution?

Yes. Either the IIA response content or unique response code should tell that the IIA is deleted. There should not be any scope of ambiguity.

[pargentieri]

DELETION

After internal discussion we see that we need your answers to the following questions to finalize the specification. Please consult your users and answer.

1. How long should we keep deleted IIAs?
   (a) Deleted IIA should be removed from the database, CNR should be sent and the answer to IIA get should be 400.
   (b) Until some moment recommended in the specification (the end of academic year, the end of Erasmus programme 2021-2027? any other?)
   (c) Forever.
2. If 1b or 1c is chosen, what should we keep in the database and send in response to IIA get?
   (a) IIA in its original form and its hash.
   (b) Well constructed IIA with removed optional fields (we called it 'zombie').
   (c) Only IIA-id.
3. Do we need a deletion date?
   (a) Yes, partner A deletes IIA, generates the deletion date, keeps it as part of IIA and shares via IIA get with partner B.
   (b) No need to share the deletion date via the network. If A or B needs to have a date will handle it locally but will not share it with the partner.

Hi, I'm Pietro, Politecnico of Milano.
About point 2b:
I don't understand "Well constructed IIA with removed optional fields". Why removing optional fields should mean that this IIA was deleted?

[LDeprez]

The answer of Ghent University:

Only IIA's that are not approved can be deleted.

How long should we keep deleted IIAs?
=> We remove them from database. CNR is sent and the answer to IIA get is 200 and empty.

I think a http status code 4** is not providing a solution for IIA Get requests that contain multiple iia-id's/iia-codes

[umesh-qs]

uld we keep deleted IIAs?
=> We remove them from database. CNR is sent and the answer to IIA get is 200 and empty.

We are forcing the partner to call IIA Get for a single IIA ID. Additionally there is no scope for any mistake. This solution will potentially add more pain/work for the IROs.

[janinamincer-daszkiewicz]

Yes. Either the IIA response content or unique response code should tell that the IIA is deleted. There should not be any scope of ambiguity.

Deletion date would solve this problem.
For index we still have the option of separate list of deleted iia-ids.

[janinamincer-daszkiewicz]

TERMINATE

We add a new attribute of IIA, named <termination-date>.
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.

Scenario

1. Partner A decides to unilaterally terminate IIA approved by A and B.
2. Partner A adds termination-date to IIA, sends IIA CNR to partner B.
3. Partner B calls IIA get, finds the termination-date.

Partner A would like to get some confirmation from B that he got the A's decision (equivalent to acknowledgment of receipt). If we do not want to add new API (to avoid changing the namespace) we can use IIA Approval.

1. Partner B sends IIA Approval CNR.
2. Partner A calls IIA Approval get. The response contains:

<approval>
 <iia-id>iia-id of the copy terminated by A</iia-id>
 <conditions-hash>original hash of the approved copy terminated by A</conditions-hash>
 <termination-date>repeated termination date<termination-date>
</approval>

Index parameters

• hei_id (required)
• partner_hei_id (optional)
• receiving_academic_year_id (optional, repeatable)
• modified_since (optional)
• include-deleted (optional) default YES; if given and value is NO, then the server should not send deleted IIAs (if we decide to keep deleted IIAs).
• include-terminated (optional) default YES; if given and value is NO, then the server should not send terminated IIAs.

[janinamincer-daszkiewicz]

P.S. We still have time to work out the details of these proposals. Please note that all three (COMMENT, DELETE, TERMINATE) are backward compatible, as we only introduce optional parameters. No change in namespace, version would change from 6.2.0 to 6.3.0. That the impact on the existing implementations would be the smallest possible.

These changes would not be backward compatible:

• Consecutive academic years: Consecutive academic years or not? #70
• Replace PDF argument with file id: File ID and its contents ewp-specs-api-omobilities#44

[demilatof]

P.S. We still have time to work out the details of these proposals. Please note that all three (COMMENT, DELETE, TERMINATE) are backward compatible, as we only introduce optional parameters. No change in namespace, version would change from 6.2.0 to 6.3.0. That the impact on the existing implementations would be the smallest possible.

Please keep in mind that no change in namespace doesn't necessarily involve the smallest impact on the existing implementations.
Every time we decide to use an existing API to make something new respect what it was designed for, we introduce a weak point in the existing implementations. And no one can assure that this problem could be addressed in a satisfactory way.
Only adding new dedicated APIs along with the existing ones could reduce the impact on the existing implementations.
New functionalities (comment, delete, terminate) => New APIs

[Piargentieri]

P.S. We still have time to work out the details of these proposals. Please note that all three (COMMENT, DELETE, TERMINATE) are backward compatible, as we only introduce optional parameters. No change in namespace, version would change from 6.2.0 to 6.3.0. That the impact on the existing implementations would be the smallest possible.

These changes would not be backward compatible:

• Consecutive academic years: Consecutive academic years or not? #70
• Replace PDF argument with file id: File ID and its contents ewp-specs-api-omobilities#44

Why can't add new APIs instead of modify the current implementation?
New API=NO backwards compatibility problems so we achieve this goal : "the impact on the existing implementations would be the smallest possible"

[demilatof]

Let's do a game!

TERMINATE
...
Partner A would like to get some confirmation from B that he got the A's decision (equivalent to acknowledgment of receipt). If we do not want to add new API (to avoid changing the namespace) we can use IIA Approval.

Partner B changes the cooperation conditions for the mobilities that will take place before the termination date and it doesn't send an IIA-CNR; then:

1. Partner B sends IIA Approval CNR.

2. Partner A calls IIA Approval get. The response contains:

<approval>
 <iia-id>iia-id of the copy terminated by A</iia-id>
 <conditions-hash>original hash of the approved copy terminated by A</conditions-hash>
 <termination-date>repeated termination date<termination-date>
</approval>

Only after reading the above response A can realize that calling Approval API it has approved a different IIA, approving not only the termination but even some changes.
And are we still talking about legal proof?

The specifications should say that it is mandatory (always, not only for a "termination"):

1. Saving the hash code of the last IIA that the IRO's have checked
2. And that, before calling the approval API, the system has to perform an IIA-Get to be sure that its hash code is no different from the one previously checked.

[jiripetrzelka]

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.

Later in this thread you suggested that an IIA undergoing changes should be kept visible to the counterparty in the original version. However, it can hardly be the "intention of the exposing party" to have the original IIA approved while it is making changes. Therefore it is necessary to either hide the IIA, or keep it visible and let the counterparty know that it should not approve it yet. If we choose the second option, drafts are necessary.

2. We add comment field to IIA (outside hashed part) and exchange it via IIA get.

The comment field will be useful in my opinion.
But, as discussed in erasmus-without-paper/general-issues#38 there is also the need to comment on the reason why a partner's IIA with a specific hash cannot be approved (yet) by the counterparty. My impression from the thread is that the contributors generally agreed that this feature would be useful, although there was no clear agreement on the way how to implement it. What is your stance in regard to the "other" comment, @janinamincer-daszkiewicz ?

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.

Option 2 seems enough to me.

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.

Termination should be used for the purposes it was supposed to, not for amendments. Amendments can be done by changing the IIA Get response and have it re-approved. Server implementers should be required to keep all logs and therefore be able to find the original partner IIA before amendment, if need be.

As far as termination is concerned, we should distinguish between unilateral termination versus termination agreed by both parties. In the first case the party unilaterally terminating an IIA will need to have a proof that it informed the counterparty at least one year in advance. In the second case, we need the approval of the counterparty.

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.

If the intention of the parties is not to terminate the cooperation as such then termination should not be used. Amendments should be used.

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.

If we start to think this way, we actually don't need IIA approvals at all because we can be "flexible" and allow anything. Important changes, such as number of persons, months/days, study levels and the blended option need to be mutually approved and the easiest technical solution for this is to allow changing the IIA Get even after it has been approved by both parties.

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.

You do introduce states. They are just not explicit. By adding the termination-date, you introduce the "terminated" virtual state (or "to-be-terminated" state, to be precise). By adding deletion-date, you would add the "deleted" virtual state.

The need for states has not disappeared, you have just stopped using the word "state".

DELETION

1. How long should we keep deleted IIAs?
   (a) Deleted IIA should be removed from the database, CNR should be sent and the answer to IIA get should be 400 (mistake, not 400 but 200).
   (b) Until some moment recommended in the specification (the end of academic year, the end of Erasmus programme 2021-2027? any other?)
   (c) Forever.

I prefer (b).

2. If 1b or 1c is chosen, what should we keep in the database and send in response to IIA get?
   (a) IIA in its original form and its hash.
   (b) Well constructed IIA with removed optional fields (we called it 'zombie').
   (c) Only IIA-id.

I prefer (c).

3. Do we need a deletion date?
   (a) Yes, partner A deletes IIA, generates the deletion date, keeps it as part of IIA and shares via IIA get with partner B.
   (b) No need to share the deletion date via the network. If A or B needs to have a date will handle it locally but will not share it with the partner.

I prefer (b).

TERMINATE

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

Scenario

1. Partner A decides to unilaterally terminate IIA approved by A and B.
2. Partner A adds termination-date to IIA, sends IIA CNR to partner B.
3. Partner B calls IIA get, finds the termination-date.

Partner A would like to get some confirmation from B that he got the A's decision (equivalent to acknowledgment of receipt). If we do not want to add new API (to avoid changing the namespace) we can use IIA Approval.

1. Partner B sends IIA Approval CNR.
2. Partner A calls IIA Approval get. The response contains:

<approval>
 <iia-id>iia-id of the copy terminated by A</iia-id>
 <conditions-hash>original hash of the approved copy terminated by A</conditions-hash>
 <termination-date>repeated termination date<termination-date>
</approval>

In this scenario, partner B cannot know for sure from which academic year the IIA is supposed to be terminated. It is not inferrable from the termination-date.

Also, partner A could freely set the termination-date to an earlier date (say, in January 2023, it would set it to 2022-08-31) and later claim that it was an unilateral termination and partner B's approval is therefore not needed and reject nominations based on this claim (in this example, nominations for 2023/24).

On which party would the burden of proof lie? If on partner A, then it would need a log of an incoming IIA Get from no later than 2022-08-31. If the date http header is also not older than 2022-08-31 and the Http Signature is valid, then partner B was clearly informed in time to terminate the IIA for any mobility starting from 2023-09-01 onwards, no approval/confirmation needed.

The only problem would be if B's implementation was buggy and wouldn't retrieve the IIA Get based on incoming IIA CNR. In that case A could provide the IIA CNR log from 2022-08-31 and say that it wanted to unilaterally terminate the IIA. It would be the problem of partner B that it did not react to the IIA CNR. But these are borderline cases...

[janinamincer-daszkiewicz]

DELETION

Two options emerge from the discussion so far:

1. If we agree that IIA may be removed, it is deleted, and we return 200 to IIA get.
2. If we decide that IIA should stays, we need to differentiate deletion from the other change made to IIA. If we do not need to exchange the deletion date, we send the list of IIAs and the list of ids of deleted IIAs in response to IIA get.

Which one we prefer?

[janinamincer-daszkiewicz]

@jiripetrzelka If we look for simple solutions, it is better not to introduce drafts, not to introduce amendments, and use comment only in response to IIA get. If we do not want to approve partner's IIA with a specific hash, we send IIA CNR and explain the reason in the comment.

Terminate is (according to IIA template) "unilateral decision to discontinue the exchanges". We don't ask for 'approval'. Having 'confirmation' would be nice but we can live without it.
The template says: "decision to discontinue the exchanges notified to the other party by 1 September 20XX will only take effect as of 1 September 20XX+1". Why if the termination date not sufficient?

[demilatof]

DELETION

Two options emerge from the discussion so far:

1. If we agree that IIA may be removed, it is deleted, and we return 200 to IIA get.

2. If we decide that IIA should stays, we need to differentiate deletion from the other change made to IIA. If we do not need to exchange the deletion date, we send the list of IIAs and the list of ids of deleted IIAs in response to IIA get.

Which one we prefer?

Option 1: with or without IIA-CNR when an IIA is deleted?

Option 2: we often talk about choosing the simplest solution. The simplest solution is not to touch existing APIs, but introducing a new one: IIA-deleted-Index. The existing code doesn't need to be touched.
What do you mean with "IIA should stay"? We can retrieve it with an IIA-Get even if it is present in the deleted IIAs list in the Index API?

[janinamincer-daszkiewicz]

Option 1: with or without IIA-CNR when an IIA is deleted?

With CNR.

What do you mean with "IIA should stay"? We can retrieve it with an IIA-Get even if it is present in the deleted IIAs list in the Index API?

Yes. At least iia-id is still available.

[demilatof]

Terminate is (according to IIA template) "unilateral decision to discontinue the exchanges". We don't ask for 'approval'. Having 'confirmation' would be nice but we can live without it.
The template says: "decision to discontinue the exchanges notified to the other party by 1 September 20XX will only take effect as of 1 September 20XX+1". Why if the termination date not sufficient?

The template is nearer to a "with paper" approach than to a "without paper" approach.
All that said, the template uses the word "notified" that has a legal meaning. The template doesn't say "communicated to the other party" but "notified".
Notify means that we have the acknowledgement that the other party has received the communication, therefore I think it's wrong thinking that we can live without it.
We need a confirmation by the partner and we need something similar to the approval, but not the Approval API because it may be misused to approve even some changes in cooperation conditions.

[demilatof]

Option 1: with or without IIA-CNR when an IIA is deleted?

With CNR.

As I've already said, an IIA-CNR followed by an IIA-Get that return 200 could represent both a deleted IIA and a temporary error in serving the IIA: "Invalid (or unknown) iia_id and iia_code values 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"
We have to know if we have to repeat later the IIA-Get or not.

What do you mean with "IIA should stay"? We can retrieve it with an IIA-Get even if it is present in the deleted IIAs list in the Index API?

Yes. At least iia-id is still available.

Cooperation-conditions are mandatory; they should be present.
How can I differentiate it from an incomplete IIA? What happens if the other party forgets to empty the agreement?
Should I rely on the Index API or on IIA-Get API to think that an IIA has been deleted?

Allowing the IIA-Get to return something is not in contrast with this sentence?

[umesh-qs]

Option 1: with or without IIA-CNR when an IIA is deleted?

With CNR.

We already mentioned multiple times that this is ambiguous and can create more problems. Not acceptable to us.

What do you mean with "IIA should stay"? We can retrieve it with an IIA-Get even if it is present in the deleted IIAs list in the Index API?

Yes. At least iia-id is still available.

[demilatof]

Option 1: with or without IIA-CNR when an IIA is deleted?

With CNR.

We already mentioned multiple times that this is ambiguous and can create more problems. Not acceptable to us.

I agree with you; could a new IIA-Delete-CNR API be a solution?
I add some doubts: we agree that only a not approved IIA may be deleted.

1. What happens if a party deletes an approved IIA anyway with or without notification?
2. What happens if a party adds an IIA Id to the deleted list in the Index, but we can fully retrieve it anyway with an IIA-Get?
3. What happens if a party deletes an IIA Id, sends an IIA-CNR (hopefully an IIA-Delete-CNR) and immediately after that it changes its mind and recovers the IIA, so that we obtain it with an IIA-Get?

To be clear: case 2) is by mistake, case 3) is by intention

[jiripetrzelka]

@jiripetrzelka If we look for simple solutions, it is better not to introduce drafts, not to introduce amendments, and use comment only in response to IIA get. If we do not want to approve partner's IIA with a specific hash, we send IIA CNR and explain the reason in the comment.

I too consider my counterproposals to be simple solutions because, for example, to use IIA Get for amendments after the IIA has been approved by both parties builds on something that we have already implemented. It would also be simpler for end-users to keep track of changes that belong to one IIA.

As for the comments in own IIAs, they won't be universally usable for commenting on partner proposals because not all partner IIAs are linkable to own IIAs. The need to communicate the reasons for not approving these IIAs via e-mail will remain. The solution to abandon the proposal is therefore simple (and cheaper) for implementers but the process won't be made simpler for IROs.

---

Terminate is (according to IIA template) "unilateral decision to discontinue the exchanges". We don't ask for 'approval'. Having 'confirmation' would be nice but we can live without it.
The template says: "decision to discontinue the exchanges notified to the other party by 1 September 20XX will only take effect as of 1 September 20XX+1". Why if the termination date not sufficient?

From https://erasmus-plus.ec.europa.eu/resources-and-tools/inter-institutional-agreement

It is up to the involved institutions to agree on the procedure for modifying or terminating the inter-institutional agreement.
So if both parties find an agreement, they can decide to a) modify, b) terminate the IIA.

However, in the event of unilateral termination, a notice of at least one academic year should be given.
So in this specific case when partners cannot or will not find a mutually acceptable solution, then a specific deadline applies.

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.
And this is this just a clarification that applies for the specific case when the IIA is being terminated unilaterally.

Also relevant is:

Examples of my interpretation:

Suppose we have an IIA signed by both parties from 2022/23 to 2028/29.
Suppose the partners have not specified anything about their specific deadlines for amendments and termination in the other-info-terms (which, I presume, would generally be possible).

Suppose it is now 15 January 2023. What can happen? For example:
a) Partners mutually agree to amend the IIA in any way they see acceptable for any academic year(s) from 2023/24 to 2028/29.
b) Partners mutually agree to terminate the IIA from academic year 2022/23 (this could have effect, for example, on blended mobilities in summer 2023).
c) Partners mutually agree to terminate the IIA from academic year 2023/24.
d) Partners mutually agree to terminate the IIA from academic year 2024/25.
e) One partner unilaterally decides to terminate the IIA from academic year 2024/25.

Are all these scenarios possible? And what about 15 February 2023? What if partners have not have enough time to discuss the changes in January and want to make changes for 2023/24. Is this strictly forbidden (because the IIA says "no later than the end of January") or is there some leeway in practise if both agree? But how much leeway? Until March, April, ...?

[janinamincer-daszkiewicz]

As for the comments in own IIAs, they won't be universally usable for commenting on partner proposals because not all partner IIAs are linkable to own IIAs. The need to communicate the reasons for not approving these IIAs via e-mail will remain. The solution to abandon the proposal is therefore simple (and cheaper) for implementers but the process won't be made simpler for IROs.

I do not see it. I have to match IIAs on both sides before I send the Approval (with comment or without).
What scenario do you have in mind?

[jiripetrzelka]

I do not see it. I have to match IIAs on both sides before I send the Approval (with comment or without).
What scenario do you have in mind?

For example, if the partner IIA is a duplicate of another partner IIA, which is already linked to the correct local IIA.
Or if the IIA from partner has not been agreed at all (for example, they think that the IIA has been renewed from the 2014-20 period but our coordinator thinks it has not been agreed).
Or if the IIA is just a fragment of local IIA and should be merged with another partner IIA before it can be linked to local IIA.
Or if the IIA is a combination of multiple local IIAs and should be first split into multiple IIAs.
Or if the IIA is with a university with which there has been no communication to have an IIA at all.

In these cases it does not make sense to link partner IIA to local IIA.
The coordinator needs to inform the partner that an action is required from them before it can be linked to local IIA.

[janinamincer-daszkiewicz]

The discussion continues in #99.