Skip to end of metadata
Go to start of metadata

NCP is short for National Contact Point, and will be the entry point that Emrex will use to fetch data from a country. 

NCP tasks

  1. The NCP receives a request to initiate fetching results.
  2. The NCP initiates a login. This means that the NCP must be a web application that can implement a secure login.
  3. The NCP fetches results for the student that has logged in. This part cannot be standardized, as it varies from country to country. 
    1. Example from Norway: In Norway there is a national web service that can fetch results for a student in two ways:
      1. Call the web service with a HEI-id, and the results are fetched only from this HEI
      2. Call the web service without any id. The web service will then ask every HEI if there are any results
      The web service will return ELMO-xml see Format example - Norway for an example of an XML
  4. The NCP presents the collected results to the student and allows him/her to select which results will be transferred
  5. Based on the selected results, generate an ELMO document. Based on the ELMO document, generate a PDF, sign this PDF and attach the signed PDF to the ELMO document.
  6. The NCP returns the ELMO to the requester, signed with its private key using the XML-DSig standard.

NCP data in EMREG

The NCP has registered some data about it in a central registry, called EMREG:

  1. URL: The URL that the requester should post the request on
  2. Public key: The public key that the requester uses to verify the signed XML document
  3. Institutions: A list of institutions the NCP is responsible for.
  4. A couple of other parameters (see page Implementation details: EMREG for details)

Request

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 request HTML form looks like this:

NCP Request
  1. Session Id: A generated unique session id from the requester (max 32 characters). 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 correct NCP
  2. Return URL: The URL that the NCP shall use to post the reply (max 2000 characters).

Login

The NCP must provide a login function. This login type should be the same as the students use to log in to the country's student applications. In Norway this is Feide, in Finland this is Haka, in Sweden this is Swamid and Denmark has Wayf.

Presenting the collected results

The NCP should present a list of all results with name, code, result and credits. If the results are collected from several HEIs, the results should be grouped by HEI.

The list should contain a check box so that the student can deselect the courses he/she does not wish to transfer.

Response

The generated XML document includes the list of all chosen results, as well as personal information about the student (first name(s), family name(s), birthday, gender...). It must also include a signature generated using the XML-DSig standard, containing the certificate paired to the private key used to generate the signature, to make it possible to verify it again at a later point. Note: Java supports natively only usage of private keys in PKCS#8 format.

The response is sent as HTTP POST and has two parameters - the sessionId received earlier by the requester, and the elmo XML (first compressed with gzip, then Base64-encoded). Note that the form must be of the default type, not "multipart/form-data".

NCP Response, example in an HTML form

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

  • NCP_OK: Everything went well, results have been transferred
  • NCP_ERROR: Something went wrong, please give a detailed textual message in this case if the client wants to show it to the user
  • NCP_NO_RESULTS: There were no results to import into the client 
  • NCP_CANCEL: The user has cancelled

Note: no elmo document should be delivered unless NCP_OK is returned.

Logging - for field trial

As part of the field trial, each NCP must provide a common log, which includes some data (no personal information) about the use of the NCP.

We suggest logging to a tab separated file, with one row for each HEI the student have results from. So one session for one student can generate one or more rows in this log. The first five variables will be identical within the same session.

The log should contain the following information

VariableDescriptionExample
SessionidSessionid from the SMP. (If we at a point want to do the same kind of logging in the SMP, with the sessionid it should be possible to join these logs)jkljsd8890sa256
SessiondateDate/time (UTC) for when the application get the request from SMP (before logging in)2015-11-15 12:32
NCP MinutesNumber of minutes spent in the NCP3.2
Return URLReturn URL to the SMP (EMREX client). This is the only information we have about the system retrieving data from NCP. It should at least give country for SMPstudweb.fi/xxx
Country codeCountry for the NCPNO
SuccessSuccessful return of ELMO document to SMP (yes/no)yes
HEI idSCHAC ID (the primary domain name) of the HEI which has delivered the datauio.no
Courses importedNumber of courses imported from HEI5
Credits importedNumber of credits imported from HEI37.5
Courses exportedNumber of courses exported to SMP3
Credits exportedNumber of credits exported to SMP22.5

For a session retrieving data from two HEIs, the log could look like this:

jkljsd8890sa256<tab>2015-11-15 12:32<tab>3.2<tab>studweb.sf/xxx<tab>no<tab>uio.no<tab>5<tab>37.5<tab>3<tab>22.5

jkljsd8890sa256<tab>2015-11-15 12:32<tab>3.2<tab>studweb.sf/xxx<tab>no<tab>uib.no<tab>2<tab>20<tab>0<tab>0

 

  • No labels

5 Comments

  1. Some length limitations on sessionId and returnUrl would be useful!

  2. It is hard to limit the returnUrl as it depends a lot on the implementation. It seems that ~2000 characters is the general recommended limit, so we can go for it.

    As to session IDs, JSESSIONID is 32 characters (not sure if anyone has longer IDs), and someone might want do use it. Should we say 32?

  3. Okay, 2000 and 32 then. I just needed some values to put inside my varchar() definitions.

  4. http://i.imgur.com/D3lQfSP.png - Some questions regarding logging:

    • "Sessiondate" is supposed to be the time when the user signed in, not when the request was received. So it can be empty (if NCP has received the request, but the user has never signed in). Is it correct?
    • What about the time zone of the "Sessiondate" timestamp? Does it matter?
    • Should "NCP Minutes" also be counted from the moment the user signed in?
    1. I've changed the description of the sessiondate to "Date/time (UTC) for when the application get the request from SMP (before logging in)". Using UTC, we will avoid the problems with timezones. I also suggest we set time before logging in.