Moodle API Integration – Roster Exchange Setup

The Roster Exchange API Integration allows Barnes & Noble College (BNC) to pull course information to proactively map LMS courses to their corresponding SIS course(s). This ensures a seamless experience for faculty and students.

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.