ims-lti 1.0

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2012 Instructure
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# IMS LTI
+
+This ruby library is to help create Tool Providers and Tool Consumers for the
+[IMS LTI standard](http://www.imsglobal.org/lti/index.html).
+
+## Installation
+This is packaged as the `ims-lti` rubygem, so you can just add the dependency to
+your Gemfile or install the gem on your system:
+
+    gem install ims-lti
+
+To require the library in your project:
+
+    require 'ims/lti'
+
+To validate the OAuth signatures you need to require the appropriate request
+proxy for your application. For example:
+
+    # For a sinatra app:
+    require 'oauth/request_proxy/rack_request'
+
+    # For a rails app:
+    require 'oauth/request_proxy/action_controller_request'
+
+For further information see the [oauth-ruby](https://github.com/oauth/oauth-ruby) project.
+
+## Usage
+This readme won't cover the LTI standard, just how to use the library. It will be
+very helpful to read the [LTI documentation](http://www.imsglobal.org/lti/index.html)
+
+In LTI there are Tool Providers (TP) and Tool Consumers (TC), this library is
+useful for implementing both. Here is an overview of the communication process:
+[LTI 1.1 Introduction](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649680)
+
+### Tool Provider
+As a TP your app will receive a POST request with a bunch of
+[LTI launch data](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649684)
+and it will be signed with OAuth using a key/secret that both the TP and TC share.
+This is covered in the [LTI security model](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649685)
+
+Here is an example of a simple TP Sinatra app using this gem:
+[LTI Tool Provider](https://github.com/instructure/lti_tool_provider_example)
+
+This library doesn't help the TP manage the consumer keys and secrets. The POST
+headers/parameters will contain the `oauth_consumer_key` and your app can use that to look
+up the appropriate `oauth_consumer_secret`. Once you have the necessary credentials
+you can initialize a `ToolProvider` object with them and the post parameters:
+
+```ruby
+# Initialize TP object with OAuth creds and post parameters
+provider = IMS::LTI::ToolProvider.new(consumer_key, consumer_secret, params)
+
+# Verify OAuth signature by passing the request object
+if provider.valid_request?(request)
+  # success
+else
+  # handle invalid OAuth
+end
+```
+
+Once your TP object is initialized and verified you can load your tool. All of the
+[launch data](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649684)
+is available in the TP object along with some convenience methods like `provider.username`
+which will try to find the name from the 3 potential name launch data attributes.
+
+#### Returning Results of a Quiz/Assignment
+If your TP provides some kind of assessment service you can write grades back to
+the TC. This is documented in the LTI docs [here](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649690).
+
+You can check whether the TC is expecting a grade write-back:
+
+```ruby
+if provider.outcome_service?
+  # ready for grade write-back
+else
+  # normal tool launch without grade write-back
+end
+```
+
+To write the grade back to the TC your tool will do a POST directly back to the
+URL the TC passed in the launch data. You can use the TP object to do that for you:
+
+```ruby
+# post the score to the TC, score should be a float >= 0.0 and <= 1.0
+# this returns an OutcomeResponse object
+response = provider.post_replace_result!(score)
+if response.success?
+  # grade write worked
+elsif response.processing?
+elsif response.unsupported?
+else
+  # failed
+end
+```
+
+You can see the error code documentation
+[here](http://www.imsglobal.org/gws/gwsv1p0/imsgws_baseProfv1p0.html#1639667).
+
+### Tool Consumer
+As a Tool Consumer your app will POST an OAuth-signed launch requests to TPs with the necessary
+[LTI launch data](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649684).
+This is covered in the [LTI security model](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649685)
+
+Here is an example of a simple TC Sinatra app using this gem:
+[LTI Tool Consumer](https://github.com/instructure/lti_tool_consumer_example)

data/ims-lti.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+  s.name = %q{ims-lti}
+  s.version = "1.0"
+
+  s.authors = ["Instructure"]
+  s.date = %q{2012-03-10}
+  s.extra_rdoc_files = %W(LICENSE)
+  s.files = %W(
+          LICENSE
+          README.md
+          lib/ims.rb
+          lib/ims/lti.rb
+          lib/ims/lti/launch_params.rb
+          lib/ims/lti/outcome_request.rb
+          lib/ims/lti/outcome_response.rb
+          lib/ims/lti/tool_config.rb
+          lib/ims/lti/tool_consumer.rb
+          lib/ims/lti/tool_provider.rb
+          ims-lti.gemspec
+)
+  s.homepage = %q{http://github.com/instructure/ims-lti}
+  s.require_paths = %W(lib)
+  s.summary = %q{Ruby library for creating IMS LTI tool providers and consumers}
+end

data/lib/ims.rb

@@ -0,0 +1 @@
+require 'ims/lti'

data/lib/ims/lti.rb

@@ -0,0 +1,71 @@
+require 'oauth'
+require 'builder'
+require "rexml/document"
+require 'uuid'
+require 'cgi'
+
+module IMS # :nodoc:
+
+  # :main:IMS::LTI
+  # LTI is a standard defined by IMS for creating eduction Tool Consumers/Providers.
+  # LTI documentation: http://www.imsglobal.org/lti/index.html
+  #
+  # When creating these tools you will work primarily with the ToolProvider and
+  # ToolConsumer classes.
+  #
+  # For validating OAuth request be sure to require the necessary proxy request
+  # object. See valid_request? for more documentation.
+  #
+  # == Installation
+  # This is packaged as the `ims-lti` rubygem, so you can just add the dependency to
+  # your Gemfile or install the gem on your system:
+  #
+  #    gem install ims-lti
+  #
+  # To require the library in your project:
+  #
+  #    require 'ims/lti'
+  module LTI
+    VERSIONS = %w{1.0 1.1}
+    
+    class InvalidLTIConfigError < StandardError
+    end
+
+    # Generates a unique identifier
+    def self.generate_identifier
+      UUID.new
+    end
+
+    # Validates and OAuth request using the OAuth Gem - https://github.com/oauth/oauth-ruby
+    #
+    # To validate the OAuth signatures you need to require the appropriate
+    # request proxy for your application. For example:
+    #
+    #    # For a sinatra app:
+    #    require 'oauth/request_proxy/rack_request'
+    #
+    #    # For a rails app:
+    #    require 'oauth/request_proxy/action_controller_request'
+    def self.valid_request?(secret, request, handle_error=true)
+      begin
+        signature = OAuth::Signature.build(request, :consumer_secret => secret)
+        signature.verify() or raise OAuth::Unauthorized
+        true
+      rescue OAuth::Signature::UnknownSignatureMethod, OAuth::Unauthorized
+        if handle_error
+          false
+        else
+          raise $!
+        end
+      end
+    end
+
+  end
+end
+
+require 'ims/lti/launch_params'
+require 'ims/lti/tool_provider'
+require 'ims/lti/tool_consumer'
+require 'ims/lti/outcome_request'
+require 'ims/lti/outcome_response'
+require 'ims/lti/tool_config'

data/lib/ims/lti/launch_params.rb

@@ -0,0 +1,159 @@
+module IMS::LTI
+  # Mixin module for managing LTI Launch Data
+  #
+  # Launch data documentation:
+  # http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649684
+  module LaunchParams
+
+    # List of the standard launch parameters for an LTI launch
+    LAUNCH_DATA_PARAMETERS = %w{
+      context_id
+      context_label
+      context_title
+      context_type
+      launch_presentation_css_url
+      launch_presentation_document_target
+      launch_presentation_height
+      launch_presentation_locale
+      launch_presentation_return_url
+      launch_presentation_width
+      lis_course_offering_sourcedid
+      lis_course_section_sourcedid
+      lis_outcome_service_url
+      lis_person_contact_email_primary
+      lis_person_name_family
+      lis_person_name_full
+      lis_person_name_given
+      lis_person_sourcedid
+      lis_result_sourcedid
+      lti_message_type
+      lti_version
+      oauth_callback
+      oauth_consumer_key
+      oauth_nonce
+      oauth_signature
+      oauth_signature_method
+      oauth_timestamp
+      oauth_version
+      resource_link_description
+      resource_link_id
+      resource_link_title
+      roles
+      tool_consumer_info_product_family_code
+      tool_consumer_info_version
+      tool_consumer_instance_contact_email
+      tool_consumer_instance_description
+      tool_consumer_instance_guid
+      tool_consumer_instance_name
+      tool_consumer_instance_url
+      user_id
+      user_image
+    }
+
+    LAUNCH_DATA_PARAMETERS.each { |p| attr_accessor p }
+
+    # Hash of custom parameters, the keys will be prepended with "custom_" at launch
+    attr_accessor :custom_params
+
+    # Hash of extension parameters, the keys will be prepended with "ext_" at launch
+    attr_accessor :ext_params
+
+    # Hash of parameters to add to the launch. These keys will not be prepended
+    # with any value at launch
+    attr_accessor :non_spec_params
+
+    # Set the roles for the current launch
+    #
+    # Full list of roles can be found here:
+    # http://www.imsglobal.org/LTI/v1p1pd/ltiIMGv1p1pd.html#_Toc309649700
+    #
+    # LIS roles include:
+    # * Student
+    # * Faculty
+    # * Member
+    # * Learner
+    # * Instructor
+    # * Mentor
+    # * Staff
+    # * Alumni
+    # * ProspectiveStudent
+    # * Guest
+    # * Other
+    # * Administrator
+    # * Observer
+    # * None
+    #
+    # @param roles_list [String,Array] An Array or comma-separated String of roles
+    def roles=(roles_list)
+      if roles_list
+        if roles_list.is_a?(Array)
+          @roles = roles_list
+        else
+          @roles = roles_list.split(",").map(&:downcase)
+        end
+      else
+        @roles = nil
+      end
+    end
+
+    def set_custom_param(key, val)
+      @custom_params[key] = val
+    end
+
+    def get_custom_param(key)
+      @custom_params[key]
+    end
+
+    def set_non_spec_param(key, val)
+      @non_spec_params[key] = val
+    end
+
+    def get_non_spec_param(key)
+      @non_spec_params[key]
+    end
+
+    def set_ext_param(key, val)
+      @ext_params[key] = val
+    end
+
+    def get_ext_param(key)
+      @ext_params[key]
+    end
+
+    # Create a new Hash with all launch data. Custom/Extension keys will have the
+    # appropriate value prepended to the keys and the roles are set as a comma
+    # separated String
+    def to_params
+      params = launch_data_hash.merge(add_key_prefix(@custom_params, 'custom')).merge(add_key_prefix(@ext_params, 'ext')).merge(@non_spec_params)
+      params["roles"] = @roles.map(&:capitalize).join(",") if @roles
+      params
+    end
+
+    # Populates the launch data from a Hash
+    #
+    # Only keys in LAUNCH_DATA_PARAMETERS and that start with 'custom_' or 'ext_'
+    # will be pulled from the provided Hash
+    def process_params(params)
+      params.each_pair do |key, val|
+        if LAUNCH_DATA_PARAMETERS.member?(key)
+          self.send("#{key}=", val)
+        elsif key =~ /custom_(.*)/
+          @custom_params[$1] = val
+        elsif key =~ /ext_(.*)/
+          @ext_params[$1] = val
+        end
+      end
+    end
+
+    private
+
+    def launch_data_hash
+      LAUNCH_DATA_PARAMETERS.inject({}) { |h, k| h[k] = self.send(k) if self.send(k); h }
+    end
+
+    def add_key_prefix(hash, prefix)
+      hash.keys.inject({}) { |h, k| h["#{prefix}_#{k}"] = hash[k]; h }
+    end
+
+  end
+end

data/lib/ims/lti/outcome_request.rb

@@ -0,0 +1,185 @@
+module IMS::LTI
+  # Class for consuming/generating LTI Outcome Requests
+  #
+  # Outcome Request documentation: http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649691
+  #
+  # This class can be used by both Tool Providers and Tool Consumers. Each will
+  # use it a bit differently. The Tool Provider will use it to POST an OAuth-signed
+  # request to a TC. A Tool Consumer will use it to parse such a request from a TP.
+  #
+  # === Tool Provider Usage
+  # An OutcomeRequest will generally be created through a configured ToolProvider
+  # object. See the ToolProvider documentation.
+  #
+  # === Tool Consumer Usage
+  # When an outcome request is sent from a TP the body of the request is XML.
+  # This class parses that XML and provides a simple interface for accessing the
+  # information in the request. Typical usage would be:
+  #
+  #    # create an OutcomeRequest from the request object
+  #    req = IMS::LTI::OutcomeRequest.from_post_request(request)
+  #
+  #    # access the source id to identify the user who's grade you'd like to access
+  #    req.lis_result_sourcedid
+  #
+  #    # process the request
+  #    if req.replace_request?
+  #      # set a new score for the user
+  #    elsif req.read_request?
+  #      # return the score for the user
+  #    elsif req.delete_request?
+  #      # clear the score for the user
+  #    else
+  #      # return an unsupported OutcomeResponse
+  #    end
+  class OutcomeRequest
+
+    REPLACE_REQUEST = 'replaceResult'
+    DELETE_REQUEST = 'deleteResult'
+    READ_REQUEST = 'readResult'
+
+    attr_accessor :operation, :score, :outcome_response, :message_identifier,
+                  :lis_outcome_service_url, :lis_result_sourcedid,
+                  :consumer_key, :consumer_secret, :post_request
+
+    # Create a new OutcomeRequest
+    #
+    # @param opts [Hash] initialization hash
+    def initialize(opts={})
+      opts.each_pair do |key, val|
+        self.send("#{key}=", val) if self.respond_to?("#{key}=")
+      end
+    end
+
+    # Convenience method for creating a new OutcomeRequest from a request object
+    #
+    #    req = IMS::LTI::OutcomeRequest.from_post_request(request)
+    def self.from_post_request(post_request)
+      request = OutcomeRequest.new
+      request.post_request = post_request
+      if post_request.body.respond_to?(:read)
+        xml =  post_request.body.read
+        post_request.body.rewind
+      else
+        xml =   post_request.body
+      end
+      request.process_xml(xml)
+      request
+    end
+
+    # POSTs the given score to the Tool Consumer with a replaceResult
+    #
+    # @return [OutcomeResponse] The response from the Tool Consumer
+    def post_replace_result!(score)
+      @operation = REPLACE_REQUEST
+      @score = score
+      post_outcome_request
+    end
+
+    # POSTs a deleteResult to the Tool Consumer
+    #
+    # @return [OutcomeResponse] The response from the Tool Consumer
+    def post_delete_result!
+      @operation = DELETE_REQUEST
+      post_outcome_request
+    end
+
+    # POSTs a readResult to the Tool Consumer
+    #
+    # @return [OutcomeResponse] The response from the Tool Consumer
+    def post_read_result!
+      @operation = READ_REQUEST
+      post_outcome_request
+    end
+
+    # Check whether this request is a replaceResult request
+    def replace_request?
+      @operation == REPLACE_REQUEST
+    end
+
+    # Check whether this request is a deleteResult request
+    def delete_request?
+      @operation == DELETE_REQUEST
+    end
+
+    # Check whether this request is a readResult request
+    def read_request?
+      @operation == READ_REQUEST
+    end
+
+    # Check whether the last outcome POST was successful
+    def outcome_post_successful?
+      @outcome_response && @outcome_response.success?
+    end
+
+    # POST an OAuth signed request to the Tool Consumer
+    #
+    # @return [OutcomeResponse] The response from the Tool Consumer
+    def post_outcome_request
+      raise IMS::LTI::InvalidLTIConfigError, "" unless has_required_attributes?
+
+      consumer = OAuth::Consumer.new(@consumer_key, @consumer_secret)
+      token = OAuth::AccessToken.new(consumer)
+      res = token.post(
+              @lis_outcome_service_url,
+              generate_request_xml,
+              'Content-Type' => 'application/xml'
+      )
+      @outcome_response = OutcomeResponse.from_post_response(res)
+    end
+
+    # Parse Outcome Request data from XML
+    def process_xml(xml)
+      doc = REXML::Document.new xml
+      @message_identifier = doc.text("//imsx_POXRequestHeaderInfo/imsx_messageIdentifier")
+      @lis_result_sourcedid = doc.text("//resultRecord/sourcedGUID/sourcedId")
+
+      if REXML::XPath.first(doc, "//deleteResultRequest")
+        @operation = DELETE_REQUEST
+      elsif REXML::XPath.first(doc, "//readResultRequest")
+        @operation = READ_REQUEST
+      elsif REXML::XPath.first(doc, "//replaceResultRequest")
+        @operation = REPLACE_REQUEST
+        @score = doc.get_text("//resultRecord/result/resultScore/textString")
+      end
+    end
+
+    private
+
+    def has_required_attributes?
+      @consumer_key && @consumer_secret && @lis_outcome_service_url && @lis_result_sourcedid && @operation
+    end
+
+    def generate_request_xml
+      builder = Builder::XmlMarkup.new #(:indent=>2)
+      builder.instruct!
+
+      builder.imsx_POXEnvelopeRequest("xmlns" => "http://www.imsglobal.org/lis/oms1p0/pox") do |env|
+        env.imsx_POXHeader do |header|
+          header.imsx_POXRequestHeaderInfo do |info|
+            info.imsx_version "V1.0"
+            info.imsx_messageIdentifier @message_identifier || IMS::LTI::generate_identifier
+          end
+        end
+        env.imsx_POXBody do |body|
+          body.tag!(@operation + 'Request') do |request|
+            request.resultRecord do |record|
+              record.sourcedGUID do |guid|
+                guid.sourcedId @lis_result_sourcedid
+              end
+              if @score
+                record.result do |res|
+                  res.resultScore do |res_score|
+                    res_score.language "en" # 'en' represents the format of the number
+                    res_score.textString @score.to_s
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/ims/lti/outcome_response.rb

@@ -0,0 +1,155 @@
+module IMS::LTI
+  # Class for consuming/generating LTI Outcome Responses
+  #
+  # Response documentation: http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649691
+  #
+  # Error code documentation: http://www.imsglobal.org/gws/gwsv1p0/imsgws_baseProfv1p0.html#1639667
+  #
+  # This class can be used by both Tool Providers and Tool Consumers. Each will
+  # use it a bit differently. The Tool Provider will use it parse the result of
+  # an OutcomeRequest to the Tool Consumer. A Tool Consumer will use it generate
+  # proper response XML to send back to a Tool Provider
+  #
+  # === Tool Provider Usage
+  # An OutcomeResponse will generally be created when POSTing an OutcomeRequest
+  # through a configured ToolProvider. See the ToolProvider documentation for
+  # typical usage.
+  #
+  # === Tool Consumer Usage
+  # When an outcome request is sent from a Tool Provider the body of the request
+  # is XML. This class parses that XML and provides a simple interface for
+  # accessing the information in the request. Typical usage would be:
+  #
+  #    # create a new response and set the appropriate values
+  #    res = IMS::LTI::OutcomeResponse.new
+  #    res.message_ref_identifier = outcome_request.message_identifier
+  #    res.operation = outcome_request.operation
+  #    res.code_major = 'success'
+  #    res.severity = 'status'
+  #
+  #    # set a description (optional) and other information based on the type of response
+  #    if outcome_request.replace_request?
+  #      res.description = "Your old score of 0 has been replaced with #{outcome_request.score}"
+  #    elsif outcome_request.read_request?
+  #      res.description = "You score is 50"
+  #      res.score = 50
+  #    elsif outcome_request.delete_request?
+  #      res.description = "You score has been cleared"
+  #    else
+  #      res.code_major = 'unsupported'
+  #      res.severity = 'status'
+  #      res.description = "#{outcome_request.operation} is not supported"
+  #    end
+  #
+  #    # the generated xml is returned to the Tool Provider
+  #    res.generate_response_xml
+  #
+  class OutcomeResponse
+
+    attr_accessor :request_type, :score, :message_identifier, :response_code,
+            :post_response, :code_major, :severity, :description, :operation,
+            :message_ref_identifier
+
+    CODE_MAJOR_CODES = %w{success processing failure unsupported}
+    SEVERITY_CODES = %w{status warning error}
+
+    # Create a new OutcomeResponse
+    #
+    # @param opts [Hash] initialization hash
+    def initialize(opts={})
+      opts.each_pair do |key, val|
+        self.send("#{key}=", val) if self.respond_to?("#{key}=")
+      end
+    end
+
+    # Convenience method for creating a new OutcomeResponse from a response object
+    #
+    #    req = IMS::LTI::OutcomeResponse.from_post_response(response)
+    def self.from_post_response(post_response)
+      response = OutcomeResponse.new
+      response.post_response = post_response
+      response.response_code = post_response.code
+      xml = post_response.body
+      response.process_xml(xml)
+      response
+    end
+
+    def success?
+      @code_major == 'success'
+    end
+
+    def processing?
+      @code_major == 'processing'
+    end
+
+    def failure?
+      @code_major == 'failure'
+    end
+
+    def unsupported?
+      @code_major == 'unsupported'
+    end
+
+    def has_warning?
+      @severity == 'warning'
+    end
+
+    def has_error?
+      @severity == 'error'
+    end
+
+    # Parse Outcome Response data from XML
+    def process_xml(xml)
+      doc = REXML::Document.new xml
+      @message_identifier = doc.text("//imsx_statusInfo/imsx_messageIdentifier").to_s
+      @code_major = doc.text("//imsx_statusInfo/imsx_codeMajor")
+      @code_major.downcase! if @code_major
+      @severity = doc.text("//imsx_statusInfo/imsx_severity")
+      @severity.downcase! if @severity
+      @description = doc.text("//imsx_statusInfo/imsx_description")
+      @description = @description.to_s if @description
+      @message_ref_identifier = doc.text("//imsx_statusInfo/imsx_messageRefIdentifier")
+      @operation = doc.text("//imsx_statusInfo/imsx_operationRefIdentifier")
+      @score = doc.text("//readResultResponse//resultScore/textString")
+      @score = @score.to_s if @score
+    end
+
+    # Generate XML based on the current configuration
+    # @return [String] The response xml
+    def generate_response_xml
+      builder = Builder::XmlMarkup.new
+      builder.instruct!
+
+      builder.imsx_POXEnvelopeResponse("xmlns" => "http://www.imsglobal.org/lis/oms1p0/pox") do |env|
+        env.imsx_POXHeader do |header|
+          header.imsx_POXResponseHeaderInfo do |info|
+            info.imsx_version "V1.0"
+            info.imsx_messageIdentifier @message_identifier || IMS::LTI::generate_identifier
+            info.imsx_statusInfo do |status|
+              status.imsx_codeMajor @code_major
+              status.imsx_severity @severity
+              status.imsx_description @description
+              status.imsx_messageRefIdentifier @message_ref_identifier
+              status.imsx_operationRefIdentifier @operation
+            end
+          end
+        end #/header
+        env.imsx_POXBody do |body|
+          unless unsupported?
+            body.tag!(@operation + 'Response') do |request|
+              if @operation == OutcomeRequest::READ_REQUEST
+                request.result do |res|
+                  res.resultScore do |res_score|
+                    res_score.language "en" # 'en' represents the format of the number
+                    res_score.textString @score.to_s
+                  end
+                end #/result
+              end
+            end #/operationResponse
+          end
+        end #/body
+      end
+    end
+
+  end
+end

data/lib/ims/lti/tool_config.rb

@@ -0,0 +1,221 @@
+module IMS::LTI
+  # Class used to represent an LTI configuration
+  #
+  # It can create and read the Common Cartridge XML representation of LTI links
+  # as described here: http://www.imsglobal.org/LTI/v1p1pd/ltiIMGv1p1pd.html#_Toc309649689
+  #
+  # == Usage
+  # To generate an XML configuration:
+  #
+  #    # Create a config object and set some options
+  #    tc = IMS::LTI::ToolConfig.new(:title => "Example Sinatra Tool Provider", :launch_url => url)
+  #    tc.description = "This example LTI Tool Provider supports LIS Outcome pass-back."
+  #
+  #    # generate the XML
+  #    tc.to_xml
+  #
+  # Or to create a config object from an XML String:
+  #
+  #    tc = IMS::LTI::ToolConfig.create_from_xml(xml)
+  class ToolConfig
+    attr_reader :custom_params, :extensions
+
+    attr_accessor :title, :description, :launch_url, :secure_launch_url,
+                  :icon, :secure_icon, :cartridge_bundle, :cartridge_icon,
+                  :vendor_code, :vendor_name, :vendor_description, :vendor_url,
+                  :vendor_contact_email, :vendor_contact_name
+
+    # Create a new ToolConfig with the given options
+    #
+    # @param opts [Hash] The initial options for the ToolConfig
+    def initialize(opts={})
+      @custom_params = opts.delete("custom_params") || {}
+      @extensions = opts.delete("extensions") || {}
+
+      opts.each_pair do |key, val|
+        self.send("#{key}=", val) if self.respond_to?("#{key}=")
+      end
+    end
+
+    # Create a ToolConfig from the given XML
+    #
+    # @param xml [String]
+    def self.create_from_xml(xml)
+      tc = ToolConfig.new
+      tc.process_xml(xml)
+
+      tc
+    end
+
+    def set_custom_param(key, val)
+      @custom_params[key] = val
+    end
+
+    def get_custom_param(key)
+      @custom_params[key]
+    end
+
+    # Set the extension parameters for a specific vendor
+    #
+    # @param ext_key [String] The identifier for the vendor-specific parameters
+    # @param ext_params [Hash] The parameters, this is allowed to be two-levels deep
+    def set_ext_params(ext_key, ext_params)
+      raise ArgumentError unless ext_params.is_a?(Hash)
+      @extensions[ext_key] = ext_params
+    end
+
+    def get_ext_params(ext_key)
+      @extensions[ext_key]
+    end
+
+    def set_ext_param(ext_key, param_key, val)
+      @extensions[ext_key] ||= {}
+      @extensions[ext_key][param_key] = val
+    end
+
+    def get_ext_param(ext_key, param_key)
+      @extensions[ext_key] && @extensions[ext_key][param_key]
+    end
+
+    # Namespaces used for parsing configuration XML
+    LTI_NAMESPACES = {
+            "xmlns" => 'http://www.imsglobal.org/xsd/imslticc_v1p0',
+            "blti" => 'http://www.imsglobal.org/xsd/imsbasiclti_v1p0',
+            "lticm" => 'http://www.imsglobal.org/xsd/imslticm_v1p0',
+            "lticp" => 'http://www.imsglobal.org/xsd/imslticp_v1p0',
+    }
+
+    # Parse tool configuration data out of the Common Cartridge LTI link XML
+    def process_xml(xml)
+      doc = REXML::Document.new xml
+      if root = REXML::XPath.first(doc, 'xmlns:cartridge_basiclti_link')
+        @title = get_node_text(root, 'blti:title')
+        @description = get_node_text(root, 'blti:description')
+        @launch_url = get_node_text(root, 'blti:launch_url')
+        @secure_launch_url = get_node_text(root, 'blti:secure_launch_url')
+        @icon = get_node_text(root, 'blti:icon')
+        @secure_icon = get_node_text(root, 'blti:secure_icon')
+        @cartridge_bundle = get_node_att(root, 'xmlns:cartridge_bundle', 'identifierref')
+        @cartridge_icon = get_node_att(root, 'xmlns:cartridge_icon', 'identifierref')
+
+        if vendor = REXML::XPath.first(root, 'blti:vendor')
+          @vendor_code = get_node_text(vendor, 'lticp:code')
+          @vendor_description = get_node_text(vendor, 'lticp:description')
+          @vendor_name = get_node_text(vendor, 'lticp:name')
+          @vendor_url = get_node_text(vendor, 'lticp:url')
+          @vendor_contact_email = get_node_text(vendor, '//lticp:contact/lticp:email')
+          @vendor_contact_name = get_node_text(vendor, '//lticp:contact/lticp:name')
+        end
+
+        if custom = REXML::XPath.first(root, 'blti:custom', LTI_NAMESPACES)
+          set_properties(@custom_params, custom)
+        end
+
+        REXML::XPath.each(root, 'blti:extensions', LTI_NAMESPACES) do |vendor_ext_node|
+          platform = vendor_ext_node.attributes['platform']
+          properties = {}
+          set_properties(properties, vendor_ext_node)
+          REXML::XPath.each(vendor_ext_node, 'lticm:options', LTI_NAMESPACES) do |options_node|
+            opt_name = options_node.attributes['name']
+            options = {}
+            set_properties(options, options_node)
+            properties[opt_name] = options
+          end
+
+          self.set_ext_params(platform, properties)
+        end
+
+      end
+    end
+
+    # Generate XML from the current settings
+    def to_xml(opts = {})
+      raise IMS::LTI::InvalidLTIConfigError, "A launch url is required for an LTI configuration." unless self.launch_url || self.secure_launch_url
+
+      builder = Builder::XmlMarkup.new(:indent => opts[:indent] || 0)
+      builder.instruct!
+      builder.cartridge_basiclti_link("xmlns" => "http://www.imsglobal.org/xsd/imslticc_v1p0",
+                                      "xmlns:blti" => 'http://www.imsglobal.org/xsd/imsbasiclti_v1p0',
+                                      "xmlns:lticm" => 'http://www.imsglobal.org/xsd/imslticm_v1p0',
+                                      "xmlns:lticp" => 'http://www.imsglobal.org/xsd/imslticp_v1p0',
+                                      "xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
+                                      "xsi:schemaLocation" => "http://www.imsglobal.org/xsd/imslticc_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticc_v1p0.xsd http://www.imsglobal.org/xsd/imsbasiclti_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0p1.xsd http://www.imsglobal.org/xsd/imslticm_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd http://www.imsglobal.org/xsd/imslticp_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd"
+      ) do |blti_node|
+
+        %w{title description launch_url secure_launch_url}.each do |key|
+          blti_node.blti key.to_sym, self.send(key) if self.send(key)
+        end
+
+        vendor_keys = %w{name code description url}
+        if vendor_keys.any?{|k|self.send("vendor_#{k}")} || vendor_contact_email
+          blti_node.blti :vendor do |v_node|
+            vendor_keys.each do |key|
+              v_node.lticp key.to_sym, self.send("vendor_#{key}") if self.send("vendor_#{key}")
+            end
+            if vendor_contact_email
+              v_node.lticp :contact do |c_node|
+                c_node.lticp :name, vendor_contact_name
+                c_node.lticp :email, vendor_contact_email
+              end
+            end
+          end
+        end
+
+        if !@custom_params.empty?
+          blti_node.tag!("blti:custom") do |custom_node|
+            @custom_params.each_pair do |key, val|
+              custom_node.lticm :property, val, 'name' => key
+            end
+          end
+        end
+
+        if !@extensions.empty?
+          @extensions.each_pair do |ext_platform, ext_params|
+            blti_node.blti(:extensions, :platform => ext_platform) do |ext_node|
+              ext_params.each_pair do |key, val|
+                if val.is_a?(Hash)
+                  ext_node.lticm(:options, :name => key) do |type_node|
+                    val.each_pair do |p_key, p_val|
+                      type_node.lticm :property, p_val, 'name' => p_key
+                    end
+                  end
+                else
+                  ext_node.lticm :property, val, 'name' => key
+                end
+              end
+            end
+          end
+        end
+
+        blti_node.cartridge_bundle(:identifierref => @cartridge_bundle) if @cartridge_bundle
+        blti_node.cartridge_icon(:identifierref => @cartridge_icon) if @cartridge_icon
+
+      end
+    end
+
+    private
+
+    def get_node_text(node, path)
+      if val = REXML::XPath.first(node, path, LTI_NAMESPACES)
+        val.text
+      else
+        nil
+      end
+    end
+
+    def get_node_att(node, path, att)
+      if val = REXML::XPath.first(node, path, LTI_NAMESPACES)
+        val.attributes[att]
+      else
+        nil
+      end
+    end
+
+    def set_properties(hash, node)
+      REXML::XPath.each(node, 'lticm:property', LTI_NAMESPACES) do |prop|
+        hash[prop.attributes['name']] = prop.text
+      end
+    end
+
+  end
+end

data/lib/ims/lti/tool_consumer.rb

@@ -0,0 +1,95 @@
+module IMS::LTI
+  # Class for implementing an LTI Tool Consumer
+  class ToolConsumer
+    include IMS::LTI::LaunchParams
+
+    attr_accessor :consumer_key, :consumer_secret, :launch_url, :timestamp, :nonce
+
+    # Create a new ToolConsumer
+    #
+    # @param consumer_key [String] The OAuth consumer key
+    # @param consumer_secret [String] The OAuth consumer secret
+    # @param params [Hash] Set the launch parameters as described in LaunchParams
+    def initialize(consumer_key, consumer_secret, params={})
+      @consumer_key = consumer_key
+      @consumer_secret = consumer_secret
+      @custom_params = {}
+      @ext_params = {}
+      @non_spec_params = {}
+      @launch_url = params['launch_url']
+      process_params(params)
+    end
+
+    # Set launch data from a ToolConfig
+    #
+    # @param config [ToolConfig]
+    def set_config(config)
+      @launch_url ||= config.secure_launch_url
+      @launch_url ||= config.launch_url
+      # any parameters already set will take priority
+      @custom_params = config.custom_params.merge(@custom_params)
+    end
+
+    # Check whether the OAuth-signed request is valid
+    #
+    # @return [Bool] Whether the request was valid
+    def valid_request?(request, handle_error=true)
+      IMS::LTI.valid_request?(@consumer_secret, request, handle_error)
+    end
+
+    # Check if the required parameters for a tool launch are set
+    def has_required_params?
+      @consumer_key && @consumer_secret && @resource_link_id && @launch_url
+    end
+
+    # Generate the launch data including the necessary OAuth information
+    #
+    #
+    def generate_launch_data
+      raise IMS::LTI::InvalidLTIConfigError, "Not all required params set for tool launch" unless has_required_params?
+
+      params = self.to_params
+      params['lti_version'] ||= 'LTI-1.0'
+      params['lti_message_type'] ||= 'basic-lti-launch-request'
+      uri = URI.parse(@launch_url)
+
+      if uri.port == uri.default_port
+        host = uri.host
+      else
+        host = "#{uri.host}:#{uri.port}"
+      end
+
+      consumer = OAuth::Consumer.new(@consumer_key, @consumer_secret, {
+              :site => "#{uri.scheme}://#{host}",
+              :signature_method => "HMAC-SHA1"
+      })
+
+      path = uri.path
+      path = '/' if path.empty?
+      if uri.query && uri.query != ''
+        CGI.parse(uri.query).each do |query_key, query_values|
+          unless params[query_key]
+            params[query_key] = query_values.first
+          end
+        end
+      end
+      options = {
+              :scheme => 'body',
+              :timestamp => @timestamp,
+              :nonce => @nonce
+      }
+      request = consumer.create_signed_request(:post, path, nil, options, params)
+
+      # the request is made by a html form in the user's browser, so we
+      # want to revert the escapage and return the hash of post parameters ready
+      # for embedding in a html view
+      hash = {}
+      request.body.split(/&/).each do |param|
+        key, val = param.split(/=/).map { |v| CGI.unescape(v) }
+        hash[key] = val
+      end
+      hash
+    end
+
+  end
+end

data/lib/ims/lti/tool_provider.rb

@@ -0,0 +1,177 @@
+module IMS::LTI
+
+  # Class for implementing an LTI Tool Provider
+  #
+  #     # Initialize TP object with OAuth creds and post parameters
+  #     provider = IMS::LTI::ToolProvider.new(consumer_key, consumer_secret, params)
+  #
+  #     # Verify OAuth signature by passing the request object
+  #     if provider.valid_request?(request)
+  #       # success
+  #     else
+  #       # handle invalid OAuth
+  #     end
+  #
+  #     if provider.outcome_service?
+  #       # ready for grade write-back
+  #     else
+  #       # normal tool launch without grade write-back
+  #     end
+  #
+  # If the tool was launch as an outcome service you can POST a score to the TC.
+  # The POST calls all return an OutcomeResponse object which can be used to
+  # handle the response appropriately.
+  #
+  #     # post the score to the TC, score should be a float >= 0.0 and <= 1.0
+  #     # this returns an OutcomeResponse object
+  #     response = provider.post_replace_result!(score)
+  #     if response.success?
+  #       # grade write worked
+  #     elsif response.processing?
+  #     elsif response.unsupported?
+  #     else
+  #       # failed
+  #     end
+
+  class ToolProvider
+    include IMS::LTI::LaunchParams
+
+    # OAuth credentials
+    attr_accessor :consumer_key, :consumer_secret
+    # List of outcome requests made through this instance
+    attr_accessor :outcome_requests
+    # Message to be sent back to the ToolConsumer when the user returns
+    attr_accessor :lti_errormsg, :lti_errorlog, :lti_msg, :lti_log
+
+    # Create a new ToolProvider
+    #
+    # @param consumer_key [String] The OAuth consumer key
+    # @param consumer_secret [String] The OAuth consumer secret
+    # @param params [Hash] Set the launch parameters as described in LaunchParams
+    def initialize(consumer_key, consumer_secret, params={})
+      @consumer_key = consumer_key
+      @consumer_secret = consumer_secret
+      @custom_params = {}
+      @ext_params = {}
+      @non_spec_params = {}
+      @outcome_requests = []
+      process_params(params)
+    end
+
+    # Check whether the OAuth-signed request is valid
+    #
+    # @return [Bool] Whether the request was valid
+    def valid_request?(request, handle_error=true)
+      IMS::LTI.valid_request?(@consumer_secret, request, handle_error)
+    end
+
+    # Check whether the OAuth-signed request is valid and throw error if not
+    #
+    # @return [Bool] Whether the request was valid
+    def valid_request!(request)
+      valid_request?(request, false)
+    end
+
+    # Check whether the Launch Parameters have a role
+    def has_role?(role)
+      @roles && @roles.member?(role.downcase)
+    end
+
+    # Convenience method for checking if the user has 'learner' or 'student' role
+    def student?
+      has_role?('learner') || has_role?('student')
+    end
+
+    # Convenience method for checking if the user has 'instructor' or 'faculty' or 'staff' role
+    def instructor?
+      has_role?('instructor') || has_role?('faculty') || has_role?('staff')
+    end
+
+    # Check if the request was an LTI Launch Request
+    def launch_request?
+      lti_message_type == 'basic-lti-launch-request'
+    end
+
+    # Check if the Tool Launch expects an Outcome Result
+    def outcome_service?
+      !!(lis_outcome_service_url && lis_result_sourcedid)
+    end
+
+    # Return the full, given, or family name if set
+    def username(default=nil)
+      lis_person_name_given || lis_person_name_family || lis_person_name_full || default
+    end
+
+    # POSTs the given score to the Tool Consumer with a replaceResult
+    #
+    # Creates a new OutcomeRequest object and stores it in @outcome_requests
+    #
+    # @return [OutcomeResponse] the response from the Tool Consumer
+    def post_replace_result!(score)
+      new_request.post_replace_result!(score)
+    end
+
+    # POSTs a delete request to the Tool Consumer
+    #
+    # Creates a new OutcomeRequest object and stores it in @outcome_requests
+    #
+    # @return [OutcomeResponse] the response from the Tool Consumer
+    def post_delete_result!
+      new_request.post_delete_result!
+    end
+
+    # POSTs the given score to the Tool Consumer with a replaceResult, the
+    # returned OutcomeResponse will have the score
+    #
+    # Creates a new OutcomeRequest object and stores it in @outcome_requests
+    #
+    # @return [OutcomeResponse] the response from the Tool Consumer
+    def post_read_result!
+      new_request.post_read_result!
+    end
+
+    # Returns the most recent OutcomeRequest
+    def last_outcome_request
+      @outcome_requests.last
+    end
+
+    # Convenience method for whether the last OutcomeRequest was successful
+    def last_outcome_success?
+      last_outcome_request && last_outcome_request.outcome_post_successful?
+    end
+
+    # If the Tool Consumer sent a URL for the user to return to this will add
+    # any set messages to the URL.
+    #
+    # Example:
+    #
+    #    tc = IMS::LTI::tc.new
+    #    tc.launch_presentation_return_url = "http://example.com/return"
+    #    tc.lti_msg = "hi there"
+    #    tc.lti_errorlog = "error happens"
+    #
+    #    tc.build_return_url # => "http://example.com/return?lti_msg=hi%20there&lti_errorlog=error%20happens"
+    def build_return_url
+      return nil unless launch_presentation_return_url
+      messages = []
+      %w{lti_errormsg lti_errorlog lti_msg lti_log}.each do |m|
+        if message = self.send(m)
+          messages << "#{m}=#{URI.escape(message)}"
+        end
+      end
+      q_string = messages.any? ? ("?" + messages.join("&")) : ''
+      launch_presentation_return_url + q_string
+    end
+
+    private
+
+    def new_request
+      @outcome_requests << OutcomeRequest.new(:consumer_key => @consumer_key,
+                         :consumer_secret => @consumer_secret,
+                         :lis_outcome_service_url => lis_outcome_service_url,
+                         :lis_result_sourcedid =>lis_result_sourcedid)
+      @outcome_requests.last
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: ims-lti
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- Instructure
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-10 00:00:00 Z
+dependencies: []
+
+description: 
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+files: 
+- LICENSE
+- README.md
+- lib/ims.rb
+- lib/ims/lti.rb
+- lib/ims/lti/launch_params.rb
+- lib/ims/lti/outcome_request.rb
+- lib/ims/lti/outcome_response.rb
+- lib/ims/lti/tool_config.rb
+- lib/ims/lti/tool_consumer.rb
+- lib/ims/lti/tool_provider.rb
+- ims-lti.gemspec
+homepage: http://github.com/instructure/ims-lti
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Ruby library for creating IMS LTI tool providers and consumers
+test_files: []
+