LUSIAlmaCourseLoader

This gem implements an Alma course loader which reads course data from Lancaster University's LUSI student records system.

Installation

Add this line to your application's Gemfile:

gem 'lusi_alma_course_loader'

And then execute:

$ bundle

Or install it yourself as:

$ gem install lusi_alma_course_loader

Usage

The course loader is a command-line script:

course_loader [-d|--delete]
              [-e|--env=env-file]
              [-f|--filter=filter]...
              [-F]
              [-l|--log-file=log-file]
              [-L|--log-level=debug|error|fatal|info|warn]
              [-o|--out-file=output-file]
              [-p|--password=lusi-password]
              [-r|--rollover]
              [-t|--time-period=time-period]...
              [-u|--user=lusi-username]
-d | --delete

Adds the DELETE operation to the course loader file, causing all entries in the file to be deleted when the file is processed by Alma.

-e env-file | --env=env-file

Specifies a file of environment variable definitions for configuration

-f filter | --filter=filter

Specifies a filter restricting the courses to be exported. See Filter specification strings for the filter syntax. This flag may be repeated to specify multiple filters; a course must pass every filter to be included in the export.

-F

Lists the fields available to filters and exits.

-h | --help

Displays a help page for the command-line interface.

-l log-file | --log-file=log-file

Specifies a file for logging course loader activity

-L log-level | --log-level=log-level

Specifies the logging level: fatal|error|warn|info|debug

-o out-file | --out-file=out-file

Specifies the output course loader file

-p lusi-password | --password=lusi-password

Specifies the password for the LUSI web service. If not specified, the value of the LUSI_API_PASSWORD environment variable is used.

-r | --rollover

Adds the ROLLOVER operation and previous course code/section to the course loader file, triggering Alma's course rollover processing for the specified courses.

-t time-period | --time-period=time-period

Specifies the course time period covered by the export. This flag may be repeated to specify multiple time periods. The exact syntax and meaning of time-period is left to clients of this gem.

-u lusi-username | --user=lusi-username

Specifies the username for the LUSI web service. If not specified, the value of the LUSI_API_USER environment variable is used.

Filter specification strings

The general form of a filter specification string is:

[!][field [op ]]value

where:

  • ! negates the condition
  • field is the name of a defined field extractor,
  • op is one of the following operators:
    • <, <=, ==, !=, >=, > the value of field is less than (etc.) value
    • ~, !~ the value of field matches/does not match the regular expression value
    • in the value of field is a key (if value is a hash) or a value (if value is any other type) in value; equivalent to value.include?(field)
    • keyin the value of field is a key of the value hash; equivalent to value.key?(field)
    • valuein the value of field is a value in the value hash; equivalent to value.value?(field)
  • value is either a JSON string (which must include double-quotes around string literal values and may specify arrays and hashes) or a regular expression delimited by /.

Examples:

# Course code must exactly match CS101
course_code == "CS101"    

# Course code must be one of CS101, CS102 or CS103
course_code in ["CS101", "CS102", "CS103"]

# Year must not be 2015 or 2016
! year in [2015, 2016]

# Course code must begin with CS
course_code ~ /^CS/

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lusi_alma_course_loader. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.