How can we help?

My Cases

Linking LMS Courses/Sections with Echo360 Sections using the API
Last Updated: Apr 27, 2018 11:02AM EDT

This article applies to:  Echo360 Admins

Disclaimer: The instructions on this page provide basic information for how to populate the necessary fields for related objects using Echo360 API calls. The direct linking of LMS courses to Echo360 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 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.
    Finally, because of updates made to the Echo360 public API to streamline this process, the original instructions, using the LMS Reference ID and External ID are no longer needed. They have, therefore, been removed from this page. However, if you still want or need to reference them, please do so using the following link:
ARCHIVED: Linking LMS Courses/Sections with Echo360 Sections using the API

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 three pieces of information:

  • The Echo360 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 (and is described in the below procedure). 
  • The LMS Profile ID of the LTI Profile configured for the LMS. This can be obtained via an LMS-Profile-Id GET call or you can copy it 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 simply copy the LMS Profile ID from the LMS Configuration page, or you can use an API call to obtain it, allowing you to 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 (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. 
    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 Echo360 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 Echo360 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 however, 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 

Alternately, if you wish to re-use an LMS Course and simply link it through to a different Echo360 Section, a GET call for sections will provide the linked LMS Course(s) for each Echo360 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 Echo360 with the exact name of the field you want to use.

Linking an LMS Course to an Echo360 Section

Once you have all three required values (Echo360 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 Echo360 Section

  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}/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 Echo360 section ID into the sectionId field identified in the above figure.
  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 deprecated 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 as you would use if you were performing 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 simply determines whether the LTI links from the identified LMS Course will AUTOMATICALLY direct all users to the Echo360 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 Echo360 section, there can be ONLY ONE Echo360 section linked to that LMS course. Otherwise we have no idea WHICH section you actually want to link to. If multiple Echo360 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 Echo360 section to present to users. There CAN be multiple LMS courses auto-linked to a single Echo360 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 Echo360 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 Echo360 section as a "linked section" selection option. You can select a DIFFERENT Echo360 section to link to, but the LMS Course is already linked to that Echo360 section.
  • If you logged 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, in order 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 into the Echo360 section.
  • If you are logged into the LMS as an administrator or instructor, you will be enrolled as an Instructor into the Echo360 section, UNLESS...
  • If the logged in Instructor DOES NOT EXIST in Echo360, AND your institution features are configured to NOT 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 the new user in Echo360 first.

 

c9f5f1d87ac29bd0c146e9565da3c739@echo360.desk-mail.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete