Interinstitutional Agreements API

• What is the status of this document?
• See the index of all other EWP Specifications

Summary

This document describes the Interinstitutional Agreements API. This API allows partners to compare their copies of interinstitutional Erasmus+ mobility agreements with each other, which makes it easier to spot errors. This API is complementary with the Interinstitutional Agreements Approval API where HEIs can approve agreements they exchange via the IIAs API.

Introduction

As part of the EWP project, we have thoroughly discussed many options of how to design the functionality of synchronizing IIAs between different HEIs. The IIAs API is the final result.

Features

• It is distributed. Agreements (IIAs) are stored and hosted only by the institutions involved in these agreements (or their providers representing them in the EWP Network).

• All partners are equal. There is no "master" of the agreement. Since all partners of a single IIA are allowed to serve their copies of this IIA, therefore multiple conflicting copies of a single IIA may exist in the network. These conflicts are not resolved by the system itself, but our APIs allow partners to discover such conflicts early (so that they may fix them by themselves).

• No history of changes. This API will serve only a single copy of the agreement (with no history of previous versions). This copy should be the copy which is currently in use by the HEI which is serving the API or the one which is being proposed to the partner.

Important rules

• Electronic versions of IIAs should model their former paper equivalents in a straightforward manner.
• Two HEIs sign one or several IIAs with one or several cooperation conditions.
• Specifications support IIAs with many cooperation conditions and each node in the network must be able to handle such IIAs to achieve this goal.
• Both copies of the same IIA stored in both partners' systems must be presented to each other as exactly one IIA having the same number of corresponding cooperation conditions.
• Partners should exchange identifiers of their copies of the IIA to match these copies respectively in their systems.
• Regardless of whether a field is mandatory in the API, if it is present in the IIA of one HEI it is highly recommended having it in the matched IIA of the partner HEI.
• Providers are free to implement their local solutions to best support the needs of their customers but under the condition that the general principle expressed in the points above is maintained.
• Termination of an IIA, which has been mutually approved, should be treated as an agreement modification if any exchanges already took place. Otherwise, it should be treated as termination of the whole agreement.
• To modify an IIA which has been mutually approved, HEIs SHOULD take a snapshot of the last approved version to be able to revert to it if they don't conclude a new approved version of the agreement.
• An IIA that has not been mutually approved can be deleted by removing it from the EWP network. Such IIA MUST NOT be exposed by the server in any of the IIA endpoints and an IIA CNR MUST be sent (see CNR client part section). The receiver MUST treat this CNR as a valid change notification and respond with an HTTP 200 response (see What constitutes a "bad CNR request"). An IIA can be removed from the EWP network only if it is permanently deleted. Identifiers of the deleted objects MUST NOT be reused for new IIAs.

Fact sheet information

If you compare our IIA XSDs to the official IIA template from the European Commission, for years 2021-20[29], you may notice that many fields seem to be missing in our XSDs. This is because we have decided to include many fields in the Institutions API and the Factsheet API instead. That is why both of the mentioned APIs MUST be implemented to use this API.

Based on the official IIA template from the European Commission for years 2021-20[29], we follow the following rules:

• General information that is part of Higher Education Institutions’ profile and made publicly available to students is part of the Institutions API (and - in some cases - Organizational Units API) and the Factsheet API. The general information can be updated without formal approval of the partner.

• Data on the terms of agreement that needs to be approved by both partners is part of this API. The approval is done in the IIAs Approval API.

Business requirements and processes

Business requirements and processes document clarifies the requirements for the technical solutions developed under EWP and in the local implementation that should adequately support the business processes related to the approval of IIAs at Higher Education Institutions.

IIA hash calculation

As of IIA version 7 each agreement contains an iia-hash element that replaces the conditions-hash element used in previous versions of this API.

To calculate the new hash an IIA get response XML has to be transformed using the appropriate XSLT template provided:

• XSLT template for IIA version 6,
• XSLT template for IIA version 7.

You can test these transformations using the provided Java class.

You may need to find the right XSLT processor for these templates to work. For Java Saxon-HE version 12.4 has been tested. For more details, please go to XSLT kit resources.

Security

This version of this API uses standard EWP Authentication and Security, Version 2. Server implementers choose which security methods they support by declaring them in their Manifest API entry.

Endpoints and functionality to be implemented

Server implementers MUST:

• Implement the get endpoint.
• Implement the index endpoint.
• Implement the stats endpoint.
• Put the URLs of these endpoints in their manifest file, as described in manifest-entry.xsd.

The details on each of these endpoints are described on separate pages of this API specification (use the links above).

Implementers also MUST implement a Notification Sender for Interinstitutional Agreement objects. That means that an EWP host will try to deliver notifications to all Interinstitutional Agreement CNR APIs implemented throughout the EWP Network whenever related agreement objects are updated.

Data model entities involved in the response

• IIA
• IIA Partner
• Cooperation Condition
• Coordinator
• Person