Technical

13th October 2016

This document is the full technical description of EMREX, and describes what has to be implemented locally to connect to the EMREX Network. For a short guide – se below.

 

EMREX technical guide

This is a technical description of EMREX, you can find here information on what has to be implemented locally to connect to the EMREX network.

Each country has two roles in the EMREX network:

  1. Provide the student with application(s) that allow them to fetch their results from another HEI, either in the same country or from abroad. This will later on be referred to as the EMREX Client and includes the functionality of the Student Mobility Plugin (SMP).
  2. Provide national client(s) with functionality to fetch assessments (results from courses, qualification) from the databases containing this information. This will later on be referred to as the National Contact Point (NCP).

Because EMREX is a decentralized system, there is no major component that each country can reuse. The EMREX project does provide some modules, plugins and examples that can be used and built upon, however there are a couple of issues that cannot be solved in a general way:

  1. Authenticating a student. Each country has their own way of authenticating a student in their system. In Norway there are Feide and ID-porten, Finland has Haka, Sweden has Swamid and so on. Therefore, the EMREX project cannot make a complete login module and distribute this, as each country solves this in different ways.
  2. Fetching results for a student. Each country/HEI has their own student information systems. Some countries have national data sources that can provide this information. Therefore, there is not one unified way of fetching results from these systems. The EMREX-system is dependent on connecting to an existing solution that can fetch results for a given student at a given HEI. The preferred solution is to build a REST service for each student information system involved, that provides ELMO formatted data.
  3. Storing results for a student. Each country/HEI has their own student information systems. So there is no standard way of storing the result data the EMREX fetches into the existing student system. When the EMREX client returns a set of results for a student, these must be stored in some local system, as EMREX does not store data in itself.

There are 5 main parts that will be referred to through this document:

  1. Common components of EMREX (no local work required)
    1. SMP: Student Mobility Plugin. This is a plugin that the EMREX client uses to enable the communication with a NCP, and to ensure that the communication with the NCP is done in a standardized way.
    2. EMREG: This is a central registry the EMREX uses to fetch the data that is needed to complete the result transfer. This is also the only centralized component in the EMREX system.
  2. EMREX Client: This is the web application that the student uses to initiate the transfer of their results from another country. (Some local work required, could be integrated into the HEI SIS, i.e. work needed by the HEI)
  3. NCP: National Contact Point. This is the point that the EMREX client contacts to fetch results. (Some local work required)
    1. Result Services: These are the services that are used by the NCP to fetch the results for the student. If you have an existing system that handles this, the NCP can simply connect to this. However, if none exist, there may be a major job to implement this. (Potentially much local work required)

 

Architecture

The following diagram shows in detail the data flow for a student wanting to import results from two different result providers (for instance, higher education institutions) in the same country.

technical_picture_1

It is up to each implementer to decide whether the SMP will run as a standalone service, or embedded into their client. The EMREX project provides a SMP library which can be used out-of-the-box as a standalone service.

The same remark applies to the result provider(s), the implementation is very much dependent on the underlying system(s).

Getting the results

This chapter is meant for consumers of results from other countries. There are 3 main steps the client needs to perform in order to get results from another country, each of which will be described in detail:

  1. Choosing the NCP
  2. Sending a request to the NCP
  3. Receiving a response
  4. Interpreting and handling the data

Choosing the NCP

In order to initiate the transfer, one must first choose the National Contact Point to get the results from. This is done by contacting EMREG, a centralized service that gives a list of all available NCPs, as well as other information necessary to establish communication with each of them.

At the moment, the URL for EMREG is as follows:

The response from EMREG contains a list in the following JSON format:

The list contains a parameter called “singleFetch” saying whether a particular country has separate NCPs for each institution. In that case, after the country has been selected, the student will be presented with a list of all NCPs registered for that country, and for each NCP only the first institution on the list will be presented to the student (even though, for compatibility reasons, it will still be delivered by EMREG as a list).

Sending a request to the NCP

The request is sent from a requester as HTTP POST and has two parameters. Note that the form must be of the default type, not “multipart/form-data”:

The hidden parameters are as follows:

  1. sessionId: A generated unique session id from the requester. This session id is not used by the NCP but it is returned as part of the reply so that the requester can check that the response comes from the NCP as part of the same session
  2. returnUrl: The URL that the NCP shall use to post the reply

As this service is still under development, additional parameters might be added at a later point.

Receiving a response

The response is sent as a HTTP POST back to the EMREX Client with four parameters:

The following return codes are supported (the list is subject to change):

  1. NCP_OK: Everything went well, results have been transferred
  2. NCP_ERROR: Something went wrong. The error message will be in the “returnMessage”
  3. NCP_NO_RESULTS: There were no results to import into the client
  4. NCP_CANCEL: The user has cancelled

The “sessionId” must be the same as the one sent in the request. If it is not the same as the one that was sent, this response should not be processed.

The “elmo” parameter is the main piece of this response. It will be gzipped and encoded in Base64 for transfer.

Interpreting and handling the data

The ELMO XML format contains the results themselves. The document is signed, using the XML DSig format, with the private key of the NCP that issued it. The public key can be obtained from EMREG. If signature verification fails, it means the results have been tampered with and MUST be rejected.

In addition to verifying the signature, the receiving client must ensure the results belong to the same person requesting them. ELMO includes the person’s name and birthday which can be used for this purpose. Both signature and person verification are provided by the SMP library.

Code examples

The EMREX code is open source and can be downloaded from the EMREX GitHub account.

The following repositories are provided:

  • elmo-schemas: XSD for the ELMO XML format
  • emrex-client: An example client that can be used to fetch results
  • ncp-mockup: An example NCP.
  • SMP: SMP stands for Student Mobility Plugin. It is a client library with helpful methods that the client can use to join the EMREX network. It can also be run as a standalone application, providing you a REST service for contacting EMREG (you just need to provide the URL for EMREG). In addition, the library contains a method for verifying digital signatures, which can also be called as a REST service.

The ELMO XML format

The ELMO XML format is the basis for the exchange of result information. ELMO is based on the CEN standard EN 15981-2011 EuroLMAI. EuroLMAI is a data model describing assessments, primarily Diplomas, Diploma Supplements and Transcripts of Records for higher educations. The schema describing the profile of the ELMO format used in EMREX is available in the EMREX GitHub repository.