pupilfirst_xapi 0.1.0

data/README.md

@@ -0,0 +1,74 @@
+# PupilfirstXapi
+
+This gem subscribes to events published by Pupilfirst LMS system,
+builds the XAPI statements and sends them to LRS endpoint defined
+using ENV variables. The list of handled Pupilfirst's events is
+defined [here](/lib/pupilfirst_xapi/statements.rb).
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pupilfirst_xapi'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install pupilfirst_xapi
+```
+
+## Usage
+Add application initializer file and setup dependencies required by this gem:
+
+### Define Pupilfirst models repository
+Add this line in gem initializer:
+```
+PupilfirstXapi.repository = ->(klass, resource_id) { ... }
+```
+
+It could be simple lambda to fetch Pupilfirst's models or
+a class with a `call(klass, repository_id)` method.
+
+Arguments:
+
+* `klass` - a symbol from a list defined below representing one of the entities
+  from Pupilfirst's data model,
+* `resource_id` - an entity id (Application Record id attribute)
+
+
+Entity types that are used by this gem:
+
+* `:course` - Pupilfirst's `Course` class
+* `:target` - Pupilfirst's `Target` class
+* `:user` - Pupilfirst's `User` class
+
+The result of the lambda or repository class call method must be
+an Pupilfirst's ActiveRecord object for requested class.
+
+### Define URI builder
+Add this line in gem initializer:
+```
+PupilfirstXapi.uri_for = ->(obj) { ... }
+```
+
+Arguments:
+
+* `obj` - an Pupilfirst's ActiveRecord object
+
+The result of the `PupilfirstXapi.uri_for.(obj)` call must be
+the unique URI of the object passed as argument.
+
+### Define LRS endpoint
+Set environment variables:
+
+* `LRS_ENDPOINT` - url of LRS server's XAPI endpoint
+* `LRS_KEY` - authentication key
+* `LRS_SECRET` - authentication secter
+
+## License
+The gem is available as open source under the terms of the [GNU GPLv3 License](https://opensource.org/licenses/GPL-3.0).

data/Rakefile

@@ -0,0 +1,25 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PupilfirstXapi'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/pupilfirst_xapi.rb

@@ -0,0 +1,20 @@
+require "action_controller/railtie"
+require "active_job/railtie"
+require "growthtribe_xapi"
+require "pupilfirst_xapi/version"
+require "pupilfirst_xapi/outbox"
+require "pupilfirst_xapi/actors"
+require "pupilfirst_xapi/objects"
+require "pupilfirst_xapi/verbs"
+require "pupilfirst_xapi/statements"
+
+module PupilfirstXapi
+  mattr_accessor :uri_for
+  mattr_accessor :repository
+
+  Statements.subscribe do |event_type|
+    ActiveSupport::Notifications.subscribe("#{event_type}.pupilfirst") do |_name, _start, finish, _id, payload|
+      Outbox << payload.merge(event_type: event_type, timestamp: finish)
+    end
+  end
+end

data/lib/pupilfirst_xapi/actors.rb

@@ -0,0 +1,7 @@
+module PupilfirstXapi
+  module Actors
+    def self.agent(actor)
+      Xapi.create_agent(agent_type: 'Agent', email: actor.email, name: actor.name)
+    end
+  end
+end

data/lib/pupilfirst_xapi/objects.rb

@@ -0,0 +1,15 @@
+require_relative 'objects/builder'
+require_relative 'objects/course'
+require_relative 'objects/target'
+
+module PupilfirstXapi
+  module Objects
+    def self.course(course, uri)
+      Course.new.call(course, uri)
+    end
+
+    def self.target(target, uri)
+      Target.new.call(target, uri)
+    end
+  end
+end

data/lib/pupilfirst_xapi/objects/builder.rb

@@ -0,0 +1,24 @@
+module PupilfirstXapi
+  module Objects
+    class Builder
+      def initialize(id:, name:, description:, type:)
+        @params = {
+          id: id,
+          name: name,
+          description: description,
+          type: type
+        }
+      end
+
+      def with_extension(type, value)
+        @params[:extensions] ||= {}
+        @params[:extensions].merge!({type => value})
+        self
+      end
+
+      def call
+        Xapi.create_activity(@params)
+      end
+    end
+  end
+end

data/lib/pupilfirst_xapi/objects/course.rb

@@ -0,0 +1,19 @@
+module PupilfirstXapi
+  module Objects
+    class Course
+      def call(course, uri)
+        Builder.new(
+          id: uri,
+          type: 'http://adlnet.gov/expapi/activities/product',
+          name: course.name,
+          description: course.description
+        ).tap do |obj|
+          if course.ends_at.present?
+            duration = ActiveSupport::Duration.build(course.ends_at - course.created_at).iso8601
+            obj.with_extension("http://id.tincanapi.com/extension/planned-duration", duration)
+          end
+        end.call
+      end
+    end
+  end
+end

data/lib/pupilfirst_xapi/objects/target.rb

@@ -0,0 +1,14 @@
+module PupilfirstXapi
+  module Objects
+    class Target
+      def call(target, uri)
+        Builder.new(
+          id: uri,
+          type: "http://activitystrea.ms/schema/1.0/task",
+          name: target.title,
+          description: target.description
+        ).call
+      end
+    end
+  end
+end

data/lib/pupilfirst_xapi/outbox.rb

@@ -0,0 +1,66 @@
+require "active_job"
+require 'xapi'
+
+module PupilfirstXapi
+  class Outbox
+    class Job < ActiveJob::Base
+      queue_as :default
+
+      def perform(payload)
+        outbox.call(**payload)
+      end
+
+      private
+
+      def outbox
+        Outbox.new(
+          lrs: remote_lrs,
+          repository: PupilfirstXapi.repository,
+          uri_for: PupilfirstXapi.uri_for
+        )
+      end
+
+      def remote_lrs
+        Xapi.create_remote_lrs(
+          end_point: ENV['LRS_ENDPOINT'],
+          user_name: ENV['LRS_KEY'],
+          password: ENV['LRS_SECRET']
+        )
+      end
+    end
+
+    class << self
+      def <<(payload)
+        Outbox::Job.perform_later(payload)
+      end
+    end
+
+    def initialize(lrs:, repository:, uri_for:)
+      @lrs = lrs
+      @repository = repository
+      @uri_for = uri_for
+    end
+
+    def call(**payload)
+      statement = statement_for(**payload)
+      Xapi.post_statement(remote_lrs: @lrs, statement: statement) if statement
+    end
+
+    private
+    attr_reader :lrs, :repository, :uri_for
+
+    def statement_for(event_type:, timestamp:, **args)
+      builder_for(event_type).call(**statement_args(**args)).tap do |statement|
+        statement&.stamp(id: nil, timestamp: timestamp)
+      end
+    end
+
+    def statement_args(**args)
+      args.slice(:actor_id, :resource_id)
+    end
+
+    def builder_for(event_type)
+      Statements.builder_for(event_type).new(repository, uri_for)
+    end
+  end
+end

data/lib/pupilfirst_xapi/statements.rb

@@ -0,0 +1,22 @@
+require "pupilfirst_xapi/statements/course_completed"
+require "pupilfirst_xapi/statements/course_registered"
+require "pupilfirst_xapi/statements/target_completed"
+
+module PupilfirstXapi
+  module Statements
+    def self.subscribe(&block)
+      EVENTS.each_key{|key| block.call(key)}
+    end
+
+    def self.builder_for(event)
+      EVENTS.fetch(event)
+    end
+
+    EVENTS = {
+      :course_completed                   => CourseCompleted,
+      :student_added                      => CourseRegistered,
+      :submission_graded                  => TargetCompleted,
+      :submission_automatically_verified  => TargetCompleted,
+    }
+  end
+end

data/lib/pupilfirst_xapi/statements/course_completed.rb

@@ -0,0 +1,21 @@
+module PupilfirstXapi
+  module Statements
+    class CourseCompleted
+      def initialize(repository, uri_for)
+        @repository = repository
+        @uri_for = uri_for
+      end
+
+      def call(actor_id:, resource_id:)
+        actor = @repository.call(:user, actor_id)
+        course = @repository.call(:course, resource_id)
+
+        Xapi.create_statement(
+          actor: Actors.agent(actor),
+          verb: Verbs::COMPLETED,
+          object: Objects.course(course, @uri_for.call(course))
+        )
+      end
+    end
+  end
+end

data/lib/pupilfirst_xapi/statements/course_registered.rb

@@ -0,0 +1,21 @@
+module PupilfirstXapi
+  module Statements
+    class CourseRegistered
+      def initialize(repository, uri_for)
+        @repository = repository
+        @uri_for = uri_for
+      end
+
+      def call(actor_id:, resource_id:)
+        actor = @repository.call(:user, actor_id)
+        course = @repository.call(:course, resource_id)
+
+        Xapi.create_statement(
+          actor: Actors.agent(actor),
+          verb: Verbs::REGISTERED,
+          object: Objects.course(course, @uri_for.call(course))
+        )
+      end
+    end
+  end
+end

data/lib/pupilfirst_xapi/statements/target_completed.rb

@@ -0,0 +1,24 @@
+module PupilfirstXapi
+  module Statements
+    class TargetCompleted
+      def initialize(repository, uri_for)
+        @repository = repository
+        @uri_for = uri_for
+      end
+
+      def call(actor_id:, resource_id:)
+        submission = @repository.call(:timeline_event, resource_id)
+        return unless submission.passed?
+
+        actor = @repository.call(:user, actor_id)
+        target = submission.target
+
+        Xapi.create_statement(
+          actor: Actors.agent(actor),
+          verb: Verbs::COMPLETED_ASSIGNMENT,
+          object: Objects.target(target, @uri_for.call(target))
+        )
+      end
+    end
+  end
+end

data/lib/pupilfirst_xapi/verbs.rb

@@ -0,0 +1,7 @@
+module PupilfirstXapi
+  module Verbs
+    COMPLETED             = Xapi.create_verb(id: 'http://adlnet.gov/expapi/verbs/completed', name: 'completed')
+    COMPLETED_ASSIGNMENT  = Xapi.create_verb(id: 'https://w3id.org/xapi/dod-isd/verbs/completed-assignment', name: 'completed assignment')
+    REGISTERED            = Xapi.create_verb(id: 'http://adlnet.gov/expapi/verbs/registered', name: 'registered')
+  end
+end

data/lib/pupilfirst_xapi/version.rb

@@ -0,0 +1,3 @@
+module PupilfirstXapi
+  VERSION = '0.1.0'
+end

data/spec/integration_spec.rb

@@ -0,0 +1,111 @@
+require 'rails_helper'
+
+RSpec.describe "#xapi", type: :job, perform_jobs: true do
+  let(:john) {
+    double(:john,
+           id: 123,
+           name: 'John Doe',
+           email: 'john@example.com',
+           uri: '/user/123')
+  }
+  let(:ror_guides) {
+    double(:course,
+           id: 1234,
+           name: 'Ruby on Rails Guides',
+           description: 'These guides are designed to make you immediately productive with Rails',
+           created_at: Time.new(2021,01,01),
+           ends_at: nil,
+           uri: 'https://guides.rubyonrails.org/')
+  }
+  let(:getting_started) {
+    double(:target,
+           title: 'Getting Started with Rails',
+           description: 'This guide covers getting up and running with Ruby on Rails.',
+           uri: 'https://guides.rubyonrails.org/getting_started.html')
+  }
+  let(:good_one) { double(:timeline_event, target: getting_started, passed?: true) }
+  let(:bad_one) { double(:timeline_event, target: getting_started, passed?: false) }
+
+
+  let(:models) {
+    {
+      :user => {
+        123 => john,
+      },
+      :course => {
+        1234 => ror_guides,
+      },
+      :timeline_event => {
+        1 => good_one,
+        2 => bad_one,
+      }
+    }
+  }
+  let(:repository) { ->(klass, resource_id) { models.dig(klass, resource_id) } }
+  let(:uri_for)    { ->(obj) { obj.uri } }
+
+  before do
+    PupilfirstXapi.repository = repository
+    PupilfirstXapi.uri_for = uri_for
+  end
+
+  def xapi_actor(user)
+    {
+      objectType: 'Agent',
+      name: user.name,
+      mbox: "mailto:#{user.email}",
+    }
+  end
+
+  def xapi_verb(verb)
+    {
+      id: verb.id,
+      display: verb.display
+    }
+  end
+
+  it "#works" do
+    timestamp = Time.now
+    xapi_request = {
+      actor: xapi_actor(john),
+      verb: xapi_verb(PupilfirstXapi::Verbs::COMPLETED),
+      object: {
+        id: ror_guides.uri,
+        definition: {
+          name: {'en-US' => 'Ruby on Rails Guides'},
+          description: {'en-US' => 'These guides are designed to make you immediately productive with Rails'},
+          type: 'http://adlnet.gov/expapi/activities/product',
+        },
+      },
+      timestamp: timestamp.iso8601,
+      version: '1.0.1',
+    }
+    request = stub_request(:post, "https://test.lrs/statements")
+      .with(
+        body: xapi_request.to_json,
+        headers: {
+          'Accept'=>'*/*',
+          'Accept-Encoding'=>'gzip;q=1.0,deflate;q=0.6,identity;q=0.3',
+          'Authorization'=>'Basic a2V5OnNlY3JldA==',
+          'Content-Type'=>'application/json',
+          'User-Agent'=>'Faraday v1.3.0',
+          'X-Experience-Api-Version'=>'1.0.1'
+        }
+      ).to_return(status: 204, body: "", headers: {})
+
+    allow(Concurrent).to receive(:monotonic_time).and_return(timestamp)
+
+    ActiveSupport::Notifications.instrument(
+      "course_completed.pupilfirst",
+      resource_id: ror_guides.id,
+      actor_id: john.id,
+    )
+    expect(PupilfirstXapi::Outbox::Job).to have_been_performed.with({
+      event_type: :course_completed,
+      actor_id: 123,
+      resource_id: 1234,
+      timestamp: timestamp,
+    })
+    expect(request).to have_been_requested
+  end
+end