Chat with us, powered by LiveChat Skip to main content
Echo360 Status: 

ARCHIVED: Linking LMS Courses/Sections with Echo360 Sections using the API

Echo360
  • Updated

Disclaimer: The instructions on this page may still work but have been made obsolete by updates to the Echo360 API. Please refer to the following article for updated instructions: Linking LMS Courses/Sections with Echo360 Sections using the API. This archived page is being retained for reference purposes only, and will be removed in the near future.
An Echo360 Engineer developed the attached document to assist LMS admins in using the API to link LMS Courses to Echo360 Sections: Using Public API to Map LMS Course To Echo Section

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:

  • The name of the field, or reference identifier, that contains the course/section ID value. Each LMS uses a different field.
  • The LMS course/section id, previously referred to as the External System ID and now referred to as an LMS Course ID. This identifies the particular course/section to link directly to Echo360.

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.

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.

  1. Navigate to the Swagger Docs UI for your region (https:///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 stringwith 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:
    • CANVAS = custom_canvas_course_id
    • SAKAI = lis_course_offering_sourcedid
    • MOODLE = context_label
    • BLACKBOARD = context_label
    • DESIRE2LEARN = context_id
  13. 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.
  14. 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.

NOTE: The lmsCourseIds shown in the image above remains as a valid usable field but may be deprecated in the near future in preference of the lmsCourses array. Do not begin using the lmsCourseIds field if you do not already.

For each LMS, this value is available as follows: 

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.

  1. Navigate to the Swagger Docs UI for your region (https:///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}/lms-course-ids endpoint.
    Swagger docs showing PUT section lms course ids operation as described
  5. Scroll down to see the parameters needed to run this call.
    PUT section lms course 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 for the lmsCourses parameter with one or more LMS course/section identifier values, but leave the quote marks. This is an Array-type data field and can accept multiple values.
    • CANVAS = Use the course or section ID value shown in the URL of the course or section home page. For example, in the following URL, the section number is 1874496
      https://.instructure.com/courses/832164/sections/1874496
    • MOODLE = Use the Course Short Name, available on the Edit Settings page for the course.
    • BLACKBOARD = Use the Course ID, available on the course properties page (Customization > Properties).
    • SAKAI = Use the Provider ID for the section shown in the My Workspace > Realms page for each section.
    • D2L = Use the course or section ID value shown in the URL of the course or section home page. For example, in the following URL, the section number is 204077
      https://riverland.ims.mnscu.edu/d2l/home/204077
  9. 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.
  10. 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:

  • If you are logged into the LMS as a student, you will be enrolled as a student into the Echo360 section.
  • If you are logged into the LMS as an administrator or instructor, you will be added to the Echo360 section as an instructor, UNLESS...
  • If your institution features are configured to NOT allow automatic instructor provisioning when linking through an LMS, AND you are logged into the LMS as a user who does NOT exist in Echo360, you will not be able to access the linked section.

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.