Linking LMS Courses/Sections with Echo360 Sections using the API

Disclaimer: The instructions on this page provide basic information for how to populate the necessary fields for related objects using Echo360 API calls. Currently this process works best when CREATING new sections in Echo360 via the API. The Public API currently does not have PUT functionality for updating multiple sections at once, though this is expected to be added very soon.
Furthermore these instructions use the Swagger Docs UI to demonstrate these actions, which in many cases is not the best or most efficient method, particularly with respect to the Section API calls. However, we believe that once you understand the process, fields, and values that need to be used, that you can translate that information in order to write the proper API calls and/or scripts to perform these tasks more efficiently.

In order to link LMS courses or sections directly to Echo360 sections, without asking the instructor or admin to manually link them, Echo360 needs you to provide two pieces of information:

Once Echo360 has this information, users clicking an LTI link in their LMS section are automatically routed to the Class List for their Echo360 section

Technical Details: Echo360 communicates with LMS via LTI (Learning Tool Interoperability). When a user clicks an LTI link configured to communicate with Echo360, the LMS sends an "LTI payload" containing a series of fields and values, to let Echo360 know who is clicking the link, where they are coming from, what they are hoping to get in return, among other things. Within this LTI payload is a field that identifies the LMS course they are clicking from. However, different LMS' use different fields to hold this information. Or rather, values for some fields are easier to obtain from the LMS than others. So Echo360 needs to be told what field you want us to look at for each LMS. This is expected to be a static value and established only once for your LMS configuration.

Background

If you previously used the EchoSystem (ESS) and have or are migrating to the Echo360 active learning platform, AND you used the External System Id field to directly link LMS sections to ESS sections, you understand the linking process to some degree. The part that is different is the need to manually identify what field the LMS must use to find the LMS course/section value to equate to the Echo360 section.

If you are a customer new to this process, this background should provide some insight as to why these instructions have you configure the system in this way.

In the ESS, the only thing an Admin had to do was to enter the course/section value from the LMS into the Section configuration on the ESS, into the External system id field. When a user clicked on an LTI link from the LMS section identified with that value, the ESS section page would automatically appear.

The reason this worked was because the ESS hard-coded the reference field to look for, for each LMS. Then we told Admins how to obtain the LMS course/section value that corresponded to that field.

This is both good and bad. Good because it eliminated the need for the extra step of identifying the LMS field to get the value from. Bad because if the LMS ever changed where it maintained that information, the entire setup would break down.

It would be ideal if we could look at the same field for all LMS', such as "context_id", which contains a unique UUID for each course/section. However, depending on the LMS, it may be very difficult for LMS Admins to obtain that value for each course. So we are allowing admins the flexibility to identify which field will contain the value to link.

The below instructions let you create your setup using the same fields the ESS used. That allows us to give you accurate end-to-end procedures that will work to link your LMS sections to Echo360 sections. You can change these as needed based on your ability to find the values passed by your LMS.

Identifying the LMS Reference ID Field

The instructions below provide steps to enter the external system reference ID that corresponds with the course/section identifier value (external system id) requested for each LMS in the procedures later on the page.

NOTE: A Field has been added to the LMS Configurations page that allows you to enter the Course ID Field name into the UI of the LMS profile, instead of using the API and the below instructions to do this. See Configuring LMS Integration for additional information.

  1. Navigate to the Swagger Docs UI for your region (https://<echo360URL>/api-documentation).
  2. If you have not done so already, generate an access token to authorize you to make API calls, and paste that value into the access token field at the very top of the page.
    Swagger docs UI showing access token in field as described
  3. Click lms-profiles to list the available operations, then select GET lms-profiles operation to expand it.
    Swagger docs showing GET all lms profiles operation as described
  4. Scroll down (if necessary) to access the Try it out! button, and click it.
    The Response Body lists the LMS configurations set up for your Echo360 institution.
  5. Copy the UUID from the "id" field in the response for the LMS to which you want to add the reference field.
  6. Click the PUT  operation for the /public/api/v1/lms-profiles/{lmsProfileId} endpoint.
    PUT lms profile operation expanded in swagger as described
  7. Scroll down to see the parameters needed to run this call.
    put LMS profile operation parameters for steps as described
  8. Paste the copied id value into the lmsProfileId field.
  9. To the right of the body textbox, click on the Model Schema shown there to populate the body with the needed fields. Replace string with the copied values, but leave the quote marks.
  10. Return to the GET call to copy and past the corresponding fields into the body of the PUT call.
  11. Delete the ltiCartridge parameter if you are not using it (it is optional).
  12. Enter the following for the courseIDField value, depending on the LMS you are updating:
  13. NOTE: You can use whatever field you want; if you know the name of the field in the LTI payload and know how to get the field value for each LMS course/section, use that one instead of those identified above. Those shown here are known to correspond to the LMS course/section values identified in the Section API procedure below.

  14. Click Try it out! located at the bottom of the PUT panel.
    If the values and access token are all valid, you will see a 200 response confirming a successful call.
  15. To verify that the update took place, run the GET call for the lms-profiles. The response will include the externalSystemRefId you just added for your LMS.
    List of LMS profiles from GET api call as described

There! Your LMS is configured to use the identified field. This field corresponds with the course/section values requested from each LMS in the instructions below.

Linking the Echo360 section to the LMS course/section

The instructions below provide steps to enter the external system ID value, which is the value that  identifies the specific LMS course/section that you want to link to. This is also the value that appears in the LTI payload in the field added to the LMS profile above.

Before performing the following steps, you must have already created the LMS and Echo360 sections (you need the ID number for both). The Echo360 Section identifier is available from the URL of the section class list, or from the URL if viewing the section details from the Courses page as an administrator.
We also recommend that you add the LTI link to Echo360 into your LMS course, so that you can log in and click the link once configuration is done, to ensure the LMS-to-Echo section linking worked.

  1. Navigate to the Swagger Docs UI for your region (https://<echo360URL>/api-documentation).
  2. If you have not done so already, generate an access token to authorize you to make API calls, and paste that value into the access token field at the very top of the page.
    Swagger docs UI showing access token in field as described
  3. Click sections to list the available operations.
  4. Click the PUT  operation for the /public/api/v1/sections/{sectionId}/external_id endpoint.
    Swagger docs showing PUT section external id operation as described
  5. Scroll down to see the parameters needed to run this call.
    PUT section external id operation parameters for steps as described
  6. Paste the Echo360 section identifier (pulled from the URL for the section) sectionId field.
  7. To the right of the body textbox, click on the Model Schema shown there to populate the body with the needed fields.
  8. Replace string with the LMS course/section identifier values, but leave the quote marks.
    For each LMS, this value is available as follows:
  9. NOTE: If you are using a different field value for your LMS profile than those listed in the LMS Profiles API procedure above, be sure you enter the corresponding course/section value here. Those shown here are known to correspond to the LTI payload field name identified in the LMS Profile API procedure earlier on this page.

  10. Click Try it out! located at the bottom of the PUT panel.
    If the values and access token are all valid, you will see a 200 response confirming a successful call.
  11. To verify that the update took place, run the GET call for the section id. The response will include the externalSystemId you just added to the section.

To verify that the linking worked, go to the LMS (logging in as an instructor or student for the course) and click on the Echo360 LTI link established for the course. The Echo360 section should appear, with the Class List showing. You should not be asked to select which Echo section to link to. If you see that selection page, something went wrong with the linking.

Final note - when you click the LTI link in the course to test the direct linking, one of the following will happen:

Remember, that these steps are designed to provide basic information on how and where these values reside; if you use the Echo360 API to create sections, you can include the LMS section identifier in the external system id field of the POST call, for each new section.