/roster-hub

RosterHub: Roster Management System based on IMS OneRoster specification

Primary LanguageRubyGNU Affero General Public License v3.0AGPL-3.0

RosterHub

About

RosterHub is an open-source roster management system for mainly educational institutions. The goal of RosterHub is to support interoperating the educational systems effectively by utilizing the learning information of SIS (Student Information System). Main features are followings.

  • CSV to REST API converter for learning information based on IMS OneRoster v1.1 standard
  • Roster management function for educational apps by original REST API

For more information, see the links in the References.

NOTICE: RosterHub is currently under development status.

Setting

  • Configure some constants.
[config/initializers/constants.rb]  
APIDOC = 'doc/apidoc.json'.freeze
CSV_BACKUP_DIR = 'backup'.freeze
CSV_FILE_PATH = 'storage/csv'.freeze
CSV_IMPORT_LOG = 'log/csv_import.log'.freeze
CSV_ZIP_FILE = 'oneroster.zip'.freeze
LIMIT = 100
OFFSET = 0
VERSION_OF_MANIFEST = '1.0'.freeze
VERSION_OF_ONEROSTER = '1.1'.freeze
ROSTER_FILES = %w[academicSessions categories demographics orgs resources courses users classes courseResources classResources enrollments lineItems results].freeze
METADATA = {}.freeze
ZIP_MODE = true
INCLUDE_CLASSES = %w[].freeze
EXCLUDE_CLASSES = %w[].freeze
  • To disable basic authorization for access tokens, it is needed to configure doorkeeper's access_token_methods.
[config/initializers/doorkeeper.rb]
Doorkeeper.configure do
    access_token_methods :from_bearer_authorization
end

Install

$ bundle install  
$ EDITOR="vi" bin/rails credentials:edit
$ rails db:migrate

Test

$ rails spec

Import OneRoster data from CSV files

  1. copy the zip file or csv files in the CSV_FILE_PATH. Sample oneroster.zip files exist in [storage/sample_csv/].

  2. execute importing csv files to the database.

  • execute now
$ rails console  
> CsvImportJob.perform_now
  • using cron jobs
  1. write schedule in [config/schedule.rb].
    (example) "everyday at 4:33 am"
every 1.day, at: ['4:33 am'] do
  runner 'CsvImportJob.perform_now'
end
  1. set cron job.
$ bundle exec whenever -i
$ crontab -l

(*) bin/rails requires execute permissions.

Start RosterHub server

$ rails s

Get data with API

  1. Register your app with uid and secret.
    'uid' and 'secret' are important.
> app = Doorkeeper::Application.new name: 'applicationname',redirect_uri: 'http://xxxxx/', uid: '[uid]',secret: '[secret]'
> app.save

To allow only specific ip address, add permit_ips.

> app = Doorkeeper::Application.new name: 'applicationname',redirect_uri: 'http://xxxxx/', uid: '[uid]',secret: '[secret]', permit_ips: 'ip1,ip2,...'
  • permit_ips : Forward matching. e.g. ['127.0.0.1', '192.168.']
  1. Request access token with uid and secret.
$  curl -i http[s]://[servername][:port]/oauth/token -F grant_type="client_credentials" -F scope="[scope]" -F client_id="[uid]" -F client_secret="[secret]"  
{"access_token":"[accesstoken]","token_type":"bearer","expires_in":nil,"created_at":1510711311}
  • scope : See config/initializers/doorkeeper.rb. If the scope value is not specified, the value of "default_scopes" will be applied.
  1. Call API with access token.
$ curl -H "Authorization: Bearer [accesstoken]" -i http[s]://[servername][:port]/ims/oneroster/v1p1/[endpoint]?[parameters]

For some resources, original endpoints with POST/PUT/DELETE methods are experimentally implemented.

$ curl -H "Authorization: Bearer [accesstoken]" -H "Content-Type:application/json" -i http[s]://[servername][:port]/ims/oneroster/v1p1/[endpoint] -X POST -d '{"[resourcename]": {...}}'

OneRoster 1.1 endpoints

Already implemented to RosterHub

Endpoint HTTP Verb Action
/academicSessions GET Return collection of all academic sessions.
/academicSessions/{id} GET Return specific academic session.
/classes GET Return collection of classes.
/classes/{id} GET Return specific class.
/courses GET Return collection of courses.
/courses/{id} GET Return specific course.
/enrollments GET Return collection of all enrollments.
/enrollments/{id} GET Return specific enrollment.
/orgs GET Return collection of orgs.
/orgs/{id} GET Return specific org.
/schools GET Return collection of schools. A school is an instance of an org.
/schools/{id} GET Return specific school. A school is an instance of an org.
/students GET Return collection of students. A student is an instance of a user.
/students/{id} GET Return specific student. A student is an instance of a user.
/teachers GET Return collection of teachers. A teacher is an instance of a user.
/teachers/{id} GET Return specific teacher.
/terms GET Return collection of terms. A term is an instance of an academic session.
/terms/{id} GET Return specific term.
/users GET Return collection of users
/users/{id} GET Return specific user
/schools/{id}/courses GET Return the collection of courses taught by this school.
/schools/{school_id}/classes/{class_id}/enrollments GET Return the collection of all enrollments into this class.
/schools/{school_id}/classes/{class_id}/students GET Return the collection of students taking this class in this school.
/schools/{school_id}/classes/{class_id}/teachers GET Return the collection of teachers taking this class in this school.
/schools/{school_id}/enrollments GET Return the collection of all enrollments for this school.
/schools/{school_id}/students GET Return the collection of students attending this school.
/schools/{school_id}/teachers GET Return the collection of teachers teaching at this school.
/schools/{school_id}/terms GET Return the collection of terms that are used by this school.
/terms/{term_id}/classes GET Return the collection of classes that are taught in this term.
/courses/{course_id}/classes GET Return the collection of classes that are teaching this course.
/students/{student_id}/classes GET Return the collection of classes that this student is taking.
/teachers/{teacher_id}/classes GET Return the collection of classes that this teacher is teaching.
/schools/{school_id}/classes GET Return the collection of classes taught by this school.
/users/{user_id}/classes GET Return the collection of classes attended by this user.
/classes/{class_id}/students GET Return the collection of students that are taking this class.
/classes/{class_id}/teachers GET Return the collection of teachers that are teaching this class.

Not yet implemented to RosterHub

Endpoint HTTP Verb Action
/gradingPeriods GET Return collection of grading periods. A grading period is an instance of an academic session.
/gradingPeriods/{id} GET Return specific grading period. A grading period is an instance of an academic session.
/demographics GET Return collection of demographics.
/demographics/{id} GET Return specific demographics.
/terms/{term_id}/gradingPeriods GET Return the collection of Grading Periods that are part of this term.

RosterHub original endpoints (Experimental)

Endpoint HTTP Verb Action
/academicSessions/ POST Create a new academic session.
/academicSessions/{id} PUT Replace specific academic session.
/academicSessions/{id} DELETE Delete specific academic session.
/classes/ POST Create a new class.
/classes/{id} PUT Replace specific class.
/classes/{id} DELETE Delete specific class.
/courses/ POST Create a new course.
/courses/{id} PUT Replace specific course.
/courses/{id} DELETE Delete specific course.
/enrollments/ POST Create a new enrollment.
/enrollments/{id} PUT Replace specific enrollment.
/enrollments/{id} DELETE Delete specific enrollment.
/orgs/ POST Create a new org.
/orgs/{id} PUT Replace specific org.
/orgs/{id} DELETE Delete specific org.

Parameters

Pagination

  • limit : the number of result to return : The default value for limit is 100.
  • offset : the index of the first record to return.(zero indexed) : The default value for offset is 0.

(ex.) http[s]://[domain]/ims/oneroster/v1p1/students?limit=10&offset=10

Sorting

  • sort=[data_field]
  • orderBy=[asc|desc]

(ex.) http[s]://[domain]/ims/oneroster/v1p1/students?sort=familyName&orderBy=asc

Filtering

  • filter=[data_field][predicate][value] or [data_field][predicate][value][logical][data_field][predicate][value]

Filter queries MUST be URL encoded.
(ex.) http[s]://[domain]/ims/oneroster/v1p1/students?filter=familyName%3D%27jones%27

API document in OpenAPI v2 format

  • To get API document in JSON format, start RosterHub server and access to the following URL.
http[s]://[servername][:port]/api-docs

Remarks

  • Only bulk data is supported (delta data is NOT supported)

  • NOT supported resources: Demographic Data, Line Items, Line Item Categories, Resources, Results

  • Academic Session

    • NOT supported fields: parent, children

  • Class ('Rclass' is used as 'Class' in RosterHub code)

    • NOT supported fields: location, grades, subjects, subjectCodes, periods, resources
    • Only one value is supported: terms

  • Course

    • NOT supported fields: schoolYear, courseCode, grades, subjects, subjectCodes, resources

  • Enrollment

    • NOT supported fields: status, beginDate, endDate

  • Org

    • NOT supported fields: status, identifier, parent, children

  • User

    • NOT supported fields: status, userIds, middleName, identifier, sms, phone, agents, grades, password
    • Only one value is supported: orgs

Database dependency

  • One of MySQL/MariaDB, PostgreSQL (9.5+), and SQLite (3.24.0+) is needed to bulk update data.
  • MySQL/MariaDB is the default DB and code for it is well maintained than others.

References