Overview

This document describes how integration between Unitu and the University Student Record System works. 

Features

Automated generic sync

Sync runs automatically every time new data snapshot sent by the University in asyncronous mode and usually takes few minutes to complete.

Sync is controlled by Unitu and can be enabled/disabled or set to dry-run mode by contacting Unitu Support Team / Customer Success Manager.

Student accounts provisioning

Student accounts are automatically provisioned for enrolled courses. For each record in the dataset, accounts are created automatically if their course is enrolled on Unitu by the Customer Success Manager.

If students are enrolled into multiple courses, we expect the record to be duplicated for each course.

Student account information updates (first and last names, year)

On every sync we check if students’ details are updated and reflect changes on Unitu. Currently, we automatically update the following fields: first name, last name and year.

Disabling accounts for university leavers

On every sync we disable all accounts which are enabled on Unitu but not included in the latest data snapshot from the University. Account holders will be automatically logged out and won’t be able to login until their account is re-enabled.

Re-enabling accounts for university leavers

On every sync we re-enable accounts which are disabled on Unitu but appeared in the latest data snapshot from the university.

Enrolling/un-enrolling students to/from courses

On every sync we automatically add and remove students to/from courses which are enrolled on Unitu. If a student’s course changed in the latest data snapshot, we will remove them from the old course and add them to the new one automatically.

Identifying new and old courses

On every sync we automatically identify new courses which appear in the latest data snapshot and old courses which are excluded from it. There are no actions performed as a result, except highlighting it in a report which is available to Customer Success Managers to take further actions and discuss with the university about any board structure changes.

Automated student email updates if university ID is provided

A student record in the university can change including an email address which is used by Unitu as a primary account identifier. When university ID is provided in the data snapshot and matches an existing record, we can update student email addresses automatically. This will allow students to change their university email address without creating a new Unitu account and losing access to all the content they produced on Unitu.

Changes on Unitu side:

• A new composite key in the Users table. {UniversityId, UniversityGUID (nullable, for backwards compatibility)}
• What do we use in Unitu as a unique identifier? We still use Email as a unique identifier for all Unitu users.
• Ensure Email is a key in the Users table.
• Remove Username field from the Users table where possible. If not, we will discuss alternatives.
• When university email is changed and a record found with the same UniversityGUID:
  • We update email address based on the new details provided.
  • We make it as a confirmed email as we trust data provided by the university.
    
    

Proposed updates & improvements (to be implemented):

Automated courses provisioning from known departments

When we identify a new course and department is enrolled on Unitu, we would like to automatically create it and enroll all students to it, without additional interaction with the university. However, when a new course appears in the data snapshot and there is no matching department, we will include it into the report for Customer Success Managers to take further actions.

Automated course archiving if no students enrolled in it

Courses with no students can be automatically archived for housekeeping purpose.

Whitelist departments and courses to sync using regex pattern

The idea is to configure departments and courses to sync based on a regex pattern. This will allow us to enable and disable sync for different departments and courses dynamically. To implement it, we will need an ability to run sync in a ‘dry-run’ mode from the admin panel.

How to send data to our servers

HTTP Post Request

1. Prepare an HTTP POST request
   1. Header:
      • API Key: <will be provided by us>
      • Cache Control: ‘no-cache’
      • Content Type: ‘application/json’
   2. Body
      • Data: {JSON list (format given below)}
2. Send the above request to the url: “https://api.unitu.co.uk/v1/sync”
   
   

HTTP Post Data schema for JSON list

Please have the data in the following format:

{
"data" : {
   "students" : 
     [
      {...}, {...},
      {
          "faculty" : "<faculty>",
 
          "department" : "<department>",
 
          "course" : "<course>",
 
          "firstName" : "<first name>",
 
          "lastName" : "<last name>",
 
          "email": "<email>",
 
          "id" : "<student unique identifier>", // Optional field. You may supply userID from the student record system or 'cn' field from an Active Directory. This field should be unique for every student within the University.
 
          "year" : <year> // Please note this field type is a nullable number with possible values (null, 0-7) and doesn't need quotes around it.
 
      },
      {...}, {...}
     ]
 }
}

An Example of a Post Request:

curl -X POST \
 https://api.unitu.co.uk/v1/sync \
 -H 'API_KEY: {your API KEY}' \
 -H 'Cache-Control: no-cache' \
 -H 'Content-Type: application/json' \
 -d '{ 
   "data" : {
   "students":[
       {
           "faculty" : "Engineering",
           "department" : "Mechanical Engineering",
           "course" : "Car Maintenance",
           "firstName" : "John",
           "lastName" : "Smith",
           "email": "john.smith@university.ac.uk",
           "id": "josm19",
           "year" : 1
       },
       {
           "faculty" : "Faculty of Development & Society",
           "department" : "Department of Sociology",
           "course" : "Social Sciences",
           "firstName" : "Joe",
           "lastName" : "Doe",
           "email": "joe.doe@university.ac.uk",
           "id": "jodo22",
           "year" : 3
       }
   ]
 }
}'