EMREX technical guide
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 version, see 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 result 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 EMREX Client (EMC)
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 EMREX Data Provider (EMP).
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 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 the data in itself.
There a 5 main parts that will be referred to through this document:
Common components of EMREX (no local work required):
Some local work required:
EMREX Client. This is a plugin that EMREX uses to enable the communication with an EMP, and to ensure that the communication with the EMP is done in a standardized way
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.
3. EMREX Client.
This is the web application that the student uses to initiate the transfer of their results from another country. (could be integrated into the HEI SIS, i.e. work needed by the HEI)
EMREX Data Provider. This is the point that the EMREX client contacts to fetch results.
Potentially much local work required.
5. Results Services
These are the services that are used by the EMP to fetch the results for the students. If you have an existing system that handles this, the EMP can simply connect to this. However, if none exist, there may be a major job to implement this.
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.
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).
Choosing the EMP
In order to initiate the transfer, one must first choose the EMREX Data Provider to get the results from. This is done by contacting EMREG, a centralized service that gives a list of all available EMP’s, as well as other information necessary to establish communication with each of them.
At the moment, the URL for EMREG is as follows;
– Production: https://fsweb-demo.uio.no/emreg/list
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 EMPs for each institution. In that case, after the country has been selected, the student will be presented with a list of all EMPs registered for that country, and for each EMP only the first institution on the list will be presented to the student (even though, for compatibility reasons, it will stil be delivered by EMREG as a list).
Sending a request to the EMP
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 “multiform/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 EMP but us returned as part of the reply so that the requester can check that the response comes from the EMP as past of the same session.
2. returnUrl: The URL that the EMP shall use to post the reply.
As this service is still under development, additional parameters might be added at a later point.
Receive 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 wen well, results have been transferred
2. NCP_ERROR: Something went wrong. The error 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’s 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 EMP 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 EMP library.
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 fromat
emrex-client: An example client that can be used to fetch results.
EMP-mockup: An example EMP.
EMC: EMC stand for EMREX Client. 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 use a REST service for contacting EMREG (you just need to provide the URL for EMREG). In addiation, 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 the EMREX GitHub repository.