The API Test Tool: A Developer’s Secret Weapon

The Challenge

Developers want a quick and easy way to try an API call and see the result without having to build code around it. Or, if they’re troubleshooting code from an existing project, they want a chance to try out the API call in isolation to help them narrow down whether the issue is with the call they’re making or how they’ve implemented it in their code.

The Solution

The API Test Tool (based on the Getting Started Sample) is a utility that streamlines the authentication process and allows developers to get down to the business of trying out the Valence Learning Framework APIs.

The Details

The API Test Tool runs in a browser and provides an interface to point to a D2L Learning Environment (LE), supply an App ID/Key pair, and log in with a given user account. Once authenticated, you can make calls using a straightforward interface.

Screenshot of the API Test Tool interface.

By default, this utility points to a sample LE identified in the Host field. You can update this field to point to any LE that is accessible to the API Test Tool. For example, if you’re using the online version of this utility, it must be able to reach your target LE (and vice-versa) without being blocked by an intervening firewall.

The utility uses a default App ID/Key pair that is configured for the sample LE. You’ll need to update these values to match an App ID/Key pair for an app that is registered to your target LE instance. For more information on the App Registration process, check out the FAQs and Best Practices. For environments at 10.3 SP13 or higher, check out the new App Reg Process.

Note: You can use the API Test Tool to help rule out issues with your App ID/Key pair. For example, if your code is giving you a 403 Invalid Token error, you can use the API Test Tool to verify if the App ID/Key is working properly in another context. If the App ID/Key pair is working with the API Test Tool, then you should double-check that you’re using the same App ID/Key pair in your code. If all is well, you can move on to investigate other pieces of the ID/Key Authentication process confident that your App ID/Key is working as expected.

Make a GetVersions Call

At this point, you can click the GetVersions button and then click Submit to receive a Response showing a list of supported API contracts on the target LMS. The GetVersions API call does not require an authenticated user. You’ll need this information to ensure you’re calling an appropriate version of each API route.

Screenshot showing the GetVersions response listing available API Contracts on the target environment.

Authenticate and Experiment with API Calls

Click Authenticate to be redirected to the D2L Learning Environment login screen on the target environment. Log in with your target user account. (If using the sample LE, be sure to make note of the sample user credentials displayed in the API Test Tool interface before clicking Authenticate.) Once authenticated, you’ll be redirected back to the API Test Tool interface. Notice that the User ID and User Key fields are now visible and populated.

Note: You can use the API Test Tool to retrieve user tokens for an application that runs headlessly under a dedicated service account. For more information on designing headless applications, check out this relevant forum post and search for other related posts.
Once authenticated, you can try some pre-configured API calls using the available WhoAmI and Create User buttons. If you’re using the sample account for the sample LE, the Create User call won’t execute successfully: the sample user doesn’t have sufficient privileges to create this type of data. This is a great example of how permissions limit data access via the API.

Now you can try pasting in any other API call that you’d like to test. You’ll need to select the appropriate action by selecting the Get, Put, Post, or Delete radio button. When appropriate, you’ll use the File input mechanism or enter valid data in the Data field and then click Submit to see the Response.

The Sample

The API Test Tool is available online or as a PHP sample. Use the online sample to work with the sample LE or to point to any D2L LE that is visible thru the internet. Use the PHP sample if target environment is located behind a firewall. You can also modify the sample code to extend its capabilities to fulfill your own development and testing needs.

PHP

The API Test Tool for the PHP platform has the same requirements as the PHP client library.

  1. Download the latest version of the API Test Tool and unzip it to a local directory inside your webserver’s document tree.
    Note: In most Unix systems, you can add the contents to /var/www, or create a virtual host; in Windows, you can create a public profile in IIS.
  2. Point a browser to the sample by navigating to http://yourServer/docRoot/util-api-test-tool/index.php.

The Result

This utility is like a Swiss Army knife for developers – whether you’re working with the Learning Framework APIs for the first time or debugging code from an old project. Give it a try – either online or in your own environment. If you’ve got any tips for using this utility or if you’ve extended this utility, add a post in the ValenceUsers forum describing what you’ve achieved.


Making development easier with the Remote Plugins Test Service

The Remote Plugins Test Service was created to facilitate manual testing of Remote Plugins in the Desire2Learn Learning Environment and provide a demonstration of different Remote Plugin types. The service supports four types of Remote Plugins: Widgets, Navbar links, Insert Stuff types, and Quicklink types.

The testing service has proven valuable internally at D2L for verifying the functionality of Remote Plugins and providing a basic starting point for creating new Remote Plugins. It was decided that the testing service would be useful to the developer community as sample code and a working project. It is currently hosted on Valence GitHub account. It is licensed under the Apache 2 open source license. It is currently implemented in C# but additional implementations in other languages are in the works.

Four routes are provided for each of the supported remote plugin types: widget, isfselector, nav, and quicklinksselector. Each route expects an LTI Launch (HTTP POST). The index page will render a splash page with a listing of supported Remote Plugin types. The code for each implementation is meant to be straightforward and minimalist. All error handling scenarios may not be covered.

If using the C# implementation, open the solution and start debugging to launch the IIS development server. It will begin running the service on your local machine. If your machine is accessible from your learning environment you can add the service’s routes as Remote Plugins. Use the Remote Plugins administrative page in the learning environment to add new Remote Plugins.

If you’ve got a GitHub account, you can Watch the Remote Plugin Test Service repo to be notified of improvements and additional language implementations for this test service.


So you want to extend your LMS – Part 2: Remote Plugins

Before diving in, be sure to check out Part 1 to review the basics of creating a tool using the Learning Tools Interoperability (LTI) standard.

The Challenge

You want to provide your users with a learning tool. The user experience should be integrated into the Desire2Learn Learning Environment (LE) user interface, the connection between the LE and your tool needs to be secure and enable rich data manipulation, and your tool needs to be hosted separately from the LE to enable ease of maintenance.

The Solution

The remote plugin service provides you with a framework to integrate an LTI-enabled tool into the LE interface, and allows you to extend beyond LTI through the use of the Valence Learning Framework APIs.

The Details

As of LE version 10.3, there are five types of remote plugins – Widget, Course Builder, NavBar, QuickLink, and the Insert Stuff Framework (ISF). You can use these integration points to deliver a learning tool through the appropriate extension point in the LE interface. Your tool can be a straight LTI-enabled tool that uses an LTI Launch to create a secure connection between the LE and the externally hosted resource – whether it be a widget on your own webserver, or a major third-party content-hosting service. Once your tool moves beyond the capabilities of LTI, the Valence LF APIs can automatically take over to provide the extra functionality you need.

The Sample

We’ve created the Course Builder Remote Plugin Sample (edit: link updated), which provides a handy tool to assist an instructor in building course content. To set it up in your environment, download the sample, edit the config.php file to configure it for your environment, and host the tool on a web server. Then create a new remote plugin using the same process described for the BookWidget sample, this time choosing the Course Builder plugin type.

When you deploy a Course Builder Remote Plugin, you add a custom object to the Course Builder toolbox. To use this custom object, drag it into the appropriate place in the content structure for the course you are building. For the Course Builder Remote Plugin sample, this action causes a popup to appear, which contains a list of available content that is served by the Tool Provider. To populate this list, an LTI Launch occurs so that the LMS can connect to the external tool and retrieve the list of links to the externally-hosted content. In this case, the list includes LTI-enabled links to quizzes that the instructor can choose to include in their course – including the WHMIS quiz we viewed in Part 1 of this series.

LTI is great for connecting to an external resource, but in order to add a quiz to the course content, you need to go beyond the capabilities of LTI. In this case, inserting a quiz involves inserting a new link in the course content. When the student clicks that link, a new LTI Launch will occur so that the student can access the externally-hosted quiz in order to complete that assessment and receive a grade. This sample uses the Valence LTI APIs to insert that quiz link into the course content.

Since this tool is being deployed as a remote plugin, Valence authentication can happen automatically using the credentials of the user currently logged in to the LE. When Valence Authentication occurs, the user may be prompted to allow the application to proceed. But beyond that prompt, the user experience is seamless.

As you can see, there are several touch-points where LTI and Valence are being used. Here’s a summary of the workflow for this sample:

  1. INSTRUCTOR: Drag the custom object into the appropriate location in the course structure.
  2. TOOL: Perform an LTI Launch to the Tool Provider to load a list of available content and present it to the instructor in the Course Builder interface.
  3. INSTRUCTOR: Click checkboxes to insert content into the course, such as the WHMIS quiz.
  4. TOOL: Authenticate with Valence using the session for the currently logged in user. If this is the first use of this tool, prompt the user to allow the tool to proceed. Perform Valence calls to create the necessary LTI links for the content and insert them into the course structure.
  5. STUDENT: Click a link in the course to access the WHMIS quiz.
  6. LINK: Perform an LTI Launch to enable the student to access the quiz. Using LTI, send the grade result from the quiz to the grade book for the course.

The Result

This sample is only one example of how a remote plugin can take advantage of both LTI and Valence to extend the user experience for instructors and students. Give it a try in  your own environment. If you have deployed your own tool using a remote plugin, leave a comment describing how your tool helps your end users.


So you want to extend your LMS – Part 1: LTI Primer

The Challenge

You want to create a learning tool that can connect easily and securely to a learning management system. The connection needs to allow for some context-passing from the LMS to your tool so that you can customize the experience based on the unique user, the role of that user (student versus instructor), and the course where they launched the tool (Biology versus Creative Writing). If your tool offers an assessment, you also need a method to pass back grades for each user.

The Solution

The IMS Global Learning Consortium has created a standard called Learning Tools Interoperability (LTI) to address these needs. Basic LTI is the 1.0 version of the standard, and offers context passing from an LMS (known as the tool consumer in the relationship) to the learning tool (known as the tool, which is created by a tool provider). LTI version 1.1 offers the ability to pass back grades information from the tool to the LMS grade book.

The Details

One of the main goals of the LTI Specification is to enable a seamless user experience. So, in a well-implemented LTI tool, the user simply clicks a link or uses a tool embedded in an iframe in the LMS, with little awareness of whether the tool is being served from an external source, or how the tool is being hooked into their LMS, because the process is not obtrusive.

Context-passing from the LMS to the learning tool occurs through the LTI launch. This launch is an HTTP POST that sends a standard set of information to the LTI-enabled learning tool. The data included in a launch is detailed in the LTI Specification. An LTI Launch can look like the following example:

Array
(
    [launch_presentation_locale] => EN-US__
    [tool_consumer_instance_guid] => 1ed35f2c89ed0exc26we6fw8f50em13a44563a53f
    [tool_consumer_instance_name] => LVU
    [tool_consumer_instance_description] => Lake Valley University
    [tool_consumer_instance_contact_email] => 
    [tool_consumer_info_version] => 10.2.0
    [tool_consumer_info_product_family_code] => desire2learn
    [context_id] => 6609
    [context_title] => Chemistry 100
    [context_label] => C100
    [context_type] => CourseOffering
    [user_id] => 02405492-05f8-495f-b0ad-358e4741768a_169
    [roles] => Student
    [lis_person_name_given] => Bob
    [lis_person_name_family] => McFred
    [lis_person_name_full] => Bob McFred
    [lis_person_contact_email_primary] => 
    [ext_tc_profile_url] => http://localhost:44444/d2l/api/ext/1.0/lti/tcservices
    [resource_link_id] => 1226856900
    [resource_link_title] => WHMIS Quiz
    [resource_link_description] => Level 1 WHMIS Quiz
    [custom_timecreated] => 1371064958 
    [custom_level] => advanced
    [lis_result_sourcedid] => 8d053b33-6f1f-410c-888b-1944226e44d3          
    [lis_outcome_service_url] => http://localhost:44444/d2l/le/lti/Outcome
    [lti_version] => LTI-1p0
    [lti_message_type] => basic-lti-launch-request
    [oauth_version] => 1.0
    [oauth_nonce] => 224535671
    [oauth_timestamp] => 1371064981
    [oauth_signature_method] => HMAC-SHA1
    [oauth_consumer_key] => mykey
    [oauth_callback] => about:blank
    [oauth_signature] => /fjsylvVX435ZnY2D85gmQvDWqU=
    [basiclti_submit] => Launch Endpoint with BasicLTI Data
)

To take advantage of LTI, the tool must be able to receive this POST and parse the data being sent, ignoring anything it doesn’t require. The tool can then provide a contextually-appropriate experience for each user. For example, the tool can use the information from the [lis_person_name_full] field to greet each user by name. The tool can use the [roles] and [context_title] fields to provide an instructor with a list of quizzes and videos that are appropriate to the subject area of a course, and then present students with the content assigned by the instructor. Your tool can also use information populated in a [custom_xyz] field, which can be used to relay static information that can be customized for each LTI link. In this example, the tool can be customized to use the [custom_level] field to identify students of advanced standing and present them with additional content for enrichment.

To ensure the security of the LTI Launch, you can opt to use OAuth 1.0 to sign messages. This protocol requires that the tool provider and the tool consumer establish a key and secret ahead of time, as part of the configuration of the tool. Notice that any fields in the LTI Launch that pertain to this security method are prefixed by [oauth_]. The tool should parse these fields to ensure that the key and secret are valid before providing a user with access to functionality.

To send back grades once a student has completed an assessment in a learning tool, the tool sends an HTTP POST back to the LMS via the URL specified in the [lis_outcome_service_url] field, the payload being a block of XML that contains the grade details.

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns = "http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>51b8cdfc2a7bb</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>8d053b33-6f1f-410c-888b-1944226e44d3</sourcedId>
        </sourcedGUID>
        <result>
          <resultScore>
            <language>en-us</language>
            <textString>0.33</textString>
          </resultScore>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>

We can see that the <sourcedId> value matches the value from the [lis_result_sourcedid] field that was sent as part of the initial LTI Launch. This value is a GUID identifying the gradable object in the LMS. The grade is sent as a decimal value in a <textString>, which is used to update the LMS grade book.

The Sample

To help you get started building your own LTI-enabled tool, we’ve created the LTI Quiz Sample (edit: link updated). This sample uses LTI to enable students to complete an externally-hosted quiz and then sends the final grade back to the course grade book, using similar values for the LTI Launch and the Grades Return that we outlined above. You can download the LTI Quiz Sample (edit: link updated) from our GitHub repository.

To get this sample working in your own environment, you’ll need to run it on a webserver that is accessible from your LMS. (Edit: View the README.md file for full details on how to configure the sample on your webserver.) To implement an LTI-enabled tool in the Desire2Learn Learning Environment, review the following whitepaper: Does Desire2Learn Learning Environment Integrate With..? (Edit: Link updated.) This whitepaper also goes into more detail about the values sent in an LTI Launch.

The Result

Using LTI, we have created an external tool that provides value to instructors and students while also enabling a seamless user experience.

Stay tuned for Part 2 of this post, where we’ll talk about how to integrate your LTI tools into the user interface of the Desire2Learn Learning Environment using Remote Plugins, and how to extend the experience even further using the Valence Learning Framework APIs.


Revisiting the BookList sample with RestSharp

Many of you are already familiar with the BookWidget sample. We’ve updated that sample to show some best practices for using the C# Valence SDK and creating a Remote Plugin Widget. The sample is available on GitHub for download (edit: link updated). It uses Microsoft’s ASP.NET web framework as the basis for the project. Several additional libraries are also used which are described below.

Know Your Platform

It’s important when using any language to be informed about the library options available. There are several excellent libraries available for C# that help relieve some of the tedious work of creating your own OAuth authentication library and handling RESTful HTTP requests.

The sample project makes use of RestSharp for handling Valence requests. Because Valence is a RESTful API, all communication is handled over HTTP. RestSharp makes the process of creating these requests less tedious and, in addition, exposes interfaces that can be used for unit testing.

LTI launch requests can optionally be signed using OAuth 1.0. There are several existing OAuth libraries available for C#; a good option is DevDefined.OAuth. The sample we’ve created makes use of this library to verify the OAuth signature on the LTI launch request.

All of these libraries are available via nuget which is integrated with Visual Studio. You can make use of the package manager built into Visual Studio to easily add packages as dependencies to your project.

There is now an additional Valence SDK package available from nuget that integrates with RestSharp. D2L.Extensibility.AuthSdk.Restsharp implements the IAuthenticator interface provided by RestSharp. You simply supply your ID2LUsercontext to the ValenceAuthenticator class to create an IAuthenticator object. This object is then passed to a RestSharp client object to handle all authentication. You can see how this is handled in the sample project.

Features of the Sample

This sample makes use of the Valence Content APIs to retrieve the list of assigned books from a course the user is enrolled in. After retrieving the list of ISBNs from the the LMS it fetches additional information about the books from the Google Books API. The final view is a grid of book cover thumbnails to show the user which textbooks have been assigned.

The sample makes use of the LTI role field and only allows those with the ‘instructor’ role to add and remove textbooks from the course. All of this functionality is implemented using the existing Valence Content APIs.

Pay attention to the BookController.cs file. It contains a POST handler that takes care of extracting parameters from the LTI launch and verifying the OAuth signature. It also takes care of the initial Valence authentication so that the project can make use of the Valence Content APIs.

Digging deeper you’ll notice the Course.cs file under the models folder. This contains the Valence calls to the LMS implemented using RestSharp. You’ll also notice the project has wrapped up the Google Book API calls and adapts the result to pass to the Razor templates that have been constructed.

Final Thoughts

We hope this project gives a good starting point for working with Valence and creating remote plugins using our C# SDK. The sample is licensed under the Apache 2 License. Feel free to check it out on Github and adapt it for your own purposes.


Diving into Valence with the Course Search sample

The Challenge

Getting your hands dirty with an API can be a daunting task. Where do you start? Experience is a great teacher, but how do you come up with a project that will provide a useful learning experience with real-world application?

The Solution

The Course Search sample provides you with a chance to explore a basic project, and opportunities to dive into the Valence Learning Framework APIs to get the widget running in your environment and extend the base functionality. This sample is a great first project for a developer who is new to the Valence platform. It is also a useful exercise for experienced developers who want to tackle an area of the Learning Framework API they might not have investigated before.

The Course Search sample is a remote plugin. As we saw with the Book Widget sample, remote plugins are easy to deploy. This widget is designed to compile a list of courses and allow users to filter the list by Semester and Department to find a specific course. You can try the online demo of this sample to get a feel for the basic functionality.

The Details

Before the widget can execute searches within your environment, you must complete some configuration. The necessary values are unlikely to change for an organization, so we make them constants for performance reasons. To perform the configuration, copy config.php.sample to config.php and change the values accordingly.

As with any application, the Course Search sample requires an App ID/Key pair and an appropriate User ID/Key pair in order to make calls against your LMS. To provide the application with the appropriate level of access, you must configure it to run under a service account with administrator privileges. By performing these configurations, you have an opportunity to work through the key request process and develop a stronger understanding of the authentication model.

  1. Follow the steps outlined in the App ID/Key pair topic to request a Limited App ID\Key pair for the environment where you will be deploying the Course Search widget. Once approved, the App ID\Key pair will be active in the environment within 24 hours.
  2. In config.php, set  appId and appKey to the values for the App ID\Key pair you receive.
  3. In the Getting Started Sample, update the appropriate fields to point to your LMS and use your App ID/Key pair.
  4. Click authenticate. You will be redirected to authenticate against your LMS. Enter credentials for the service account you configured to run this sample.
  5. When you are redirected back to the Getting Started Sample, note the User ID and User Key values.
  6. In config.php, set  userId and userKey to the values returned by the authentication process.

For the variables outlined below, you’ll need to manually run some API calls to retrieve the appropriate values. As you did above, you can point the Getting Started Sample to your own LMS and then run the necessary API calls.

  1. Set rootOrg to the identifier property returned by GET /d2l/api/lp/1.0/organization/info (See organization info API documentation.)
  2. Set deptOrgType to the Id property returned by GET /d2l/api/lp/1.0/outypes/department (See department API documentation.)
  3. Set semesterOrgType to the Id property returned by GET /d2l/api/lp/1.0/outypes/semester (See semester API documentation.)

If you would like to run the Course Search widget for multiple LMSes, there is an opportunity to extend this sample by creating a more elaborate way to fetch and store these variables across multiple environments.

The Course Search widget uses the Organization Structure Learning Framework APIs to repeatedly walk down the organization structure to compile a list of courses. First, the widget performs a GET to retrieve the list of semesters. Then the widget performs a GET to retrieve a list of departments. You can see how this is done within the index.php file. These values are presented to the user as lists used to filter the courses.

Choosing an option from the list of departments

Choosing an option from the list of departments.

Retrieving the list of courses is a three-stage process in the dept.php file. First, the widget performs a GET to retrieve the available course templates for the department that the user selected using the widget. Course templates are org units that link a course offering to a department. Course templates allow you to configure, store and reuse components of a course, such as quizzes, dropbox folders, and surveys, and then use the components in individual course offerings. For each template, the widget performs another GET to retrieve all of the courses that match the template. Finally, the widget performs a GET to retrieve all offerings for each course. These values are presented to the user in a drop-down list of available courses.

Choosing an option from the list of course offerings.

Choosing an option from the list of course offerings.

Once the user selects a specific course, the user interface displays a Submit button. This button provides an opportunity to extend the sample, as there is currently no functionality attached to it. Perhaps it could be used to copy the data to the clipboard so that the user can paste the information into the school’s enrollment system. There is a wide range of possibilities. Be sure to share your ideas for extending this sample in the comments.

The Sample

To use the Course Search widget in your own environment, you need to deploy it as a Remote Plugin.

  1. Download the current version of the Course Search sample. The sample requires PHP installed on the server where it is running.
  2. Log in to the Learning Environment as an administrator.
  3. Click on the Admin Tools icon and click Remote Plugins.
  4. Click on the New Remote Plugin button and fill out the Launch Point and Name. In this example, the Launch Point is the URL of the running instance of the Course Search sample.
  5. Change the Plugin Type dropdown to Widget.
  6. Add the Org Units that will have permission to run the Course Search widget by clicking the Add Org Units button.
  7. Click Save.

The Result

The Course Search sample is a development exercise that exposes you to key facets of the Valence platform – from application keys & authentication, to retrieving data, to deploying a remote plugin in the LMS. If you experimented with deploying and extending this sample, share your experience in the comments.


Remote plugins & the BookWidget sample

The Challenge

A Desire2Learn Learning Environment administrator can install applications to offer greater functionality or streamline common processes for their users. However, there is some overhead involved in performing software updates to install these applications on the Learning Management System. Logically, reducing this installation overhead can reduce a barrier to adoption of an application.

The Solution

A remote plugin (Note: Link updated to expanded documentation on Remote Plugin Service.) can extend the functionality of the LMS without requiring additional software. The remote plugin object has a rich content connection with the LMS, and provides UI elements that the developer can control. Using the BookWidget as an example, we will introduce some of the functionality that is possible through remote plugins and demonstrate the ease of building and deploying them.

The BookWidget is designed to allow an instructor to select textbooks to associate with their courses. Instructors can search by ISBN, title, or author to locate textbooks, and add or remove textbooks for each course they manage.

An instructor adds books by searching for the ISBN, author, or title.

An instructor adds books by searching for the ISBN, author, or title.

Students are presented with a user-friendly interface to determine which textbooks they need to acquire, including a thumbnail of the cover, and key information such as title and author. Where applicable, the BookWidget also provides students with a link to purchase textbooks from online retailers.

A student views thumbnails of textbooks listed for a course.

A student views thumbnails of textbooks listed for a course.

The Details

Remote plugin widgets are hosted separately from the LMS, which allows them to be enabled without performing software updates to the LMS. They take advantage of the Learning Tools Interoperability (LTI) specification to connect to the LMS. Once connected, the Valence Learning Framework APIs take over to provide interactivity with the LMS. The BookWidget sample is a VisualStudio 2010 project, which is available to download from our public code repository (Note: Moved to GitHub).

A remote plugin widget loads within an iframe embedded in a course homepage. When a student or instructor loads a page that  contains a remote plugin widget, the widget issues an LTI launch request, which results in a POST to the URL configured as the target for the remote plugin widget. The POST contains a set of fields described in the LTI documentation. Once the widget extracts these fields from the POST data, it generates the application context to create the appropriate LTI authorization parameters. The LTI authentication takes place using OAuth, which uses a shared key and secret between the remote plugin and the widget code. The widget then redirects to the generated authentication URL. After authentication is completed, the widget reloads at its launch URL.

Once the LTI launch is complete, the remote plugin widget uses the Learning Framework APIs to perform actions against the LMS. For the BookWidget, this includes retrieving and manipulating information related to the books assigned to a particular course. The BookWidget uses an HTTP POST to the appropriate route to associate a book with a course. It uses an HTTP DELETE to remove a book from a course. And it uses an HTTP GET to retrieve the list of associated books for a course. When we developed the BookWidget, we identified the Learning Framework APIs we needed and then tested them interactively to ensure they behaved as we expected. We performed this interactive testing using the Getting Started Sample. Then we built those routes into the BookWidget application.

Because a remote plugin is hosted separately from the LMS, it does not inherit the look and feel of the course homepage. It is not yet possible to retrieve LMS CSS information using the APIs, so the BookWidget uses a simple design with minimal embellishments to allow it to blend in with the LMS styles. The sample was built using Bootstrap to help make styling easier.

The Sample

Setting up the BookWidget in your own environment demonstrates how easy it is to deploy a remote plugin.

  1. Download the current version of the BookWidget sample (edit: link updated). The sample requires Visual Studio 2010.
  2. Log in to the Learning Environment as an administrator.
  3. Click on the Admin Tools icon and click Remote Plugins.
  4. Click on the New Remote Plugin button and fill out the Launch Point and Name. In this example, the Launch Point is the URL of the running instance of the BookWidget. If running the sample from Visual Studio it will likely be “http://localhost:6371/books“.
  5. Change the Plugin Type dropdown to Widget.
  6. Add the Org Units that will have permission to run the BookWidget by clicking the Add Org Units button.
  7. Click Save.

Once the BookWidget is configured, an instructor can add it to their course homepage and start using it.

The BookWidget on a course homepage.

The BookWidget on a course homepage.

The Result

As we’ve demonstrated, a remote plugin provides LMS users with additional functionality without the overhead of software updates. The BookWidget sample demonstrates how a remote plugin can use LTI and the Learning Framework APIs to offer a rich user experience.

Try the BookWidget sample in your own environment. Share your experience implementing and extending this sample in the comments. If you create your own remote plugins, be sure to let us know. We’d love to feature your work in a future blog post!

Note: This sample has been updated. See the post “Revisiting the BookList sample with RestSharp” for details.


Follow

Get every new post delivered to your Inbox.

Join 40 other followers