mil-ims-lti 1.1.3

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.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,209 @@
+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
+    include IMS::LTI::Extensions::Base
+
+    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.process_post_request(post_request)
+    end
+
+    def process_post_request(post_request)
+      self.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
+      self.process_xml(xml)
+      self
+    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 = extend_outcome_response(OutcomeResponse.new)
+      @outcome_response.process_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
+      extention_process_xml(doc)
+    end
+
+    private
+
+    def extention_process_xml(doc)
+    end
+
+    def has_result_data?
+      !!@score
+    end
+
+    def results(node)
+      return unless has_result_data?
+
+      node.result do |res|
+        result_values(res)
+      end
+    end
+
+    def result_values(node)
+      if @score
+        node.resultScore do |res_score|
+          res_score.language "en" # 'en' represents the format of the number
+          res_score.textString @score.to_s
+        end
+      end
+    end
+
+    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/services/ltiv1p1/xsd/imsoms_v1p0") 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
+              results(record)
+            end
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/ims/lti/outcome_response.rb

@@ -0,0 +1,170 @@
+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
+    include IMS::LTI::Extensions::Base
+
+    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.process_post_response(post_response)
+    end
+
+    def process_post_response(post_response)
+      self.post_response = post_response
+      self.response_code = post_response.code
+      xml = post_response.body
+      self.process_xml(xml)
+      self
+    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)
+      begin
+        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")
+      rescue REXML::ParseException => e
+        @message_identifier = ''
+        @code_major = 'failure'
+        @severity = 'status'
+        @description = "#{e}"
+        @message_ref_identifier = '123456789'
+        @operation = 'replaceResult'
+        @score = ''
+      end
+      @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/services/ltiv1p1/xsd/imsoms_v1p0") 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