Administration Guide - Required Steps

This article walks Moodle administrators through the required steps to connect a Moodle site to PaperScorer. Once these steps are complete, individual teachers at your institution can connect their own accounts and sync grades.

NOTE: This article is for enterprise PaperScorer customers. Moodle connections are configured once by an administrator with Moodle site-administration access, then used by your teachers. If you are a teacher looking to connect your own account, see Connecting Your Account to Moodle instead.

Unlike Canvas, Moodle does not use OAuth. Instead, PaperScorer connects to your Moodle site with a web service token. Steps 1–5 create that token inside Moodle; Step 6 adds it to PaperScorer.

NOTE: Moodle includes a guided wizard that walks through most of Steps 1–5 in one place. If you prefer it, go to Site administration → Server → Web services → Overview and follow the “Enable a service for external systems” path, then use the function list and capability list below to make sure nothing is missed. Otherwise, follow the manual steps.

Step 1: Enable web services in Moodle

  1. Sign in to Moodle as a site administrator.
  2. Go to Site administration → Advanced features, turn on Enable web services, and save.
  3. Go to Site administration → Server → Web services → Manage protocols and enable the REST protocol.
Enabling the Moodle web services.
Enabling the Moodle REST protocol.

Step 2: Create a service account

Create a dedicated Moodle user that owns the token. Grade updates and lookups are attributed to this account, so a purpose-built account keeps the activity easy to identify.

  1. Go to Site administration → Users → Add a new user.
  2. Create a user such as “PaperScorer Sync” with the following values:
    1. Username: papersync
    2. First Name: PaperScorer
    3. Last Name: Sync
    4. Email: paperscorer_sync@noemail.com
    5. Password: Generate a random password for this user.
Creating a new Moodle user.

Step 3: Create a role with the required capabilities

The service account needs a role that grants the capabilities the integration relies on. Missing capabilities are the most common cause of a connection that verifies but returns no data.

  1. Go to Site administration → Users → Permissions → Define roles and add a new role, for example “PaperScorer Web Service.”
    1. Set the short name to paperscorersync
    2. Set the custom full name to PaperScorer Sync
    3. Allow the role to be assigned at the System context.
  2. Set each of the capabilities in the table below to Allow.
  3. Go to Site administration → Users → Permissions → Assign system roles, choose your new role, and add the papersync   account.
Capability Why it is needed
webservice/rest:use Required for any REST web service call.
moodle/user:viewdetails Read user profiles.
moodle/user:viewalldetails Read all user fields.
moodle/user:viewhiddendetails See fields marked hidden.
moodle/site:viewparticipants Enumerate users across the site.
moodle/site:viewuseridentity See identity fields such as email. Do not skip this one — see the note below.
moodle/course:view Read course records.
moodle/course:viewparticipants List course enrolments.
moodle/role:review Inspect role assignments (used to tell teachers from students).
moodle/grade:edit Write grades back to Moodle.
moodle/grade:view Read grades.
moodle/grade:viewall Read grades for all users.

NOTE: moodle/site:viewuseridentity   is easy to miss and essential. Without it, Moodle silently drops the email field from user lookups, so PaperScorer cannot match your students even though the connection looks healthy. If a teacher connects and PaperScorer reports “no matching account,” this capability is almost always the cause.

Creating a new Moodle role.

Step 4: Create an external service and add the functions

  1. Go to Site administration → Server → Web services → External services and click Add.
  2. Give the service a name such as “PaperScorer,” check Enabled, and check Authorised users only.
  3. Save, then open Functions for the new service and add each function in the table below.
  4. Open Authorised users for the service and add the papersync   account.
Function Used for
core_webservice_get_site_info Validating the token when you verify the connection.
core_user_get_users_by_field Matching PaperScorer students to Moodle users by email.
core_course_get_courses_by_field Reading course details.
core_course_get_contents Reading a course’s assignments.
core_enrol_get_enrolled_users Reading course rosters.
core_enrol_get_users_courses Reading the courses a user is enrolled in.
mod_assign_save_grade Writing grades back to a Moodle assignment.
Creating a new Moodle external service

Step 5: Generate a token

  1. Go to Site administration → Server → Web services → Manage tokens and click Create token (or Add).
  2. Set User to the paperscorersync   account and Service to the “PaperScorer Sync” service you created.
  3. Save, then copy the generated token. You will paste it into PaperScorer in the next step.
Creating a new Moodle token.

NOTE: Treat the token like a password. Anyone with the token and your site address can act as the service account. If it is ever exposed, delete it here and generate a new one, then update the connection in PaperScorer.

Step 6: Add the connection in PaperScorer

  1. Sign in to the PaperScorer web app and go to Connections.
  2. Click Add connection.
  3. In the modal, set Type to Moodle.
  4. For Client domain, enter only your Moodle site domain — for example moodle.yourschool.edu  . You do not need to include https://  ; PaperScorer adds it for you.
  5. For Client Token, paste the token from Step 5.
  6. Click Save.
  7. Turn on the connection with the active toggle.
  8. Open the connection’s menu and click Verify. A green Verified label confirms the token and domain are working.
Create a Moodle connection in PaperScorer

What your users should do next

Once the connection is verified, your teachers can connect their own Moodle accounts and begin syncing grades. Point them to Connecting Your Account to Moodle.

Troubleshooting

  1. Verification fails. Confirm web services and the REST protocol are enabled (Step 1), the token belongs to the paperscorersync   account on the “PaperScorer Sync” service (Step 5), and the client domain is your Moodle site address.
  2. An accessexception  error. The function being called is not part of your external service. Add the missing function to the service’s function list (Step 4).
  3. Teachers connect but PaperScorer reports “no matching account.” The service account is missing moodle/site:viewuseridentity   (Step 3). Moodle drops the email field without it, so lookups come back empty even though the user exists.

If you are still stuck after checking these, contact our support team and include your Moodle site address and the name of the external service you created.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us