Contents
High-level overview
The FutureLearn-initiated enrolment flow is used to enrol FutureLearn users on degrees and programs that require enrolment as a student at the partner university.
The flow starts with the student or prospective student (the ‘applicant’) clicking a join button on the FutureLearn website. If the applicant is not already signed in to the FutureLearn website, they’re asked to sign in or register before continuing.
The applicant is then shown a page informing them that the degree or program they wish to join is delivered by the partner university. The applicant is asked to consent to FutureLearn sharing data about them with that university, and to the eventual linking of their FutureLearn account with their university ID.
Assuming that the applicant does give their consent, the FutureLearn platform creates a new ‘enrolment request’ record to track the applicant’s progress through the flow. The applicant is then redirected to the university’s online admissions or enrolment portal (the ‘enrolment portal’) with an enrolment request token in the query string.
The enrolment portal uses the FutureLearn partners API to exchange the enrolment request token in the query string with useful information about the applicant and the enrolment request. This might include:
- The applicant’s name and email address
- Any university IDs (for the same partner) already linked to the applicant’s FutureLearn account
- The degree or program the applicant would like to enrol on
This information is used to tailor the admissions and enrolment process so that it is as friction-free as possible for the applicant.
Once the applicant has submitted their enrolment request through the enrolment portal, the portal uses the FutureLearn partners API to notify FutureLearn that the enrolment request has been submitted. In its response, the API provides a URL that the enrolment portal uses to redirect the applicant back to an appropriate page on the FutureLearn website.
From this point forward the applicant sees a placeholder message reflecting their status of their enrolment request in the relevant parts of the FutureLearn application (including the degree or program page they applied from).
Some time after the request has been submitted to the university by the applicant, the university may use the FutureLearn partners API to:
- Decline the enrolment request
- Provisionally accept the enrolment request, giving the applicant access to ‘orientation’ resources but not the course content
- Confirm the enrolment request, enrolling the applicant on the relevant programs in the FutureLearn platform so that they have access to the course content
By the time the enrolment request is confirmed, the university will have used the FutureLearn partners API to confirm the applicant’s university ID and, if necessary, the program runs the applicant needs to be enrolled on in the FutureLearn platform.
Definitions
Entities
| Entity | Description |
|---|---|
| Applicant | A learner or student applying to enrol on a degree or program through the FutureLearn-initiated enrolment flow. |
| Degree | A degree level qualification offered through FutureLearn (e.g. Graduate Certificate or Masters). Made up of programs. |
| Degree enrolment | A learner’s enrolment on a degree in FutureLearn. |
| Learner | A user who takes courses on the FutureLearn platform. |
| Program | A collection of FutureLearn courses. Equivalent to what a university may call a module or unit. |
| Program run | A run (instance or offering) of a program starting on a specific date. |
| Program enrolment | A learner’s enrolment on a program run in FutureLearn. |
| Organisation membership | A record that links a learner to an organisation. |
| Single program enrolment | A program enrolment that is not linked to a degree enrolment (for universities that allow students to enrol on a program without enrolling on a degree). |
| Student | A learner that is enrolled at the university and whose FutureLearn account is linked via an organisation membership to their university ID. |
Identifiers
| Identifiers | Description |
|---|---|
| Degree code |
The alphanumeric code assigned to a degree by the university (e.g. ‘MA01’). No two degrees by the university can have the same degree code. |
| Degree enrolment UUID |
The unique identifier assigned to a degree enrolment by FutureLearn. No two degree enrolments on the FutureLearn platform can have the same degree enrolment UUID. |
| Degree UUID |
The unique identifier assigned to a degree by FutureLearn. No two degrees on the FutureLearn platform can have the same degree UUID. |
| External learner ID | See ‘University ID’. |
| Learner UUID |
The unique identifier assigned to a learner by FutureLearn. No two learners on the FutureLearn platform can have the same learner UUID. |
| Organisation membership UUID |
The unique identifier assigned to an organisation membership by FutureLearn. No two organisation memberships on the FutureLearn platform can have the same organisation membership UUID. |
| Program code |
The alphanumeric code assigned to a program by the university (e.g. ‘MA101’). No two programs by the university can have the same program code. |
| Program enrolment UUID |
The unique identifier assigned to a program enrolment by FutureLearn. No two program enrolments on the FutureLearn platform can have the same program enrolment UUID. |
| Program run code |
The alphanumeric code assigned to a program run by the university (e.g. ‘2017.02’). No two runs of the same program can have the same program run code. |
| Program run UUID |
The unique identifier assigned to a program run by FutureLearn. No two program runs on the FutureLearn platform can have the same program run UUID. |
| Program UUID |
The unique identifier assigned to a program by FutureLearn. No two programs on the FutureLearn platform can have the same program UUID. |
| University ID |
The unique identifier assigned to the student by the university. No two students at the same university can have the same university ID. In the API, the university ID is referred to as the ‘External learner ID’ as it can also refer to an employee ID or similar in other use case. |
In general, the API uses UUID to identify entities. ‘Find’ endpoints are provided to allow consumers to resolve these UUIDs from university assigned codes if necessary.
General principles
- All students have a university ID that can be used to uniquely identify them in exports and API calls.
- University IDs are associated with enrolment requests through organisation memberships (where the university ID is the ‘external learner ID’).
- By the end of the flow the applicant may be enrolled on a different program or degree than they’d selected at the start of the process.
- Once an enrolment request is ‘confirmed’ it can no longer be changed, although access to the programs can still be withdrawn at any time through the ‘deactive program enrolment’ API.
- Prior to an enrolment request being confirmed almost any state transition is permitted. In particular, an enrolment request can be ‘confirmed’ without first being ‘submitted’ or ‘accepted’ and can be declined after it has been ‘accepted’.
- The university is responsible for keeping the applicant informed of the progress of their request. In particular, the university is responsible for notifying applicants when their request has been confirmed or declined.
Enrolment request states
| State | Description | What the applicant sees in FutureLearn |
|---|---|---|
| New | The applicant has clicked the join button in FutureLearn and has consented to their details being shared with the university. The applicant has yet to submit their request to the university. | The join button remains available. If the applicant clicks on it again, they are redirected to the enrolment portal with the same enrolment request token as before. |
| Submitted | The applicant has submitted their enrolment request to the university, which is still processing it. | The join button is replaced with a message describing the status of the enrolment request. |
| Accepted | The university has provisionally accepted the enrolment request. |
The join button is replaced with a message describing the status of the enrolment request. The applicant has access to orientation resources, but not the courses and their content. |
| Confirmed | The university has confirmed the enrolment. |
The join button is hidden. The applicant is enrolled on all the relevant program runs and has access to contents of courses that have started. |
| Cancelled | The applicant has chosen not to proceed with their enrolment request. | The join button remains available. If the applicant clicks on it again, the flow is restarted with a fresh enrolment request record. |
| Declined | The university has declined the enrolment request. | The join button remains available. If the applicant clicks on it again, the flow is restarted with a fresh enrolment request record. |
Scenarios
The FutureLearn-initiated enrolment flow is designed to cover the following scenarios, many of which are covered in greater detail in the Walkthroughs section.
| ID | Description |
| S1 | The applicant would like to enrol on a degree. |
| S2 | The applicant would like to enrol on run of a program (single program enrolment). |
| S3 | The applicant has yet to enrol at the university. |
| S4 | The applicant is already a student at the university. Their university ID is not yet linked to a FutureLearn account. |
| S5 | The applicant is already a student at the university. Their university ID is already linked to the FutureLearn account they’re signed in with. |
| S6 | The applicant, an existing student at the university. Their university ID is already linked to a different FutureLearn account than the one they’re signed in with. |
| S7 | The enrolment request is submitted by the applicant to the university. |
| S8 | The enrolment request is provisionally accepted by the university. |
| S9 | The enrolment request is provisionally accepted by the university, but for a different run of the program than initially specified (applies to single program enrolments only). |
| S10 | The enrolment request is confirmed by the university. |
| S11 | The enrolment request is confirmed by the university, but for a different run of the program than initially specified. |
| S12 | The enrolment request is cancelled by the user before it’s been submitted to the university. |
| S13 | The enrolment request is cancelled by the user after it’s been submitted to the university. |
| S14 | The enrolment request is declined by the university. |
API endpoints
The FutureLearn-initiated enrolment flow utilises a number of endpoints from the FutureLearn partners API.
| ID | Name | Purpose |
|---|---|---|
| EP1 | Exchange enrolment request token | Exchanging enrolment request tokens for enrolment request details |
| EP2 | Get enrolment request | Getting the enrolment request details |
| EP3 | Update enrolment request | Updating enrolment requests (including state transitions) |
| EP4 | Get learner | Getting applicant details |
| EP5 | Get learner’s organisation memberships | Getting any university IDs already linked to applicants’ FutureLearn account |
| EP6 | Get program | Getting program details |
| EP7 | Get program run | Getting program run details |
| EP8 | Create organisation membership | Linking a new university ID to the applicant’s FutureLearn account |
| EP10 | Find organisation membership | Checking for an existing organisation membership with a given university ID |
| EP11 | Create program enrolment | Enrolling a student on their first set of programs after accepting a degree enrolment. |
Sequence diagram
Walkthroughs
In these walkthroughs, https://fl-enrol.example.ac.uk/ represents the university’s enrolment request endpoint and {JWT-Token} represents the bearer token for the request.
Not all of the steps illustrated are mandatory. In particular, many of the calls to the update enrolment request API endpoint can be skipped or combined to match the university’s business processes.
Applicant submits request to enrol on a degree
- The applicant clicks the join button on the FutureLearn degree discipline page.
- If there is more than one degree available within the degree discipline, the applicant picks to degree they wish to enrol on.
- If the applicant is not already signed in, FutureLearn prompts them to sign in or register.
- Unless the applicant has an existing, unsubmitted (i.e. ‘new’) enrolment request, FutureLearn asks the applicant for permission to share data about them with the university.
- Assuming that applicant is happy to proceed, FutureLearn creates a new enrolment request and redirects them to the enrolment portal.
|
HTTP/1.1 302 Found Location: https://fl-enrol.example.ac.uk/?token=e5m2qh8yt1gq0duyjz0pd2131lvabs1 |
6. The enrolment portal uses the exchange enrolment request token API endpoint to exchange the token in the query string with basic information about the request.
|
Request |
|
Response HTTP/1.1 200 OK |
7. The enrolment portal can follow the links in the response to get more information about the applicant and degree.
|
Request GET https://api.futurelearn.com/partners/learners/b2c0b8d8-b274-4f71-ba8f-2a484c42ad1e |
|
Response HTTP/1.1 200 OK "first_name": "Susannah", "links": { |
|
Request GET https://api.futurelearn.com/partners/learners/b2c0b…/organisation_memberships |
|
Response Example 1: The applicant’s FutureLearn account has yet to be linked to a university ID:
HTTP/1.1 200 OK
Example 2: The applicant’s FutureLearn account is linked to a single university ID (‘12345678’):
HTTP/1.1 200 OK "external_learner_id": "12345678" |
|
Request GET https://api.futurelearn.com/partners/degrees/0c757f62-7719-461f-9901-34e31ec866db |
|
Response HTTP/1.1 200 OK |
8. The enrolment portal uses the data it’s retrieved from the API to display the appropriate form to the applicant.
9. When the applicant submits the completed the form, the enrolment portal uses the update enrolment request API endpoint to transition the request to the ‘submitted’ state.
|
Request Example 1: Marking the degree enrolment request as submitted
Example 2: Marking the degree enrolment request as submitted with a custom message "status_message": "The University has received your application" |
|
Response HTTP/1.1 200 OK |
10. The enrolment stores the enrolment request UUID in the university’s internal systems so that it can be used to identify the enrolment request in future calls to the API.
11. The enrolment portal redirects the applicant back to the FutureLearn website via the return URL specified in the response from the update enrolment request API endpoint.
|
HTTP/1.1 302 Found |
Applicant submits request to enrol on a program run
12. The applicant clicks the join button on the FutureLearn program page.
13. If the applicant is not already signed in, FutureLearn prompts them to sign in or register.
14. Unless the applicant has an existing, unsubmitted (i.e. ‘new’) enrolment request, FutureLearn asks the applicant for permission to share data about them with the university.
15. Assuming that applicant is happy to proceed, FutureLearn creates a new enrolment request and redirects them to the enrolment portal.
|
HTTP/1.1 302 Found |
16. The enrolment portal uses the exchange enrolment request token API endpoint to exchange the token in the query string with basic information about the request.
|
Request POST https://api.futurelearn.com/partners/enrolment_requests/token_exchange |
|
Response HTTP/1.1 200 OK |
17. The enrolment portal can follow the links in the response to get more information about the applicant and program run.
|
Request GET https://api.futurelearn.com/partners/learners/b2c0b8d8-b274-4f71-ba8f-2a484c42ad1e |
|
Response HTTP/1.1 200 OK "first_name": "Susannah", "links": { |
|
Request GET https://api.futurelearn.com/partners/learners/b2c0b…/organisation_memberships |
|
Response Example 1: The applicant’s FutureLearn account has yet to be linked to a university ID:
HTTP/1.1 200 OK
Example 2: The applicant’s FutureLearn account is linked to a single university ID (‘12345678’):
HTTP/1.1 200 OK "external_learner_id": "12345678" |
|
Request GET https://api.futurelearn.com/partners/program_runs/26875b20-fe07-4781-bfc3-01960b849fde |
|
Response HTTP/1.1 200 OK "start_date": "2017-03-06" |
18. The enrolment portal uses the data it’s retrieved from the API to display the appropriate form to the applicant.
19. When the applicant submits the completed the form, the enrolment portal uses the update enrolment request API endpoint to transition the request to the ‘submitted’ state.
|
Request Example 1: Marking the program enrolment request as submitted
Example 2: Marking the program enrolment request as submitted with an optional status message "status_message": "The University has received your application" |
|
Response HTTP/1.1 200 OK |
20. The enrolment stores the enrolment request UUID in the university’s internal systems so that it can be used to identify the enrolment request in future calls to the API.
21. The enrolment portal redirects the applicant back to the FutureLearn website via the return URL specified in the response from the update enrolment request API endpoint.
|
HTTP/1.1 302 Found |
University provisionally accepts an enrolment request
In some cases the university may wish to provisionally accept an enrolment request so that the applicant has access to orientation resources while university services are still being provisioned.
- The university uses the update enrolment request API endpoint to transition the request to the ‘accepted’ state.
|
Request Assuming ‘12345678’ is the university ID (external learner ID) |
|
Response Example 1: No organisation membership exists with the specified university ID
HTTP/1.1 404 Not Found
Example 2: A matching organisation membership is found
HTTP/1.1 302 Found |
2. If no matching organisation membership is found, the university uses the create organisation membership API endpoint to instruct FutureLearn to create a new organisation membership for the learner associated with the enrolment request.
|
Request Assuming ‘12345678’ is the university ID (external learner ID). Authorization: Bearer {JWT-token}
{ "external_learner_id": "12345678", } |
|
Response
HTTP/1.1 201 Created "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…", "external_learner_id": "12345678" |
3. The university uses the update enrolment request API endpoint to associate the enrolment request with the organisation membership associated with the university ID.
|
Request PATCH https://api.futurelearn.com/partners/enrolment_requests/3b3b75ea-d60d-4889-bf4a-a53c0952c218 "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d" } |
|
Response HTTP/1.1 200 OK "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d", }, |
4. The FutureLearn platform links the specified organisation membership to the learner that made the enrolment request. If the organisation membership is already linked to a learner, the FutureLearn platform checks that the learner associated with the organisation membership is the same as the learner that made the enrolment request. If there is a mismatch an error is returned, otherwise the organisation membership is assigned to the enrolment request.
University confirms a request to enrol on a degree
- The university uses the update enrolment request API endpoint to transition the request to the ‘confirmed’ state.
|
Request Example 1: Marking the degree enrolment request as confirmed
Example 2: Marking the degree enrolment request as confirmed with an optional status message "status_message": "The University has confirmed your application" |
|
Response HTTP/1.1 200 OK "organisation_membership": { "degree_enrolment": { "status_message": "The University has confirmed your application" |
2. The FutureLearn platform creates or re-activates the student’s degree enrolment and associates it with the organisation membership assigned to the request.
3. The university uses the create program enrolment API endpoint to enrol the student on their first set of program runs. The organisation membership UUID and degree enrolment UUID required to make create the linked program enrolments are included in the response from the update enrolment request API endpoint. The program run UUIDs can be looked up using the find program run API endpoint. This is covered in more detail in the University-initiated enrolment flow documentation.
University declines an enrolment request
- The university uses the update enrolment request API endpoint to transition the request to the ‘declined’ state.
|
Request Example 1: Marking the enrolment request as declined
Example 2: Marking the enrolment request as declined with an optional status message "status_message": "The University has declined your application" |
|
Response HTTP/1.1 200 OK |
2. The university notifies the learner (most likely by email) that their enrolment request has been declined.
Applicant cancels an enrolment request
There are a number of situations where an enrolment request might be considered ‘cancelled’ by the applicant:
- The applicant has explicitly requested to cancel the request through a feature in the enrolment portal, or by contacting the university via some other channel.
- The applicant has failed to complete additional enrolment steps (e.g. payment) in time.
Currently only the university is able to transition an enrolment request to the cancelled state as there no mechanism in place for the FutureLearn platform to inform the university that an enrolment request has been cancelled.
- The university uses the update enrolment request API endpoint to transition the request to the ‘cancelled’ state.
|
Request Example 1: Marking the enrolment request as cancelled
Example 2: Marking the enrolment request as cancelled with an optional status message "status_message": "The University has cancelled your application" |
|
Response HTTP/1.1 200 OK |
2. If the applicant cancelled the request through a web interface, the return URL in the response from the update enrolment request API endpoint can optionally be used as a link back to an appropriate page on the FutureLearn website.
Update program enrolment
This method can be used to update an existing program enrolment to link it to a degree enrolment, in the case where a program enrolment has been created first.
If the program enrolment UUID is unknown, it can be looked up using the find program enrolment method.
HTTP request
| Method |
Path |
|
PATCH |
partners/program_enrolments/{program-enrolment-uuid} |
Example
|
Request Authorization: Bearer {JWT-token} { "degree_enrolment": { "uuid": "26875b20-fe07-4781-bfc3-01960b849fde" } } |
|
Response
HTTP/1.1 303 See Other |
Authorisation
Only program enrolments where the program belongs to the university, and the learner has an organisation membership record linking them to the university can be updated using this method. Program enrolments can only be linked to degree enrolments in the case that neither enrolment is deferred, and the program belongs to the degree.
Future plans
Re-enrolment
We anticipate that the same flow will be used to allow students to enrol on their next set of programs starting from the FutureLearn interface. In those cases the enrolment request may specify more than one program run, and the enrolment portal may ask the student to do little more than confirm their selection and pay.
Open issues
| ID |
Description |
| IS1 | In scenario S6, should the FutureLearn API return an error response or automatically reassign the enrolment request to the FutureLearn account already linked to the university ID? |
Document control
|
Rev |
Date |
Author |
Changes |
|
0.1 |
22/05/2017 | S.F. | Initial draft to cover phase 2 requirements. You can find the document this replaces in the attachments section below. |
|
1.0 |
13/09/2017 | S.F. | Updated to reflect changes during implementation. Added glossary and sequence diagram. |
|
1.1 |
09/10/2017 | S.F. | Added scenarios and walkthroughs for degree enrolments. |
|
1.2 |
22/11/2017 | S.F. | Removed learner parameter from create organisation membership endpoint; learner is now associated with the organisation membership automatically when the organisation membership is added to the enrolment request. |
|
1.3 |
08/12/2017 | S.F. | Remove `learner` attribute from program enrolment entity; `organisation_membership` should be used instead. |
|
1.4
|
24/05/18 |
V.G. |
Added examples for PATCH endpoint to update a program enrolment to link it to a degree enrolment |
Comments
0 comments
Please sign in to leave a comment.