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

EchoVideo: Linking LMS Courses / Sections with EchoVideo Sections using the API

Brockman Winfrey
  • Updated

The instructions on this page provide basic information for how to populate the necessary fields for related objects using EchoVideo API calls. The direct linking of LMS courses to EchoVideo sections can also be done via Section CSV Import. See Update LMS Course IDs.
Furthermore, these instructions use the Swagger Docs UI to demonstrate the API calls, which is not the best or most efficient method, particularly concerning the Section API calls. However, once you understand the process, fields, and values that need to be used, you can translate that information to write the proper API calls and / or scripts to perform these tasks more efficiently.

To link LMS courses or sections directly to EchoVideo sections without asking the instructor or admin to link them manually, EchoVideo needs you to provide three pieces of information:

  • The EchoVideo Section ID of the section you want to link to.
  • The unique identifier for the LMS Course/Section you want to link from. The location or field for this value differs for each LMS (described in the procedure below).
  • The LMS Profile ID of the LTI Profile configured for the LMS. This can be obtained via an LMS-Profile-Id GET call or copied from the Host URL for the LMS configuration. This value identifies the LMS this particular link-through is coming from. Effectively it tells us that whenever a user comes to us via this LMS ID, and this LMS course, link to this Echo section.

Obtaining the LMS Profile ID

As stated above, you can copy the LMS Profile ID from the LMS Configuration page or use an API call to obtain it. Then, you can use a script to populate that value into the appropriate field for course-to-section linking.

To get the LMS Profile ID

  1. Navigate to the Swagger Docs UI for your region.
  2. If you still need to do so, 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 showing the token populated
  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 EchoVideo institution.

    API Response to GET LMS Profiles call as described

The value in the ID field in the response is the LMS Profile ID you will use in the linking call. It is likely to be the same for every Section ID you are updating, in as much as institutions typically have only one LMS. However, if you do use multiple LMS', be certain you are using the correct LMS Profile ID for each EchoVideo Section > LMS Course you want to link.

Obtaining the LMS Course ID

Besides the LMS Profile ID, you also need the LMS Course ID from the LMS, as well as the EchoVideo Section ID you are linking into. A GET for sections will retrieve all section IDs, from which you can select the ones you want. The LMS Course ID is available from different places in the LMS, depending on the LMS you are using. Guidelines are as follows:

  • Canvas = Use the course or section ID value shown in the URL of the course or section home page. If there are multiple sections within a Canvas course, and each must link to a different Echo Section, use the Section ID; if there is only one section or all sections in the course must link to the same Echo Section, use the Course ID. Just be sure to use the correct ID for each as necessary. For example, in the following URL, the Course ID is 832164; the Section ID is 1874496:
    https://<institutionname>.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.scu.edu/d2l/home/204077

Alternatively, if you wish to re-use an LMS Course and link it to a different EchoVideo Section, a GET call for sections will provide the linked LMS Course(s) for each EchoVideo Section ID returned.

The above field value locations are based on the default Course ID field for each LMS, as listed below:

  • CANVAS = custom_canvas_course_id
  • SAKAI = lis_course_offering_sourcedid
  • MOODLE = context_label
  • BLACKBOARD = context_label
  • DESIRE2LEARN = context_id

If you wish to use the value from a different Course ID Field in the LMS, you must replace the above field name in the Course ID field of the LMS Configuration in EchoVideo with the exact name of the field you want to use.

Linking an LMS Course to an EchoVideo Section

Once you have all three required values (EchoVideo Section ID from a GET sections call, LMS Profile ID from a GET call, and LMS Course ID via the methods described above) you can run the direct linking call via the API.

To link your LMS course to your EchoVideo Section

  1. Navigate to the Swagger Docs UI for your region.
  2. If you still need to do so, 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 showing the token populated
  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 expanded PUT for 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 EchoVideo section ID into the sectionId field, as shown in the figure above.
  7. To the right of the body textbox, click on the Model Schema shown to populate the body with the needed fields.
  8. Replace string with the necessary values for the Body of the call as follows:
    • lmsCourseIds: This field remains as a valid usable field but is being depreciated in preference of the lmsCourses array. Do not begin using the lmsCourseIds field if you do not already. It is optional.
    • lmsCourses: This is the array of values used to identify the LMS course, the LTI profile, and whether or not to auto-link the LMS course to the section. These are the same values you would use if you performed this linking via CSV Import.
      • lmsProfileId: The ID value obtained for the LMS Profile in the Obtaining LMS Profile ID section above.
      • lmsCourseId: The LMS Course identifier obtained in the Obtaining LMS Course ID section above.
      • ltiLinksToSection: A boolean field that accepts true or false as values. This determines whether the LTI links from the identified LMS Course will automatically direct all users to the EchoVideo section (set to true). This field is optional and defaults to false if not present.

        NOTE: To auto-link (ltiLinksToSection=true) an LMS Course to an EchoVideo section, there can be only one EchoVideo section linked to that LMS course. Otherwise, we have no idea which section you want to link to. If multiple EchoVideo sections are linked to an LMS course (a 1:Many relationship), those Echo sections appear as options in the LMS, and an Instructor or Admin will need to manually select the EchoVideo section to present to users. Multiple LMS courses can be auto-linked to a single EchoVideo section (Many:1 relationship).

  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 lmsCourses array you just configured.

To verify that the linking worked, log into the LMS and click on the EchoVideo LTI link established for the course (or if necessary, establish an LTI link in the course). One of the following will happen:

  • If you set ltiLinksToSection to true, the link will place you on the Class List for the linked section. You should not be asked to select which Echo section to link to.
  • If you set ltiLinksToSection to false(or did not set it at all) you should see the identified EchoVideo section as a "linked section" selection option. You can select a different EchoVideo section to link to, but the LMS Course is already linked to that EchoVideo section.
  • If you log in as a student, you are taken directly to the Class List for the Echo section, regardless of the ltiLinksToSection value used. Auto-Linking only applies to Admins or Instructors entering via the LMS to reduce the manual mapping required on the LMS side. If the course and section are linked, Students are always taken to the class list (as long as there are not multiple Echo sections linked to the LMS course).

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 in the EchoVideo section.
  • If you are logged into the LMS as an administrator or instructor, you will be enrolled as an Instructor in the EchoVideo section unless...
  • If the logged-in Instructor does not exist in EchoVideo, and your institution features are configured not to allow automatic instructor provisioning when linking through an LMS, that user will not be able to access the linked section (receiving a User Not Found error). You will need to create a new user in EchoVideo first.

Related to