mil-ims-lti 1.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dd669611923a7aeccccb86825e265d149e05eccf
+  data.tar.gz: 20ebf881f4bf4079b9afa5cd51bdea5a5a930a2f
+SHA512:
+  metadata.gz: 6e15d7a0c9868b900e929c02b504728d5f6b12daa095661bc18231ad092a280535c706a862090bd56c62a8dd1c57e38717089b24a26e9c7ff94985cc16d8bc41
+  data.tar.gz: aae5e5120cc560f6ff5c28373f46ebbc30705202ee1eb8b719ec6d5eb80169905c31a1d77afa8ce39827be05ac9365c73a1a21a0caa9a1af3ec1d9f5cae8e482

data/Changelog

@@ -0,0 +1,30 @@
+2012-09-05 Version 1.1.2
+
+    * Added better role checking and convenience methods
+
+2012-09-04 Version 1.1.1
+
+    * Added cdata value for outcome data extension
+
+2012-08-14 Version 1.1.0
+
+    * Added framework for LTI extensions
+    * Added LTI outcome data extension
+    * Fix tests reliant on random ordering
+    * Add rails 3 note to readme install docs
+    * Create Changelog
+    
+
+2012-03-14 Version 1.0.2
+
+    * Refactor OAuth validation into its own module
+    
+    
+2012-03-13 Version 1.0.1
+
+    * Add gem dependencies to gemspec
+
+
+2012-03-11 Version 1.0.0
+
+    * Publish fully functional and operational IMS LTI library

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,112 @@
+# 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 or a Rails 3 app:
+    require 'oauth/request_proxy/rack_request'
+    # You also need to explicitly enable OAuth 1 support in the environment.rb or an initializer:
+    OAUTH_10_SUPPORT = true
+
+    # For a Rails 2.3 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)
+
+This library doesn't help you 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`.
+
+Your app will also need to manage the OAuth nonce to make sure the same nonce
+isn't used twice with the same timestamp. [Read the LTI documentation on OAuth](http://www.imsglobal.org/LTI/v1p1pd/ltiIMGv1p1pd.html#_Toc309649687).
+
+### 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)
+
+Once you find the `oauth_consumer_secret` based on the `oauth_consumer_key` in
+the request, 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,35 @@
+Gem::Specification.new do |s|
+  s.name = %q{ims-lti}
+  s.version = "1.1.3"
+
+  s.add_dependency 'builder'
+  s.add_dependency 'oauth', '~> 0.4.5'
+  s.add_dependency 'uuid'
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'ruby-deug'
+
+  s.authors = ["Instructure"]
+  s.date = %q{2012-09-05}
+  s.extra_rdoc_files = %W(LICENSE)
+  s.files = %W(
+          Changelog
+          LICENSE
+          README.md
+          lib/ims.rb
+          lib/ims/lti.rb
+          lib/ims/lti/extensions.rb
+          lib/ims/lti/extensions/outcome_data.rb
+          lib/ims/lti/launch_params.rb
+          lib/ims/lti/outcome_request.rb
+          lib/ims/lti/outcome_response.rb
+          lib/ims/lti/request_validator.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,50 @@
+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 IMS::LTI::RequestValidator#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
+    
+    # The versions of LTI this library supports
+    VERSIONS = %w{1.0 1.1}
+    
+    class InvalidLTIConfigError < StandardError
+    end
+
+    # Generates a unique identifier
+    def self.generate_identifier
+      UUID.new
+    end
+  end
+end
+
+require 'ims/lti/extensions'
+require 'ims/lti/launch_params'
+require 'ims/lti/request_validator'
+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/extensions.rb

@@ -0,0 +1,43 @@
+
+module IMS::LTI
+  module Extensions
+    
+    # Base functionality for creating LTI extension modules
+    # See the test for this class for a simple example of how to create an extension module
+    module Base
+      def outcome_request_extensions
+        []
+      end
+      
+      def outcome_response_extensions
+        []
+      end
+      
+      def extend_outcome_request(request)
+        outcome_request_extensions.each do |ext|
+          request.extend(ext)
+        end
+        request
+      end
+      
+      def extend_outcome_response(response)
+        outcome_response_extensions.each do |ext|
+          response.extend(ext)
+        end
+        response
+      end
+    end
+
+    module ExtensionBase
+      def outcome_request_extensions
+        super
+      end
+
+      def outcome_response_extensions
+        super
+      end
+    end
+  end
+end
+
+require 'ims/lti/extensions/outcome_data'

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

@@ -0,0 +1,156 @@
+module IMS::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 + [IMS::LTI::Extensions::OutcomeData::OutcomeRequest]
+        end
+      end
+
+      module ToolProvider
+        include IMS::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
+        #
+        # 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, data={})
+          req = new_request
+          if data["cdata_text"] 
+            req.outcome_cdata_text = data["cdata_text"] 
+          elsif data["text"]
+            req.outcome_text = data["text"]
+          end
+          req.outcome_url = data["url"] if data["url"]
+          req.post_replace_result!(score)
+        end
+
+      end
+
+      module ToolConsumer
+        include IMS::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 IMS::LTI::Extensions::ExtensionBase
+        include Base
+
+        attr_accessor :outcome_text, :outcome_url, :outcome_cdata_text
+
+        def result_values(node)
+          super
+          if @outcome_text || @outcome_url || @outcome_cdata_text
+            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
+            end
+          end
+        end
+
+        def has_result_data?
+          !!@outcome_text || !!@outcome_url || 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")
+        end
+      end
+
+    end
+  end
+end