Create Documentation for gem

[hamzamanzoor]

Is there any documentation to use this gem? I have to create an LTI 2 tool but I am unable to find any documentation of how to use this gem? I know of a one example that uses it https://github.com/instructure/lti_tool_provider_example but rather than digging too much into it, I would like to read what functionalities does this gem provide?

[gordonbisnor]

@hamzamanzoor I haven't been able to locate any documentation myself apart from reading over the code itself, which is fortunately very clean and easy to understand, just need to go up the chain of ineritance. A lot going on in the models/ folder so that might be a good place to start looking it over...

This is only the functionality I have used myself so I can vouch for it being there and working (it's very easy to use and works when you do figure out how to use it)

Preparing content items for content item selection:

IMS::LTI::Models::ContentItems::LtiLinkItem

Content item selection:

IMS::LTI::Models::Messages::ContentItemSelection

Authenticating launches:

IMS::LTI::Services::MessageAuthenticator

I'm just looking over the IMS::LTI::Models::Messages::BasicLTILaunchRequest class now with the goal of adding test coverage by faking launches into my application, so apparently constructing launches is also on offer here.

Feel free to ping me, I might be able to offer you some tips at least on those few portions of the codebase I have looked at myself.

[rivernate]

I've marked this as an enhancement, It's something we recognize as a deficiency in the current gem.

[h8rry]

@gordonbisnor good to know that it works for you

After I construct a Message, how do I send it? I am trying to do basic-lti-launch-request. It makes sense when I am testing with http://ltiapps.net/test/tc.php, but I have a very hard time understanding how to use this gem.

All I need is a minimal guideline like this

request = IMS::LTI::Models::Messages::BasicLTILaunchRequest.new({
  launch_url: 'xxx',
  consumer_key: 'xxx',
  consumer_secret: 'xxx',
  resource_link_id: 'xxx',
  custom_user_id: 'xxx',
  ...
})

request.send

I don't mind building up a documentation for this gem from here on.

[gordonbisnor]

@h8rry I haven't used this library for a launch – we're using it for provider functionality.... but what I was working on might also work for your case? I used the library to prepare the message, then rendered it to a Rails view, which I then post to the LMS using javascript, like this:

<form class="hidden-form" encType="application/x-www-form-urlencoded" method="post" action="<%= @return_url %>" id="my-form" >
  <% @form_elements.each_pair do |key,value| %>
    <input type="hidden" name="<%= key %>" value="<%= value %>" />
  <% end if @form_elements.present? -%>
</form>
<script>
  document.getElementById('my-form').submit();
</script>

For my purposes I am not happy with this approach, but the LMS I have been using does not have much in the way of support or documentation and so I'm not yet sure if it's possible to do this server-side or with an ajax request. Would like to be able to get a results of the POST request.

At any rate, you could give this a try. Sorry I can't be more helpful or authoritative, but don't hesistate to ask, if I can provide any further (possibly questionable!!) advice would be happy to...

[ahmadhasankhan]

Hey @gordonbisnor @rivernate, is there a way to pass these parameters in LTI 2.0?

course_navigation[default]
course_navigation[enabled]

https://canvas.instructure.com/doc/api/all_resources.html#method.external_tools.show

[abutterf]

Those values should be returned by the show action for LTI 1.x tools. Is that what you are asking?

[ahmadhasankhan]

Hey @abutterf sorry, I meant in LTI 2.0.
Never mind I got the answer here #148 that it's not feasible.

Thanks for the response

[mrmattnewell]

@gordonbisnor do you think that you could give me a steer as I'm really struggling without any documentation here!

So say I'm wanting to create a content item selection with an LtiLinkItem and I want it to be constructed like the example here:

lti_message_type: ContentItemSelection
    lti_version: LTI-1p0
    content_items: {
                     "@context": "http://purl.imsglobal.org/ctx/lti/v1/ContentItem",
                     "@graph": [
                       {
                         "@type": "LtiLinkItem",
                         "@id": "http://example.com/messages/launch",
                         "url": "http://example.com/messages/launch",
                         "title": "test",
                         "text": "text",
                         "mediaType": "application/vnd.ims.lti.v1.ltilink",
                         "placementAdvice": {
                           "presentationDocumentTarget": "frame"
                         }
                       }
                     ]
                   }

How would you go about that?

I've tried something like:

link = IMS::LTI::Models::ContentItems::LtiLinkItem.new(
        :url => "http://example.com/messages/launch",
        :title => "test",
        :text => "text",
        :placement_advice => {
          :presentationDocumentTarget => "frame"
        }
    )

content_item = IMS::LTI::Models::Messages::ContentItemSelection.new(attrs = {:content_items => link})

But this produces:

#<IMS::LTI::Models::Messages::ContentItemSelection:0x007f80ae493000
 @content_items=
  #<IMS::LTI::Models::ContentItems::LtiLinkItem:0x007f80b09cb908
   @ext_attributes={},
   @placement_advice={:presentationDocumentTarget=>"frame"},
   @text="text",
   @title="test",
   @type="LtiLinkItem",
   @unknown_attributes={},
   @url="http://example.com/messages/launch">,
 @custom_params={},
 @ext_params={},
 @lti_message_type="ContentItemSelection",
 @unknown_params={}>

Which looks all wrong! Any help would be greatly appreciated!

[gordonbisnor]

@mrmattnewell I would be happy to help if I'm able....

This is the high level overview of what I am doing in order to generate an HTML form that we then post to the LMS – not sure if you are trying to accomplish the same thing or not...

First create a new instance of the IMS::LTI::Models::Messages::ContentItemSelection class:

message = IMS::LTI::Models::Messages::ContentItemSelection.new(body)

Then add content items:

message.content_items = []
my_stuff.each do |stuff|
  IMS::LTI::Models::ContentItems::LtiLinkItem.new
end

Then in a view iterating over the keys and values contained in

message.signed_post_params 

Finally we automatically post the form to the LMS using javascript on page load. In my opinion, this is far from ideal as I'm not getting a response code from the server that I can use to confidently update state on my end – instead just hoping that it worked. I couldn't find a way to successfully post to the LMS we are using using an HTTP client. I was never able to find out if this is a limitation of the technology, the particular LMS we are using, or an error or lack of understanding on my part....

If this is enough to get your setup working, great... if not feel free to contact me if you think I might be able to help!

[mrmattnewell]

@gordonbisnor thanks so much for the reply. I'll check out that workflow and see if that works for me.

I guess I was thinking of doing this from a slightly different angle - sending the variables for my custom items into a controller action and then in turn into these classes to construct the item and then do something like:

redirect_to @@launch_params[:launch_presentation_return_url]

To post in the response to the LMS.

If I keep on hitting my thumbs then I might ask for more help!

Thanks

[gordonbisnor]

@mrmattnewell Oh that's an idea, I hadn't thought of that. Still doesn't solve the problem of knowing what the result was but it would eliminate the need for the view and javascript if it works!

[mrmattnewell]

@gordonbisnor ha! I was asking you for help! ;)

[gordonbisnor]

:)

[jnajdi]

I'm trying to figure out how to send scores back to Canvas with the newer version of ims-lti (2.3.0). Our current code is using the old syntax (see below). I'm having hard time finding any documentation that could help with this.

toolProvider = IMS::LTI::ToolProvider.new(consumer_key, consumer_secret, {
"lis_outcome_service_url" => lis_outcome_service_url,
"lis_result_sourcedid" => lis_result_sourcedid,
})
toolProvider.extend IMS::LTI::Extensions::OutcomeData::ToolProvider
res = toolProvider.post_extended_replace_result!(score: score)

[sauderrs]

I too am struggling to understand how to use this gem because there is no documentation. The "about" says that it can be used by both tool providers and tool consumers (maybe it's my lack of context, but that seems like it should be broken up into 2 gems).
Regardless, I'm curious to know if this gem can be used to create an LTI 1.3 tool (provider side). And if so, how?
It seems a shame for otherwise great code to go unused because it's undocumented (if I can't understand it, I'll attempt to "roll my own").

[xandroxygen]

@sauderrs this gem does not support LTI 1.3 and has been in maintenance mode for some time, sadly.

[sauderrs]

Thanks, @xandroxygen ! That's helpful context.
If it's in maintenance mode, it'd be nice if the README called that out.