Interinstitutional Agreements (IIA)

Levels of estimated error severity.

If an error is present in the context of an API (or endpoint), it applies only to that API (or endpoint).

Critical	This severity level implies that the process always/usually works badly.
MAJOR	This severity level implies that the process works badly in some cases.
MEDIUM	This flaw results in unfavorable behavior but the system remains functioning.
LOW	This type of flaw won’t cause any major breakdown in the system.

List of identified issues in this category (click on the title to show details)

Description	According to specification, partners should exchange identifiers of their copies of the IIA to match these copies respectively in their systems. Further actions in the exchange flow should occur only after both partners have shared their local IIA IDs, and binding of the IDs was successful in both systems.

Description	According to specification, partners should exchange identifiers of their copies of the IIA to match these copies respectively in their systems. Further actions in the exchange flow should occur only after both partners have shared their local IIA IDs, and binding of the IDs was successful in both systems.
Estimated severity	Critical
Examples
Suggested action	Enforce absolute compliance with the specification and the exchange scenario.
How communicated	Dashboard proactive debugging using the IIAs testing scenarios

Description	Specification supports IIAs with many cooperation conditions and each node in the network must be able to handle such IIAs to achieve this goal. Partner B issuing multiple IDs for the same IIA ID that partner A has shared creates confusion to the users, seeing different IIAs (one IIA per cooperation condition), when instead these should be exchanged as one IIA in the EWP Network.
Estimated severity	MEDIUM
Examples
Suggested action	Provider should merge all affected IIAs locally and exchange these merged IIAs via the EWP Network. Enforce absolute compliance with the specification and the exchange scenario.
How communicated	Dashboard proactive debugging using the IIAs testing scenarios

Description	According to Mandatory Business Requirements an IIA is only finalised when it is approved by both partners. There are cases where Partner A creates an IIA, sends it to Partner B, Partner B approves it and unilaterally considers it finalised, i.e. approved by both partners. The IIA is stored as approved by both partners on the partner’s side, though this is not the case for the local IIA.
Estimated severity	Critical
Examples
Suggested action	Enforce absolute compliance with the specification and the exchange scenario.
How communicated	Dashboard proactive debugging using the IIAs testing scenarios

Description	Partners assume that an IIA is approved, simply because it carries signing details (as defined in the EWP specifications), when this is not the case. Approval in the EWP Network is a distinct action in the dedicated approval endpoints. This issue leads to IIAs having not synced statuses in the partners’ systems. According to Mandatory Business Requirements the EWP Spec has no interest whether an IIA has been internally officially signed or not by some institutional coordinator. Partners may include the ‘signing-contact’ or the ‘signing-date’ but this should not be taken as an approval. An IIA is approved by the approval API.
Estimated severity	MAJOR
Examples
Suggested action	Enforce absolute compliance with the specification and the exchange scenario.
How communicated	Dashboard proactive debugging using the IIAs testing scenarios

Description	According to specification, “HEI B by sending `iia_id` obtained from HEI A approves the agreement identified by this `iia_id`. However HEI B needs some proof that this agreement has not been changed by HEI A after HEI B has last seen it. To reference and approve a particular version (copy) of the partner’s agreement, HEIs attach to each agreement a digest (hash) of the cooperating conditions of this agreement. This digest MUST be verified by HEI B before sending the approval notification (via the IIA Approval CNR API). For this purpose, HEI B has to call the IIAs get API and compare the hash received in the response with the hash independently calculated from the cooperation conditions received in that response. If both hashes are identical, the agreement can be approved.” A problem can occur after a partner receives an IIA CNR and it involves changes to the cooperation conditions (see the Examples section).
Estimated severity	Critical
Examples	Initially both partners exchanged iia-ids and are synced. Hash status on the side of partner A: Hash_A_1, Hash_B_1 . Hash status on the side of partner B: Hash_A_1, Hash_B_1. Partner B makes changes to their cooperation conditions and sends an IIA CNR. Hash status on the side of partner A: Hash_A_1, Hash_B_1. Hash status on the side of partner B: Hash_A_1, Hash_B_2. Partner A gets the IIA and saves the changes to system. Hash status on the side of partner A: Hash_A_2, Hash_B_2. Hash status on the side of partner B: Hash_A_1, Hash_B_2. Now if partner B wants to send approval to partner A, they will have to include partner A’s hash in the approval. But it happens that the latest hash that partner B knows is Hash_A_1, while partner A has Hash_A_2. This means that the approval of partner B will be rejected because it includes an incorrect hash. This issue leads to potentially blocked approval actions.
Suggested action	The solution is for partner A to send an IIA CNR when they received changes that altered their hash, so both partners have the latest version of hashes.
How communicated	Dashboard proactive debugging using the IIAs testing scenarios

Description	EWP partners have their local hash inside the <conditions-hash> and not the partner’s hash from their IIA GET response. If they are not sharing the correct hash, the partner is not able to respond to their IIA Approval CNR. Approval actions are potentially blocked, not allowing the finalisation of the IIA.
Estimated severity	Critical
Examples
Suggested action	Enforce absolute compliance with the specification and the exchange scenario.
How communicated	Dashboard proactive debugging using the IIAs testing scenarios

Description	The IIA comes to HEI A without iia-code of the IIA copy of partner B, but iia-code is mandatory.
Estimated severity	Critical
Examples
Suggested action	Enforce absolute compliance with the specification
How communicated	Email correspondence with providers

Description	According to specification (link1, link2) iia-code is the partner's "human readable" ID of this IIA (aka an agreement number). Since `iia-id` values should contain surrogate identifiers (and, as such, should not be displayed to the user), we require additional "human readable" agreement codes/numbers to be provided.
Estimated severity	LOW
Examples	CORRECT IIA-ID = 84cf84-ce6c6322-942cb697-a95b1d6-4074d4dc-863 IIA-CODE = 123456 or IT-2023-105 or 1003/E+/KA131 IIA-ID = 123456 IIA-CODE = 123456 WRONG IIA-ID = 84cf84-ce6c6322-942cb697-a95b1d6-4074d4dc-863 IIA-CODE = 84cf84-ce6c6322-942cb697-a95b1d6-4074d4dc-863 IA-ID = 123456 IIA-CODE = 84cf84-ce6c6322-942cb697-a95b1d6-4074d4dc-863
Suggested action	Enforce absolute compliance with the specification. Partners should use human-readable iia-codes.
How communicated	GitHub, Infrastructure Forum

Description	If iia_id is completely unknown to the server, it should send HTTP 200 as IIAs Approval get response, according to specification.
Estimated severity	MAJOR
Examples
Suggested action	Enforce absolute compliance with the specification
How communicated	Email correspondence with providers This error was encountered in a number of mobility systems

Interinstitutional Agreements (IIA)

Related content