Skip to main content
Echo360 Status: 

Adding a REST API Integration between Echo360 and Moodle

Echo360
  • Updated

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

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

The basic process for API integration is:

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

As with most LMS-to-Echo360 configurations, this requires that you are able to log into Echo360 and Moodle as an administrator.

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

Configure Web Services and REST API Access

Echo360 does not need access to all of the protocols and API access points. The Echo360 Moodle API integration only uses the REST protocol and two APIs. MoodleDocs contains a Web Services section that details step-by-step configuration of Web Services. 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)

Meaning 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 either 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 Echo360 integration service:
    • core_enrol_get_users_courses
    • core_user_get_users
    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 Authorised 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 be adding it to the API configuration in Echo360, described in the next section.

Add the Moodle API Configuration to Echo360

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

  1. Log into Echo360 as an institution-level administrator.
  2. Click the Settings icon in the top right of the main menu bar, then select Configurations, as shown in the below figure. The LMS Configurations tab is shown by default. 
    LMS Configurations page with API tab shown and navigation to the page identified as described
  3. In the main panel of the page, click the APIs tab, as identified in the above figure.
  4. Click Add.
  5. In the form that appears, shown below, select Moodle as the LMS Type.
  6. Enter a Name for the configuration.
  7. Enter your Moodle Domain (base URL of your Moodle instance). 
  8. Paste the copied API Token generated in Moodle from the above section.
    Add LMS configuration dialog box with Moodle selected and fields for completion shown for steps as described
  9. Click Save.
  10. In the API tab that appears with your new configuration, click Test as identified in the below figure.
    LMS Configuration page with API tab shown and Test button for newly added Moodle configuration identified as described
  11. In the popup that appears, enter an email address for a Moodle instructor 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 below figure. You can close the dialog box using the X in the top right corner.

You are done! You can now Link your Echo360 capture schedules to LMS courses. And your instructors will now see an Analytics tab in their main menu navigation, to access to 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 Echo360 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 Echo360 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 Echo360 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 below figure.

    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 role (e.g. Echo360 Integration), as shown in the below figure.
  5. In the Context types where this role may be assigned section, enable the checkbox for System, also shown in the below figure.

    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/authorized 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 Echo360 API integration to function as needed so that the Web Services API configuration for Echo360 works properly.