Troubleshooting Issues

Below is troubleshooting guidance for Brightspace integrations, including common issues that may arise during setup or synchronization.

Missing Users or Enrollments

• Issue: Some users or enrollments are not appearing in Edlink.
• Potential Resolutions:
  • Determine if you are digesting historical data- This can be changed when you click Adjust Settings in the Configure Your Sync page
  • Ensure that the Brightspace API user has the necessary permissions to access enrollment data (users:userdata:read, enrollment:orgunit:read`).

Course Offerings Not Syncing

• Issue: Brightspace course offerings are not showing up in Edlink.
• Potential Resolutions:
  • Check if the Brightspace OAuth application has access to course data (orgunits:course:read).

Assignment or Submission Data Missing

• Issue: Assignments or submissions are failing to create in Brightspace.
• Potential Resolutions:
  • Check if the Brightspace API has permission to access assignment and submission endpoints (dropbox:access:read, dropbox:folders:*).

Role Mapping Errors

• Issue: User roles appear incorrect or do not reflect properly in Edlink.
• Potential Resolutions:
  • Ensure any special Brightspace roles are mapped to an Edlink-compatible Role

API Connection Errors

• Issue: The sync fails or does not start due to API connection issues.
• Potential Resolutions:
  • Verify that the Brightspace API credentials (Client ID, Secret, URL) are correctly entered in the Edlink configuration.
  • Ensure the Brightspace API is not experiencing downtime by visiting the Brightspace status page or contacting their support.
  • Re-authorize the API connection through Edlink if the issue persists.

Skipped Session

• Issue: Sessions (Semesters) were skipped while enumerating via the school’s org unit descendants, usually due to a 403 response when listing Semester OUs or their children (Course Offerings).
• Potential Resolutions:
  • Grant the integration user permission to view Org Unit structure and Semester OUs under the target school.
  • If using a restricted root_ou_id, verify it’s correct and that the API user has access to that OU and its descendants.
  • Confirm Semesters actually exist under the school and aren’t archived/hidden from the integration user.
  • Re-run after updating Brightspace role permissions or OU scoping.

Hard Error Session

• Issue: Fetching Semesters failed due to network/API errors (non-403), e.g., 5xx, bad URL, expired token, or rate limiting.
• Potential Resolutions:
  • Confirm the Brightspace base URL, OAuth credentials, and token validity; re-authorize if needed.
  • Check Brightspace status and any IP allowlisting/firewall policies.

Skipped Course

• Issue: One or more Course Templates (or their offerings) were skipped due to 403/404 when listing children under a Course Template.
• Potential Resolutions:
  • Ensure the integration user can view Course Template OUs and their child Course Offerings.
  • Expand OU access if the user is restricted to specific org units.
  • Validate that the Course Template still exists (404 can indicate deletion or wrong OU scope).

Hard Error Course

• Issue: Errors fetching Course Templates caused by network/API issues (timeouts, 5xx, misconfiguration).
• Potential Resolutions:
  • Verify base URL and OAuth token freshness

Skipped Class

• Issue: Specific Course Offerings were skipped while fetching details (403 or 404).
• Potential Resolutions:
  • Grant the integration user permission to view Course Offering OUs.
  • Confirm the offering exists and isn’t deleted/archived.
  • Ensure the user’s OU scoping includes offerings under their Course Templates and Semesters.

Hard Error Class

• Issue: Non-permission errors when fetching Course Offerings (e.g., network or Brightspace API errors).
• Potential Resolutions:
  • Verify /orgstructure/{courseTemplate}/children and /courses/{offeringId} calls and tokens.

Skipped Enrollment

• Issue: Enrollment lists for a class were skipped due to a 403 or missing endpoint while calling /enrollments/orgUnits/{classId}/users.
• Potential Resolutions:
  • Ensure the integration user can view enrollments for the Course Offering OU.
  • Confirm the class OU is within the user’s scope and not deleted.
  • If using OU restrictions, include all relevant sections where enrollments live.

Skipped Enrollment Missing Role

• Issue: Enrollment records were ignored because no Brightspace role mapped to an Edlink role.
• Potential Resolutions:
  • Review your role mappings and add missing Brightspace roles.
  • Map any custom roles to Edlink-compatible roles and re-run the sync.

Hard Error Enrollment

• Issue: Enrollment fetch failed due to network/API issues (timeouts, 5xx, token errors).
• Potential Resolutions:
  • Re-authorize the connection; verify tokens and base URL.
  • Check Brightspace status

Skipped User

• Issue: Users for the school OU were skipped due to a 403/404 when calling /enrollments/orgUnits/{schoolId}/users.
• Potential Resolutions:
  • Grant the integration user permission to view users for the School (or configured root) OU.
  • Verify the root_ou_id selection and OU scoping.
  • Confirm the endpoint exists for the target OU in your Brightspace environment.

Hard Error User

• Issue: Non-permission errors while fetching users for the organization (network/API failures).
• Potential Resolutions:
  • Check authentication and base URL; re-authorize if necessary.

Hard Error District

• Issue: Fetching /organization/info failed; district metadata could not be retrieved.
• Potential Resolutions:
  • Verify Brightspace base URL and OAuth credentials.
  • Ensure the integration user can access the Organization Info endpoint.

Hard Error School

• Issue: Fetching school metadata via /organization/info or /orgstructure/{root_ou_id} failed.
• Potential Resolutions:
  • Validate the configured root_ou_id (or remove it to use the default organization root).
  • Confirm the integration user has access to the school OU.
  • Re-authorize and retry after checking service status and logs.

Notes on 403 “Permissions”

Most Brightspace skips/failures with 403 mean the API user lacks access to the specific Org Unit. Grant view permissions for the relevant OU types (Organization, School, Course Template, Course Offering, Semester) and retry.