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)
• 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.
   
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.
   
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.
    
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.
    
19. Click Add service.
20. From the list of External Services, for the service you just created, click Functions.
    
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
    
23. Return to the External Services list and click Authorised users.
    
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.
    
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.
    
28. From the Service drop-down list, select the Echo360 integration external service you just created.
    
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.
    
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.
   
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.
    
13. Click Save.
14. Click Test in the API tab that appears with your new configuration, as identified in the figure below.
    
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.

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.

   
3. From the Use role or archetype drop-down list, select ARCHETYPE: Authenticated user, then click Continue.
   
4. On 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 figure below.
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.

   
   

   Ensure that a default Moodle role is selected when you select the role assignments. Do not allocate a custom role.

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.
    

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.