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

EchoVideo: Adding a REST API Integration for Moodle

Echo360
  • Updated

EchoVideo's REST API integration essentially provides EchoVideo with an LMS / VLE course lookup by Instructor capability. This integration provides two features:

  1. The ability for EchoVideo admins or schedulers to create both EchoVideo sections and connect capture schedules directly to LMS Courses. This is described in Linking an EchoVideo Capture Schedule to an LMS Course.
  2. The ability for instructors to see and use the consolidated Analytics tab from within EchoVideo, which provides viewing and polling response data in one place for all of their LMS-course-related EchoVideo media.

The basic process for API integration is:

  1. Create a Rest API integration in Moodle.
  2. Add a Moodle API configuration in EchoVideo, including the access token provided by Moodle.
  3. Test the configuration.

As with most LMS-to-EchoVideo configurations, you must log into EchoVideo and Moodle as an administrator.

The Moodle API process also requires creating a specific Moodle user that will be granted Administrative privileges (e.g. integration-moodle@institution.edu). 

Configure Web Services and REST API Access

EchoVideo does not need access to all protocols and API access points. The EchoVideo Moodle API integration only uses the REST protocol and two APIs. MoodleDocs contains a Web Services section that details step-by-step Web Services configuration. We strongly recommend you refer to MoodleDocs as needed, as the instructions below are designed strictly as a guide to this configuration. 

Also, note that the instructions below apply across Moodle versions; however, the services you are configuring reside in either of the two following locations:

  • Site Administration Web Services External Services (for newer versions)
    OR
  • Site Administration Plugins Web Services (for older versions)

This means that in ANY of the steps where it states Navigate to Web Services, your actual navigation steps may vary depending on the version of Moodle you are using.

To configure REST API access in Moodle 

  1. Log into Moodle as an administrator and click Site administration from the left navigation.
  2. Search for or navigate to Advanced Features.
  3. Under the Advanced features list, put a check into the box for Enable web services (enabling the use of web services on this installation of Moodle).
  4. Navigate to Web Services and select Manage Protocols.
  5. In the list that appears, enable the REST Protocol (click the eye icon).
  6. On the same page, enable Web services documentation.
    Manage Protocols page of Moodle Web Services containing options and fields for steps as described
  7. Click Save changes.
  8. If you have not already, create a new Moodle user who will be granted administrative privileges.
  9. In user creation, be sure the Email display is set to Hide my email address from non-privileged users.
    new user creation form with new integration user information entered and email display selection set as described
  10. After creating the integration user, navigate to Users Permissions User policies.
  11. Scroll down to Show user identity (showuseridentity) and ensure Email address is enabled.
  12. Navigate to Users Permissions Check system permissions.
  13. Find the user you just created from the list, then click Check User Permissions.
  14. This user MUST, at a minimum, have the following permissions:
    • moodle/webservice:createtoken - for allowing this use to generate a security key
    • webservice/rest:use
    • moodle/site:viewuseridentity - works in conjunction with the showuseridentity policy to allow this user to access email addresses for users who select (or if the institution default is) to Hide their email address.

      Use a Custom Role: Because Moodle assigns permissions to roles and not users by default, you may find it easier to grant Moodle Administrator privileges for this user or create / edit a custom role that provides the necessary permissions. Your institution's policies should guide you in this decision. The section at the bottom of this page provides the procedures necessary to create an integration role with the proper permissions. You may also want to refer to the permissions section of the MoodleDocs for any additional information.

  15. Navigate to Web Services External services.
  16. In the External Services page, below Custom Services, click Add.
    External services list with Add selection below custom services section identified for steps as described
  17. Complete the External Service fields using the information from the Integration user you created.
  18. Enable both the Enabled and Authorised users only checkboxes.
    Add external service dialog box with options for selection identified for steps as described
  19. Click Add service.
  20. From the list of External Services, for the service you just created, click Functions.
    Newly created external service with Functions option identified for steps as described
  21. At the bottom of the functions list, click Add functions.
  22. Add the following functions to the new EchoVideo integration service:
    • core_enrol_get_users_courses
    • core_user_get_users
    • core_enrol_get_enrolled_users
    • core_course_search_courses
    External service functions list with the newly added functions identified for steps as described
  23. Return to the External Services list and click Authorised users.
    newly created external service with Authorised users selection identified for steps as described
  24. Find the new integration user you just created from the list on the right, then click Add to move them to the Authorized users list on the left.
    Authorize users dialog box with user lists shown and integration user added to Authorised users list as described
  25. Navigate to Web Services Manage Tokens.
  26. At the bottom of the tokens list, click Add.
  27. In the Create token form, search for and select the Echo360 integration user you created for this purpose.
    Create token dialog box user search and selection field identified for steps as described
  28. From the Service drop-down list, select the Echo360 integration external service you just created.
    Create token dialog box service search and selection field identified for steps as described
  29. Click Save changes.
  30. When the Manage tokens page appears, the token you just created is shown in the left column; remember, you will only see tokens that you create.
    Manage tokens list with newly create token identified for selection and copy for use in Echo360 as described
  31. Select and copy the token value shown. You will add it to the API configuration in EchoVideo, described in the next section.

Add the Moodle API Configuration to EchoVideo

The instructions below take the token generated in the above section and use it to create the API configuration in EchoVideo.

  1. Log into EchoVideo as an institution-level administrator.
  2. Click the Settings icon in the upper-right corner of the screen.
  3. From the Settings menu, select Institution Settings.

    General settings appears and Basic Info is selected by default.

  4. Click Integration.
  5. From the middle panel, select LMS / VLE.

    The LTI 1.1 tab is selected by default.

  6. Click the API tab.
    EchoVideo LMS configurations page with navigation to page and API tab shown as described
  7. Optionally, toggle on Full Course Roster. When on, it provides the full course roster for Consolidated Analytics. This allows Instructors to see who has not yet watched a piece of media or engaged with polling questions in their LMS course rather than displaying only those users who have.
  8. Click Add Configuration, as shown in the figure above.
  9. In the form that appears, shown below, select Moodle as the LMS Type.
  10. Enter a Name for the configuration.
  11. Enter your Moodle Domain (base URL of your Moodle instance).
  12. Paste the copied API Token generated in Moodle from the above section.
    Add API configuration dialog box with Moodle selected and fields for completion shown for steps as described
  13. Click Save.
  14. Click Test in the API tab that appears with your new configuration, as identified in the figure below.
    LMS Configuration page with API tab shown and Test button for newly added Moodle configuration identified as described
  15. In the popup that appears, enter the email address of a Moodle instructor who is known to be enrolled in one or more courses, then click Search.

If the configuration is successful, the bottom section of the test modal is populated with a list of that instructor's Moodle courses, as shown in the figure below. You can close the dialog box using the X in the top right corner.

You are done! You can now Link your EchoVideo capture schedules to LMS courses. Your instructors will now see an Analytics tab in their main menu navigation, to access their LMS-course related media data.

Test configuration dialog box with moodle email address entered and course list search results showing successful integration as described

Creating an API Integration Role in Moodle

As cited in the procedural steps earlier in this page, Moodle assigns permissions to ROLES and not to users by default. Meaning it can be cumbersome to try and create a dedicated system user for integrations like this one, including the necessary permissions and policy access, without just giving that user an Administrator role.

The following instructions provide the steps necessary to create an EchoVideo integration role, OR you can use these steps to edit an existing dedicated role to have the necessary permissions. You can then assign that role to the integration user you create for the EchoVideo API integration. This can help simplify the configuration for you, and ensure the user has the necessary permissions without over-permissioning the integration user.

As always, these steps are provided as a guide. Your Moodle interface may look slightly different, or the specific navigation location may differ from your version of Moodle. Refer to the Moodle documentation as needed for further clarification.

To create or configure an EchoVideo integration role

  1. As Moodle Admin, log into Moodle and go to /admin/roles/manage.php
  2. Click Add a new role as identified in the figure below.

    If editing an existing Role: find that role in the list and click the Settings icon (on the right side of the row) for that role, then go to step 5.

    Manage roles page with Add new role button identified for selection as described
  3. From the Use role or archetype drop-down list, select ARCHETYPE: Authenticated user, then click Continue.
    Add new role page with specified archetype selected and displayed as described
  4. In the Adding a new role page, enter a Short name and Custom full name for the role (e.g. Echo360 Integration), as shown in the below figure.
  5. In the Context types where this role may be assigned, enable the checkbox for System, also shown in the figure below.

    This is to allow the Role to appear in the Site Administration Users Assign system roles options, so a Moodle User account can be assigned to it.

    Add new role page with name fields completed and Context type System enabled for steps as described
  6. Scroll down to the Capabilities list, and ensure that the following capabilities are set to Allow (the checkbox is enabled) - use the Filter text box at the top to find them in the list if necessary:
    • moodle/course:viewparticipants
    • moodle/user:viewdetails
    • moodle/user:viewhiddendetails
    • moodle/course:useremail
    • moodle/user:update
    • webservice/rest:use
    • moodle/site:viewuseridentity
    • moodle/course:view

    Capabilities 1-5 are specified by the Web Services API functions for core_enrol_get_users_courses and core_user_get_users. The additional capabilities 6-8 are required for the Web Services API functionality to work properly for a manual Moodle capabilities configuration.

  7. Click Create this role or Save changes (as appropriate) to save your Role settings.
  8. Go to Site Administration Users Permissions Assign system roles.
  9. Click on the System role you just created.
  10. From the list of users on the right, select the integration account created / authorised to use the Web Services API Configuration, then click Add to move that user to the left list box, as shown below.
    Assign role to user page with Echo360 integration user added to integration role users list as described

Once complete, this role will allow the integration user for the EchoVideo API integration to function as needed so that the Web Services API configuration for EchoVideo works properly.

Related to