EduXchange.EU Tech docs Edit this page

Technical documentation for eduxchange.eu

A collection of technical documents for enrolment on eduxchange.eu

Technical documentation

Overview
About OOAPI
About the broker
About enrollment
About the enrollment receiver
About openID and MyAcademicID
And more

Overview

This documentation focusses on the enrollment process after orientation of a student and a click on the register button. For more information about the orientation proces, please check the eduxchange profile.

To enable automated enrolment in an alliance, each institutions will play the role of the home institution (sending students out) and the host institution (receiving students). The home institution must have the required OOAPI endpoints available. The host institution will run a component called enrollment receiver for authentication and authorization. The host institution will always be in the lead for communication.

Overview of orientation and enrollment

eduXchange Overview

Zoomed in on enrollment

enrollment Overview

About OOAPI

These endpoints will be protected using oauth tokens.

About the broker

About enrollment

For enrollment to work, an institution has to implement functionality to play two “roles”:

  1. The Host Institution, where you receive incoming enrollment requests. The Host Institution sends several (OOAPI) requests (via the Enrollment Receiver) to the Home Institution of the student to:
    • Get personal information about the student.
    • Let the Home Institution know the students want to enroll at the Host Institution, giving the Home Institution a chance to allow or deny the enrollment.
    • Check whether a student is still “active” at the Home Institution, for example just before the course starts.
    • Inform the Home Institution that the students has cancelled the enrollment.
    • Inform the Home Institution of the result that student achieved when the course has finished.
  2. The Home Institution, who will receive OOAPI requests from the Host Institution and responds to them. In the responses, the Home Institution can inform the Host Institution about decisions regarding the enrollment of the student.

In general, the Host Institution is in charge of the communication and will initiate requests. The Home Institution responds to those request.

Extra notes about the API calls needed for the enrolment flow

GET /persons/me

This call is used to provide the Host institution with the personal information of the student that wants to enrol. Of special note is the activeEnrollment field. This boolean should indicate whether the students is an “active student” at the Home institution. This could mean different things in different countries, but might include checks like: has the student payed their tuition, or does the student have an active enrolment in a bachelor or master programme?

Minimal required attributes for persons

person

Unique person identification

The /persons/me call needs to have a unique person identification to facilitate deduplication.

Within the alliance the personId can be used for this.

{
  "personId": "123e4567-e89b-12d3-a456-426614174000",
  ...
}
Issuer persons

To get the issuer of the /persons/me response one of the otherCodes field could be used. All institutions should use the same codeType, for example schacHome.

{
  "otherCodes": [
    {
      "codeType": "schacHome",
      "code": "dtu.dk"
    }
  ],
  ...
}

POST /associations/external/me

Once the Host institution has done the initial processing after the Enrollment Request starts, the Host should do a POST /associations/external/me request to the Home institution (via the enrollment receiver). The purpose of this call is to provide the Home Institution with enough information to make an informed decision about the enrollment request of the student. Therefore it should include information about:

Minimal required attributes for associations

association

association.offering

association.offering.course

association.issuer

Note: courseCode is missing in the OOAPI spec and should be added there in the future.

state and remoteState

The state and remoteState fields are used to communicate about the enrolment state between the two institutions. Because OOAPI is based on the REST paradigm, it describes resources being manipulated on the server. For the POST /associations/external/me call this has the following consequences:

Issuer associations

To set the issuer of the /associations/external/me request the primaryCode field should be used in the body. All institutions should use the same codeType, for example schacHome.

{
  "issuer": {
    "primaryCode": {
        "codeType": "schacHome",
        "code": "dtu.dk"
    },
    ...
  }
  ...
}

View a full example for the body of this request

PATCH /associations/{associationId}

With this call the Host institution can inform the Home institution about any updates to its associationState. There are several reasons why this is needed:

  1. If the Host institution communicated a pending or queued state to the Home institution during the initial enrolment flow, the Host has to update Home institution when the state progresses to associated or denied.
  2. If the student cancels the enrolment (for example using some out-of-band process, like sending an email to the student administration of the Host institution), the Host should inform the Home by communicating the canceled state.

To update the Home institution, the Host institution should use the remoteState field in the PATCH request.

GET /associations/{associationId}

With this call the Host institution can request the current associationState from the Home institution. This is needed when the Home institution returned a pending state during the initial enrolment flow. The Host institution should then poll the Home institution (for example using a cron job) to check whether the Home institution has reached a new state.

In the response to this call, only required fields are necessary:

About the enrollment receiver

About openID and MyAcademicID

And more

Testing

Status