Electronic transfer of student records (EMREX)
:: services/emrex module

This is a BETA module. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this module, please let us know. Then, we will work with you and move it out of beta as soon as we can.

EMREX is the solution for electronic transfer of student records between higher education institutions in Europe.

This USOS API module:

  • Provides the NCP endpoint enabling other institutions to retrieve student records from this USOS installation using the EMREX protocol.
  • Serves as a backend for our local USOS-related applications. Helps with the EMREX data retrieval, its signing and verification, and with importing such data into the local USOS database.

If you are an external developer and you want to use EMREX then please note that:

  • Probably you do not need to consult USOS API documentation provided below, EMREX documentation should be enough by itself.
  • If the institution which is running this USOS API installation participates in the EMREX program then its NCP endpoint URL should be included in the EMREG list response. You should not use this NCP in production environment unless it is so.
  • This module, as well as the entire EMREX project is still in "beta" stage (it will probably come out of beta no sooner than in late 2016).
  • Our documentation might still come in handy, e.g. when troubleshooting. If you think there is something wrong with our documentation or with the generated ELMO file, then please let us know.

Methods

ncp_endpoint BETA Receive and process the EMREX NCP request

services/emrex/ncp_endpoint ΒΆ

Consumer: ignored Token: ignored Scopes: n/a SSL: required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Receive and process the EMREX NCP request, as described in the EMREX NCP documentation.

Please note that this method is supposed to be called directly by your user, within his browser (in similar fashion as the services/oauth/authenticate method).

returnUrl required

An absolute HTTPS URL of your response-receiver endpoint, no longer than 2000 characters.

The name of this parameter doesn't follow USOS API conventions (we don't normally use camelCase in USOS API) in order to by compatible with EMREX specs.

sessionId optional

Default value: (empty string)

An extra string that will be POSTed back to you when the user's browser will be returning to your returnUrl. No longer than 32 characters.

The name of this attribute doesn't follow USOS API conventions (we don't normally use camelCase in USOS API) in order to be compatible with EMREX specs.

langpref optional

Default value: en

Not part of the EMREX specs. ISO 639-1 code of the preferred language in which we should display the user interface. If we don't support the provided language, we will fall back to English.

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

Currently, if your request parameters are incorrect, then we will respond with HTTP 400 and an error message (targeted to a developer). However, since this request will be performed in your user's browser, then it is the user who will see this message, not you (and EMREX specs do not tell us what to do in such case). Try to make sure your parameters are always correct.

If the request is correct, then we will proceed as described in the EMREX documentation. The user will be alerted that his/her personal data is to be exported, and will be able to cancel the operation. The user will be allowed to select a subset of his data to be exported.

If the export takes place (the user agrees to export his data) then you can expect a POST request at your returnUrl with the following form fields included:

  • sessionId - the value you have provided in your sessionId parameter in your NCP request (if you provided any),
  • elmo - the signed ELMO document with the courses selected by the user (as described in the EMREX docs).
USOS API ver. 6.1.2.0-bc1aa53 (2016-06-07)