cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 
arunkottol
Community Participant

Using the Canvas External Tools API

Jump to solution

I am trying to understand the basic workflow involved in using the Canvas External Tools API (primarily POST /api/v1/courses/:course_id/external_tools).

Can someone point me to a documentation with actual steps to get started and implement such a flow? 

Any help would be highly appreciated. Thanks.

1 Solution

Accepted Solutions
chofer
Community Coach
Community Coach

Hello there,  @arunkottol ...

I noticed that there hasn't been any new activity in this thread for quite a while, and so I thought that I would check in with you.  It looks as though you have received some good help from both  @James ‌ and  @dwahl_sales ‌.  Did any of their responses help to answer your question?  Or, are there still any outstanding questions you have as it relates to your original question?  If you feel that one of the above responses has helped to answer your question, please feel free to mark it as "Correct".  However, if you still have some questions that need answered, please let us know by posting a message below so that members of the Canvas Community can continue to help you.  For now, I am going to mark your question as "Assumed Answered" because we've not seen any new activity in this particular topic since July 11th.  However, that won't prevent you or others from posting additional questions/comments related to this topic below.  I hope that's okay with you, Arun.  Looking forward to hearing from you soon!

View solution in original post

8 Replies
James
Community Champion

 @arunkottol ,

Can you please provide more information about what you're trying to accomplish?

Are you asking about how to use the API in general, what specific information you need to send to create an external tool within Canvas, how to write an external tool that can be called from Canvas, or something completely different?

I am unclear because I normally interpret "workflow" as a multistep process, while using the API to create an external tool in Canvas is basically one step -- with example cURL commands to do so given in the documentation. You may be using "workflow" in a different manner or you may be referring to the process of using an LTI with Canvas, which could involve multiple steps.

If you're talking about what information to send, external tools differ depending on what you want them to do. It's hard to provide the right information without knowing what you're trying to do. The bottom of the API documentation menu has an entire section (10 separate pages) on External Tools, which illustrates how complex things can be.

arunkottol
Community Participant

James,

I guess that was indeed a vague question.

What I would like to do is to use the External Tools API to create an LTI App in Canvas Course by calling  the above mentioned API. Correct me if I am wrong, however what I understand is that to use this API, an Authentication token is required. There is a Oauth 2 flow as mentioned here. The auth token then allows me to make API calls into the Canvas instance and perform operations.

As a tool provider, the idea is to avoid having to publish an app XML, instead install the LTI app using the API. I am looking for some clear cut information/documentation on what needs to be done to achieve this requirement.

Hope this clarifies what I am looking for. Thanks.

- Arun

James
Community Champion

Thank you, it clarifies what you're trying to do, but I'm not sure about the why. While it is not always necessary to know why in order to answer the question, it sometimes leads to a better or simpler answer.

There are three ways to add an external app (LTI) to a course. All of them originate from the Settings page and can be added by an instructor at the course level or an administrator once for the entire site but for use in the course. These are links to the Canvas Instructor's Guide

You don't have to publish an XML file that people can copy/paste, you can provide a link that will supply that configuration information. 

There is no OAuth 2 workflow, no access tokens, and no API calls involved with installing an external app this way. That is the preferred way of installing Apps, especially if your tool doesn't need access to the internals of Canvas. 

Some LTIs may need to access to the API as the instructor to obtain information from the Canvas API that can't be exposed through the custom variables. For example, if you're writing an attendance tool, it would need access to a list of the students in a course. Others may want to install the tool for the user as a convenience -- although here I would be suspicious if things just started popping up on my course menu and I wasn't expecting it.

If you still want to install your LTI through the API, then you will need access. If you are running an application that is used by multiple users then it is against the Canvas Terms of Service to ask someone to generate an access token for you and you are required to use the OAuth 2 workflow.

Here is the link to the documentation on how to use OAuth 2 with Canvas. You are going to want to find a library that will do this for whatever programming language your tool is written in. You will find the work by  @garth ‌ useful. He has written several blogs on how to accomplish this. Although they use .NET as the programming language, the explanations apply to other languages.

If you already have the OAuth part working and are ready for the API portion of actually installing the LTI app, then there are a different set of resources, but it is a simple API call that can be accomplished with a REST library or cURL for whichever programming language you're using. Knowing the specifics of which parameters need sent depends on what your LTI is supposed to do.

Hello  @arunkottol ‌,

I'm going to be a bit of a pedant here, but it's only to help with clarity Smiley Happy If you are trying to create an LTI tool, meaning create a placement within an account or a course then you use the Create an External Tool method which does not require any OAUTH workflow (aside from the obvious API authentication token, which isn't related to the LTI launch authentication).  You can see the examples listed in the linked method.

If you are trying to launch an LTI tool (which already has been created) then you will have to go through the LTI OAuth workflow using the Sessionless Launch method.

From what you have described, it sounds like you're trying to do the first, and the linked method should work for you.

arunkottol
Community Participant

Hi James,

Thank you for the information and I understand that  providing a simple URL can serve the purpose. When the APP XML is standard then obviously this the best route to follow. However, sometimes, there are additional / custom parameters that are specific to a tool consumer. For example, a unique id may be given to tool customer which is sent in a LTI request as a custom parameter. 

The idea of being able to create the app automatically is to take away the complexity (knowledge of such custom parameters) from Instructors and Admins and do it for them automatically.

Thanks for the response again. I guess the initial approach would be to provide a simple URL for adding the APP.

- Arun

arunkottol
Community Participant

Danny,

Thanks for your input on this. I indeed am trying to create a LTI tool placement in a Course / Account. I would like to use the "Create External Tool API" to configure apps for Tool Consumers. The idea to be able to fine tune the apps without Instructors / Admins having to get this information in advance in order to use the tool. I have the following question:


How does the tool provider get the authentication token in order to use the external tools API?

Thanks again for your input.

- Arun

James
Community Champion

You can include the custom variables to include in the XML that you generate -- the person installing the external tool never needs to look at them. The page on your server that generates the XML file could add your unique ID as a custom variable to the generated file. In other words, don't serve a static configuration file, but customize it for the particular instance.

However, there is already a built-in mechanism for sending a unique ID -- it's called the consumer key which, together with the shared secret, must match before you'll accept their LTI launch into your provider. If you need an extra layer of security, then you can add that as a custom variable, but you might be able to get the information from one of the existing variables instead of creating your own.

What you can't do, outside of the OAuth route, is use the Canvas API as that person. This means that you can't automatically enter the consumer key and shared secret for someone. But asking someone for permission to your Canvas account if that's the only thing that you need it for should raise security concerns for people.

It's much simpler to provide the consumer key and shared secret somewhere and then let them add it themselves. They just need to put in the name, the consumer key, the shared secret, and the URL and you can set everything* else they need through the configuration file that you custom generate for them.

* - there may be something else that you can only set through the API, but I haven't seen it yet in your posts. I just want to leave that disclaimer in there.

chofer
Community Coach
Community Coach

Hello there,  @arunkottol ...

I noticed that there hasn't been any new activity in this thread for quite a while, and so I thought that I would check in with you.  It looks as though you have received some good help from both  @James ‌ and  @dwahl_sales ‌.  Did any of their responses help to answer your question?  Or, are there still any outstanding questions you have as it relates to your original question?  If you feel that one of the above responses has helped to answer your question, please feel free to mark it as "Correct".  However, if you still have some questions that need answered, please let us know by posting a message below so that members of the Canvas Community can continue to help you.  For now, I am going to mark your question as "Assumed Answered" because we've not seen any new activity in this particular topic since July 11th.  However, that won't prevent you or others from posting additional questions/comments related to this topic below.  I hope that's okay with you, Arun.  Looking forward to hearing from you soon!

View solution in original post