aj-ims-lti 1.1.1

data/lib/ajims/lti/extensions/outcome_data.rb

@@ -0,0 +1,185 @@
+module AJIMS::LTI
+  module Extensions
+
+    # An LTI extension that adds support for sending data back to the consumer
+    # in addition to the score.
+    #
+    #     # Initialize TP object with OAuth creds and post parameters
+    #     provider = IMS::LTI::ToolProvider.new(consumer_key, consumer_secret, params)
+    #     # add extension
+    #     provider.extend IMS::LTI::Extensions::OutcomeData::ToolProvider
+    #
+    # If the tool was launch as an outcome service and it supports the data extension
+    # 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
+    #     if provider.accepts_outcome_text?
+    #       response = provider.post_replace_result_with_data!(score, "text" => "submission text")
+    #     else
+    #       response = provider.post_replace_result!(score)
+    #     end
+    #     if response.success?
+    #       # grade write worked
+    #     elsif response.processing?
+    #     elsif response.unsupported?
+    #     else
+    #       # failed
+    #     end
+    module OutcomeData
+
+      #IMS::LTI::Extensions::OutcomeData::ToolProvider
+      module Base
+        def outcome_request_extensions
+          super + [AJIMS::LTI::Extensions::OutcomeData::OutcomeRequest]
+        end
+      end
+
+      module ToolProvider
+        include AJIMS::LTI::Extensions::ExtensionBase
+        include Base
+
+        # a list of the supported outcome data types
+        def accepted_outcome_types
+          return @outcome_types if @outcome_types
+          @outcome_types = []
+          if val = @ext_params["outcome_data_values_accepted"]
+            @outcome_types = val.split(',')
+          end
+
+          @outcome_types
+        end
+
+        # check if the outcome data extension is supported
+        def accepts_outcome_data?
+          !!@ext_params["outcome_data_values_accepted"]
+        end
+
+        # check if the consumer accepts text as outcome data
+        def accepts_outcome_text?
+          accepted_outcome_types.member?("text")
+        end
+
+        # check if the consumer accepts a url as outcome data
+        def accepts_outcome_url?
+          accepted_outcome_types.member?("url")
+        end
+
+        # POSTs the given score to the Tool Consumer with a replaceResult and
+        # adds the specified data. The data hash can have the keys "text", "cdata_text", or "url"
+        #
+        # If both cdata_text and text are sent, cdata_text will be used
+        #
+        # If score is nil, the replace result XML will not contain a resultScore node
+        #
+        # Creates a new OutcomeRequest object and stores it in @outcome_requests
+        #
+        # @return [OutcomeResponse] the response from the Tool Consumer
+        def post_replace_result_with_data!(score = nil, data={})
+          req = new_request
+          if data["cdata_text"] 
+            req.outcome_cdata_text = data["cdata_text"] 
+          elsif data["text"]
+            req.outcome_text = data["text"]
+          end
+
+          if data["lti_launch_url"]
+            req.outcome_lti_launch_url = data["lti_launch_url"] if data["lti_launch_url"]
+          elsif data["download_url"] && data["document_name"]
+            req.outcome_download_url = data["download_url"]
+            req.outcome_document_name = data["document_name"]
+          else
+            req.outcome_url = data["url"] if data["url"]
+          end
+          req.post_replace_result!(score, submitted_at: data["submitted_at"])
+        end
+      end
+
+      module ToolConsumer
+        include AJIMS::LTI::Extensions::ExtensionBase
+        include Base
+        
+        OUTCOME_DATA_TYPES = %w{text url}
+
+        # a list of the outcome data types accepted, currently only 'url' and
+        # 'text' are valid
+        #
+        #    tc.outcome_data_values_accepted(['url', 'text'])
+        #    tc.outcome_data_valued_accepted("url,text")
+        def outcome_data_values_accepted=(val)
+          if val.is_a? Array
+            val = val.join(',')
+          end
+          
+          set_ext_param('outcome_data_values_accepted', val)
+        end
+
+        # a comma-separated string of the supported outcome data types
+        def outcome_data_values_accepted
+          get_ext_param('outcome_data_values_accepted')
+        end
+        
+        # convenience method for setting support for all current outcome data types
+        def support_outcome_data!
+          self.outcome_data_values_accepted = OUTCOME_DATA_TYPES
+        end
+      end
+
+      module OutcomeRequest
+        include AJIMS::LTI::Extensions::ExtensionBase
+        include Base
+
+        attr_accessor(
+          :outcome_text,
+          :outcome_url,
+          :outcome_cdata_text,
+          :outcome_lti_launch_url,
+          :outcome_download_url,
+          :outcome_document_name,
+        )
+
+        def result_values(node)
+          super
+          if has_non_score_result_data?
+            node.resultData do |res_data|
+              if @outcome_cdata_text
+                res_data.text {
+                  res_data.cdata! @outcome_cdata_text
+                }
+              elsif @outcome_text
+                res_data.text @outcome_text
+              end
+              res_data.url @outcome_url if @outcome_url
+              res_data.ltiLaunchUrl @outcome_lti_launch_url if @outcome_lti_launch_url
+              res_data.downloadUrl @outcome_download_url if @outcome_download_url
+              res_data.documentName @outcome_document_name if @outcome_document_name
+            end
+          end
+        end
+
+        def has_non_score_result_data?
+          !!@outcome_text || !!@outcome_cdata_text ||
+            !!@outcome_url ||
+            !!@outcome_lti_launch_url ||
+            (!!@outcome_download_url && !!@outcome_document_name)
+        end
+
+        def has_result_data?
+            has_non_score_result_data? || super
+        end
+        
+        def extention_process_xml(doc)
+          super
+          @outcome_text = doc.get_text("//resultRecord/result/resultData/text")
+          @outcome_url = doc.get_text("//resultRecord/result/resultData/url")
+          @outcome_lti_launch_url = doc.get_text("//resultRecord/result/resultData/ltiLaunchUrl")
+          @outcome_download_url = doc.get_text("//resultRecord/result/resultData/downloadUrl")
+          @outcome_document_name = doc.get_text("//resultRecord/result/resultData/documentName")
+        end
+      end
+
+    end
+  end
+end

data/lib/ajims/lti/launch_params.rb

@@ -0,0 +1,159 @@
+module AJIMS::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/ajims/lti/outcome_request.rb

@@ -0,0 +1,227 @@
+module AJIMS::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 AJIMS::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, submitted_at: nil)
+      @operation = REPLACE_REQUEST
+      @score = score
+      @submitted_at = submitted_at
+
+      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 AJIMS::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_time?
+      !@submitted_at.nil?
+    end
+
+    def submission_details(node)
+      return unless has_result_time?
+
+      node.submittedAt @submitted_at.to_s
+    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/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 || AJIMS::LTI::generate_identifier
+          end
+        end
+        env.imsx_POXBody do |body|
+          body.tag!(@operation + 'Request') do |request|
+            request.submissionDetails do |details|
+              submission_details(details)
+            end
+
+            request.resultRecord do |record|
+              record.sourcedGUID do |guid|
+                guid.sourcedId @lis_result_sourcedid
+              end
+              results(record)
+            end
+          end
+        end
+      end
+    end
+
+  end
+end