Moodle API Integration – Roster Exchange Setup

These instructions were created using Moodle version 3.8. If your institution is using another version the following instructions might be slightly different for your particular version.

https://docs.moodle.org/38/en/Using_web_services

System requirements: Moodle version 3.2 or above

1. Ensure the instance of Moodle is configured to use Web Services.
   • Access Administration > Site administration > Advanced features
   • Check Enable web services then click Save Changes
2. Ensure debugging messages are turned on.
   • Access Administration > Site administration > Development > Debugging
     • Set Debug messages to NORMAL
     • Check Default: Yes for Display debug messages
3. Enable REST protocol.
   • Access Administration > Site administration > Plugins > Web services > Manage protocols
   • Enable REST Protocol then click Save Changes
4. Create an External Service.
   • Navigate to Administration > Site administration > Plugins > Web services > External services
   • Under Custom Services click Add.
     • Name: Barnes & Noble
     • Short name: BNC
     • Check Enabled
     • Check Authorised users only
     • Click Add service
5. Add functions to the External Service.
   • Click Add Functions and search for the following functions to add to the External Service
     • core_course_get_courses
     • core_course_get_courses_by_field
     • core_enrol_get_enrolled_users
     • core_course_get_categories
     • core_course_search_courses
   • Click Add functions
6. Create a specific user for the External Service.
   • Site Administration → Users → Accounts → Add a new user
     • Enter the following information for the user:
       • Username: bnc_api_user
       • Password: Anything…
       • First name: Barnes&Noble
       • Surname: API
       • Email Address: integrations@bncfirstday.com
   • Click Create User
7. Accept Privacy Policies for the user (if necessary):
   • Click on the new Barnes&Noble user and view their profile
     • Under Privacy and policies click Policies and agreements (if this is not present, skip to step 7).
     • Click Accept → Give Consent for all policies and ensure all Responses are set to Accepted
8. Create a new role for the Web Service user:
   • Site administration > User > Permissions > Define Roles
   • Scroll down to bottom and click Add a new role
   • Click Continue (do not change any defaults)
   • Enter the following:
     • Short name: BNCAPI
     • Custom full name: Barnes API
     • Custom Description: Barnes Web Service Integration
     • Context types where this role may be assigned: System
9. Under the permissions at the bottom of the page search for and click ALLOW for the following permissions:
   •  Category

     • moodle/category:viewhiddencategories, See hidden categories

   •  Course
     • moodle/course:useremail, Enable/disable email address
     • moodle/course:enrolreview, Review course enrollments
     • moodle/course:view, View courses without participation
     • moodle/course:viewhiddencourses, View hidden courses
   • User
     • moodle/user:viewdetails, View user profiles
     • moodle/user:viewhiddendetails, View hidden details of users
     • moodle/user:viewalldetails, View user full information
   •  Activities
     • site:viewfullnames, Always see full names of users
     • moodle/site:accessallgroups, Access all groups
   • Web service; REST protocol
     • webservice/rest:use, Use REST protocol
   • Scroll to top and click Create this Roll
10. Add the new role to the created user
    • Site Administration > Users > Permissions > Assign System Roles
    • Click on the Barnes API role.
    • Search and select the user created above (Barnes&Noble API) in the Potential users column and click Add.
11. Authorize the user for the Web Service
    • Administration > Site Administration > Plugins > Web services > External Services
    • Under Custom services, click Authorised users link for Barnes & Noble (the service must have been set as Authorised users only in the Edit link)
    • Search for and select the Barnes&Noble user created in Step 3, and click Add.
12. Create a Token for the Authorised User.
    • Administration > Site Administration > Plugins > Web services > Manage tokens
    • Click Add
    • Select the created user (bnc_api_user) and service (Barnes & Noble)
      • Click on Saves changes
13. Locate the newly created token next to the Barnes&Noble API and provide token along with you Moodle instance base URL to the Barnes and Noble Implementation POC.

For Each New Term

Each term sync is initiated with a click on the BNC Course Material link within a course associated to the upcoming term. In order to pull course and roster information for each new term, please be sure to click on the Course Material link in a course in the upcoming term to initiate the new term sync.