Admin User Guide

Complete reference for the middleware admin panel

Overview

The middleware connects Blackboard Learn Ultra (elearn.oc.edu.sa) to the NELC LRS using xAPI statements. Blackboard does not send xAPI natively — this service polls Blackboard, builds statements, queues them in an outbox, and dispatches to NELC.

Blackboard REST API → Poller → Outbox → Dispatcher → NELC LRS → integration.nelc.gov.sa

Authentication

When ADMIN_TOKEN is set in .env, enter it in the top bar and click Save. The token is stored in your browser local storage. Use a strong value in production — never commit .env to git.

Dashboard

Shows company summary, live stats, and system configuration.

Stat	Meaning
Outbox pending	Statements waiting to send
Outbox sent	Successfully delivered to LRS
Dead letter	Failed permanently (400/422) — needs review
Journeys	Learner×course progress tracked
Quarantine	Learners missing valid National ID
NELC / Blackboard	Credentials configured
Worker	Background poller + dispatcher running

The header badge shows the active LRS environment (e.g. STAGING).

Company Settings

Organization profile for branding and NELC metadata.

Logo — upload PNG/JPG/SVG (max 2MB) or set URL
Platform key — must be exactly elearn.oc.edu.sa in every xAPI statement
Platform names — EN/AR names sent in NELC extensions
Brand color — updates sidebar accent

My Profile

Operator display name, email, role, and organization — shown in the sidebar.

LRS Endpoints

Manage NELC LRS connection targets. See Endpoints guide for details.

Active environment — poller tags new outbox rows with this ID
Endpoint Management — add/edit/delete custom endpoints
Health — probe LRS connectivity without writing to outbox
Built-in staging and production cannot be deleted

Worker

Poll Blackboard — manual sync of courses, enrollments, grades
Dispatch Outbox — send pending statements immediately
Quarantine — learners without 10-digit National ID (starts with 1, 2, or 4)

Automatic intervals: poll every 5 min, dispatch every 30 sec (configurable in .env).

Actions (Testing)

Action	Purpose
Test LRS Connection	Probe active endpoint; updates health status
Send Validation Journey	Queue all 7 required verbs for one learner×course
Test Blackboard	Verify REST API can list course users

Validation journey uses National ID in actor.name and course ID for object.id.

Outbox

Transactional queue with deduplication and retry.

Status	Meaning
PENDING	Waiting for dispatcher
RETRY	Failed temporarily — exponential backoff
SENT	Accepted by LRS (HTTP 200)
DEAD	Permanent failure — fix payload or credentials

Each row stores its Env column — dispatcher routes to the correct LRS even after switching active environment.

Journeys

State machine per learner and course URL:

registered → initialized → watched → completed → attempted → rated → earned

Phase 2 automates registered, initialized, and attempted. Others need Phase 3 (Caliper/LTI).

Logs & Statements

Logs — filter by level (info/warn/error) and category (nelc, dispatcher, poller, …)
Statements — history of direct sends and dispatcher results with LRS UUIDs

Required xAPI rules (NELC)

context.platform = elearn.oc.edu.sa (exact)
actor.name = 10-digit Saudi National ID
All 7 verbs for portal approval — including earned
Send from backend only — no duplicate statements