Echo360's REST API integration essentially provides Echo360 with an "LMS/VLE course lookup by Instructor" capability. This integration provides two features:
- 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.
- 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:
- Create a Rest API integration in Moodle.
- Add a Moodle API configuration in Echo360, including the access token provided by Moodle.
- 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. firstname.lastname@example.org).
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)
- 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
- Log into Moodle as an administrator and click Site administration from the left navigation.
- Search for or navigate to Advanced Features.
- 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).
- Navigate to Web Services and select Manage Protocols.
- In the list that appears, enable the REST Protocol (click the "eye" icon).
- On the same page, enable Web services documentation.
- Click Save changes.
- If you have not already, create a new Moodle user who will be granted administrative privileges.
- In user creation, be sure the Email display is set to Hide my email address from non-privileged users.
- After creating the integration user, navigate to Users > Permissions > User policies,
- Scroll down to Show user identity (showuseridentity) and ensure Email address is enabled.
- Navigate to Users > Permissions > Check system permissions.
- Find the user you just created from the list, then click Check User Permissions.
- This user MUST, at a minimum, have the following permissions:
- moodle/webservice:createtoken - for allowing this use to generate a security key
- 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.
- Navigate to Web Services > External services.
- In the External Services page, below Custom Services, click Add.
- Complete the External Service fields using the information from the Integration user you created.
- Enable both the Enabled and Authorised users only checkboxes.
- Click Add service.
- From the list of External Services, for the service you just created, click Functions.
- At the bottom of the functions list, click Add functions.
- Add the following functions to the new Echo360 integration service:
- Return to the External Services list and click Authorised users.
- 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.
- Navigate to Web Services > Manage Tokens.
- At the bottom of the tokens list, click Add.
- In the Create token form, search for and select the Echo360 integration user you created for this purpose.
- From the Service drop-down list, select the Echo360 integration external service you just created.
- Click Save changes.
- 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.
- 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.
- Log into Echo360 as an institution-level administrator.
- 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.
- In the main panel of the page, click the APIs tab, as identified in the above figure.
- Click Add.
- In the form that appears, shown below, select Moodle as the LMS Type.
- Enter a Name for the configuration.
- Enter your Moodle Domain (base URL of your Moodle instance).
- Paste the copied API Token generated in Moodle from the above section.
- Click Save.
- In the API tab that appears with your new configuration, click Test as identified in the below figure.
- 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.
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
- As Moodle Admin, log into Moodle and go to
<Moodle Host URL>/admin/roles/manage.php
- 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.
- From the Use role or archetype drop-down list, select ARCHETYPE: Authenticated user, then click Continue.
- 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.
- 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.
- 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:
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.
- Click Create this role or Save changes (as appropriate) to save your Role settings.
- Go to Site Administration > Users > Permissions > Assign system roles.
- Click on the System role you just created.
- 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.
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.