Student activity moments, plain enough for a teacher and exact enough for an LLM.

Import TimeBack source events without pre-normalizing

Send raw TimeBack Production learning-event rows and let Events Alpha derive Caliper tuples, Alpha kind, relationship keys, dedupe evidence, and public view rows.

Customer

Migration app or app-builder LLM

Operations

/source-imports, /events

Fields

event.kind, event.studentId, event.contentId, event.receivedAt

Trace

EAITD-005, EAITD-007, EAITD-008, EAITD-108

curl -sS -X POST "$EVENTS_BASE_URL/source-imports" \
  -H "Authorization: Bearer $EVENTS_TOKEN" \
  -H "X-Timeback-Tenant: demo" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: duke-2025-26-events-source-import-a1" \
  -d '{
  "sourceSystem": "timeback_production",
  "adapter": "timeback_learning_event_v1",
  "importId": "duke-2025-26-events-a1",
  "records": [
    {
      "id": "pf_918271",
      "student_sourced_id": "b6fa7128-f641-4efd-9075-375411fd6c39",
      "activity_id": "fractions_video_482",
      "activity_kind": "video_scrub",
      "occurred_at": "2026-02-12T15:04:03Z",
      "course_ref": "math-5-fractions"
    }
  ]
}'

Send a question answer moment

Record that a student answered a question without writing a score into Events.

Customer

Learning app

Operations

/events, /events/{eventId}

Fields

event.kind, event.studentId, event.contentId, event.happenedAt

Trace

EAITD-003, EAITD-005, EAITD-007

export RUN_ID="$(node -e 'console.log(require("node:crypto").randomUUID())')"
export HAPPENED_AT="$(node -e 'console.log(new Date().toISOString())')"

cat > events.json <<JSON
{
  "events": [
    {
      "sourceEventId": "urn:uuid:$RUN_ID",
      "kind": "question_answered",
      "eventType": "AssessmentItemEvent",
      "profile": "AssessmentProfile",
      "action": "Completed",
      "actorRef": {
        "id": "https://timeback.example.edu/users/student-1",
        "type": "Person"
      },
      "studentId": "student-ada-001",
      "objectRef": {
        "id": "https://timeback.example.edu/items/fractions-1",
        "type": "AssessmentItem",
        "name": "Fractions check"
      },
      "contentId": "content-fractions-video-01",
      "activitySourceId": "2fb3d3d9-a9f0-49ac-9ef7-5d2d1d0b1001",
      "happenedAt": "$HAPPENED_AT",
      "extensions": {
        "https://timeback.example.edu/extensions/outcomeScore": 1
      }
    }
  ]
}
JSON

curl -X POST "$EVENTS_BASE_URL/events" \
  -H "Authorization: Bearer $EVENTS_TOKEN" \
  -H "X-Timeback-Tenant: demo" \
  -H "Idempotency-Key: question-answer-$RUN_ID" \
  -H "Content-Type: application/json" \
  -d @events.json

Build a student's moments-today report

List today's app opens, views, video activity, hints, and answers for one student.

Customer

Teacher or parent-facing app

Operations

/events

Fields

event.studentId, event.kind, event.happenedAt, event.receivedAt

Trace

EAITD-009, EAITD-103, EAITD-107

export TO_TIME="$(node -e 'console.log(new Date().toISOString())')"
export FROM_TIME="$(node -e 'const d=new Date(); d.setUTCHours(0,0,0,0); console.log(d.toISOString())')"

curl "$EVENTS_BASE_URL/events?studentId=student-ada-001&happenedAtFrom=$FROM_TIME&happenedAtTo=$TO_TIME&pageSize=50" \
  -H "Authorization: Bearer $EVENTS_TOKEN" \
  -H "X-Timeback-Tenant: demo"

Trace a moment to content and source

Explain which learning app sent the moment and which content item it touched.

Customer

Support engineer or app-builder LLM

Operations

/events/{eventId}, /activity-sources/{sourceId}

Fields

event.activitySourceId, event.contentId, eventLink.role, eventThing.sourceId

Trace

EAITD-004, EAITD-006, EAITD-010

curl "$EVENTS_BASE_URL/events/b9f6dd89-b024-4d1d-a0c5-c923aab41001" \
  -H "Authorization: Bearer $EVENTS_TOKEN" \
  -H "X-Timeback-Tenant: demo"

Poll for new activity

Refresh an activity feed without re-reading the entire stream or implementing webhooks.

Customer

Dashboard or automation

Operations

/events

Fields

event.receivedAt, eventsPolicy.pageSize

Trace

EAITD-103, EAITD-107, EAITD-112

export MODIFIED_SINCE="$(node -e 'const d=new Date(Date.now()-15*60*1000); console.log(d.toISOString())')"

curl "$EVENTS_BASE_URL/events?modifiedSince=$MODIFIED_SINCE&pageSize=50" \
  -H "Authorization: Bearer $EVENTS_TOKEN" \
  -H "X-Timeback-Tenant: demo"

Read a student's attendance week

List school-day and section attendance moments without learning Ed-Fi resource names or descriptor tables.

Customer

Attendance dashboard or family-facing app

Operations

/attendance-events, /attendance-events/{attendanceEventId}

Fields

attendanceEvent.studentId, attendanceEvent.eventDate, attendanceEvent.category, attendanceEvent.isDeleted

Trace

EAITD-014, EAITD-016, EAITD-103

export TO_DATE="$(node -e 'console.log(new Date().toISOString().slice(0,10))')"
export FROM_DATE="$(node -e 'const d=new Date(); d.setUTCDate(d.getUTCDate()-7); console.log(d.toISOString().slice(0,10))')"

curl "$EVENTS_BASE_URL/attendance-events?studentId=student-ada-001&from=$FROM_DATE&to=$TO_DATE&pageSize=50" \
  -H "Authorization: Bearer $EVENTS_TOKEN" \
  -H "X-Timeback-Tenant: demo"

Review discipline moments safely

List discipline moments with governed behavior and participation values while keeping sensitive narrative text redacted.

Customer

School operations app or authorized staff workflow

Operations

/discipline-events, /discipline-events/{disciplineEventId}

Fields

disciplineEvent.studentId, disciplineEvent.incidentDate, disciplineEvent.behavior, disciplineEvent.description

Trace

EAITD-015, EAITD-016, EAITD-111

export TO_DATE="$(node -e 'console.log(new Date().toISOString().slice(0,10))')"
export FROM_DATE="$(node -e 'const d=new Date(); d.setUTCDate(d.getUTCDate()-30); console.log(d.toISOString().slice(0,10))')"

curl "$EVENTS_BASE_URL/discipline-events?studentId=student-ada-001&from=$FROM_DATE&to=$TO_DATE&pageSize=50" \
  -H "Authorization: Bearer $EVENTS_TOKEN" \
  -H "X-Timeback-Tenant: demo"

Raw TimeBack source-event import

Migrate production TimeBack learning-event rows without asking the caller to compute Caliper event tuples, Alpha event kind, Content joins, People & Orgs joins, dedupe hashes, or Results-owned metrics.

Trace

EAITD-005, EAITD-006, EAITD-007, EAITD-008, EAITD-108

Dictionary

Run The Student Moments Query

curl -sS -X POST "$EVENTS_BASE_URL/source-imports" \
  -H "Authorization: Bearer $TIMEBACK_JWT" \
  -H "X-Timeback-Tenant: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: duke-2025-26-events-source-import-a1" \
  -d '{
    "sourceSystem": "timeback_production",
    "adapter": "timeback_learning_event_v1",
    "importId": "duke-2025-26-events-a1",
    "records": [
      {
        "id": "pf_918271",
        "student_sourced_id": "b6fa7128-f641-4efd-9075-375411fd6c39",
        "activity_id": "fractions_video_482",
        "activity_kind": "video_scrub",
        "occurred_at": "2026-02-12T15:04:03Z",
        "course_ref": "math-5-fractions"
      }
    ]
  }'

-- Success is checked at public Events grain, not source-row submission grain.
-- The source import itself is a surface call; raw DB checks only prove materialization.
SELECT
  count(*) AS materialized_event_count,
  min(e.happened_at) AS first_event_at,
  max(e.happened_at) AS last_event_at
FROM alpha.event_view e
WHERE e.tenant_id = :tenant_id
  AND e.student_id = :student_id
  AND e.received_at >= :import_started_at
  AND e.kind IN ('app_opened','content_viewed','video_started','video_scrubbed',
                 'hint_requested','question_answered','assessment_started',
                 'assessment_submitted','lesson_finished','search_run',
                 'feedback_viewed','session_joined');

• The source record in the example is intentionally TimeBack-shaped. It is not a Caliper event and not an Alpha event object.
• The server must derive sourceEventId, eventType, profile, action, kind, actorRef, objectRef, studentId, contentId, orgId, happenedAt, and relationship links before writing.
• events:validation_failed returns HTTP 400. events:adapter_rejected returns HTTP 422. A validation or adapter rejection under HTTP 200 is a raw-ingest failure.
• On success, acceptedCount equals materializedCount and the returned event ids are immediately readable through GET /events.

Last 7 days of moments for one student

List event moments for a given studentId in the last 7 days, joined to People & Orgs for the org as of event.happenedAt and Content through event.contentId for the lesson touched.

Trace

EAITD-003, EAITD-006, EAITD-009, EAITD-103

Dictionary

Run The Student Moments Query

curl "$EVENTS_BASE_URL/events?studentId=person_ada_lovelace&happenedAtFrom=2026-05-28T00:00:00Z&happenedAtTo=2026-06-04T00:00:00Z&pageSize=50" \
  -H "Authorization: Bearer $TIMEBACK_JWT" \
  -H "X-Timeback-Tenant: $TENANT_ID"

SELECT
  e.id,
  e.happened_at,
  e.kind,
  e.student_id,
  p.first_name,
  p.last_name,
  pm.place_id AS org_id_as_of_event,
  pl.name AS org_name_as_of_event,
  ci.content_id,
  ci.title AS content_title,
  ci.content_kind
FROM alpha.event_view e
-- People & Orgs temporal join: event.happened_at is the only as-of key.
JOIN alpha.person p
  ON p.tenant_id = e.tenant_id
 AND p.person_id = e.student_id
JOIN alpha.place_membership pm
  ON pm.tenant_id = e.tenant_id
 AND pm.person_id = e.student_id
 AND pm.role_kind = 'student'
 AND pm.is_time_locatable = true
 AND pm.begin_date <= e.happened_at::date
 AND (pm.end_date IS NULL OR pm.end_date >= e.happened_at::date)
JOIN alpha.place pl
  ON pl.tenant_id = pm.tenant_id
 AND pl.place_id = pm.place_id
-- Content join: event.content_id is the only public Content relationship key.
LEFT JOIN alpha.content_item_view ci
  ON ci.workspace_id = e.tenant_id
 AND ci.content_id = e.content_id
WHERE e.tenant_id = :tenant_id
  AND e.student_id = :student_id
  AND e.happened_at >= :as_of::timestamptz - interval '7 days'
  AND e.happened_at < :as_of::timestamptz
ORDER BY e.happened_at DESC
LIMIT :page_size;

• Raw readers use alpha.event_view at public event grain, not caliper.envelope or raw payload rows.
• The People & Orgs join is point-in-time and formal: begin_date NULL rows are excluded, end_date NULL rows are active after begin_date, and event.happenedAt / e.happened_at is the as-of key.
• Content has exactly one public Events join key: event.contentId / e.content_id to alpha.content_item_view.content_id. objectRef and targetRef are provenance only.
• Scores, mastery, MAP, working grade, and report-card fields are intentionally absent. Join Results separately only when the job is a settled outcome report.

Migration skeleton for the public event view

Create the raw-DB surface the query above depends on without copying Caliper fields into an Alpha table.

Trace

EAITD-001, EAITD-002, EAITD-006, EAITD-007, EAITD-008

Dictionary

Run The Student Moments Query

Core event writes route through POST /events; rename/cut/restrict fields are persisted in Caliper base tables, not Alpha copies.

CREATE VIEW alpha.event_view AS
SELECT
  e.tenant_id,
  e.event_row_id AS id,
  e.event_iri AS source_event_id,
  e.event_type,
  e.profile,
  e.action,
  x.event_kind AS kind,
  e.actor AS actor_ref,
  x.student_sourced_id AS student_id,
  e.object AS object_ref,
  x.content_id,
  env.sensor_id AS activity_source_id,
  e.group_entity AS group_ref,
  x.org_sourced_id AS org_id,
  e.generated AS generated_ref,
  e.target AS target_ref,
  e.referrer AS referrer_ref,
  e.federated_session AS session_ref,
  e.event_time AS happened_at,
  env.received_at,
  e.event_extensions AS extensions
FROM caliper.event e
JOIN caliper.envelope env
  ON env.tenant_id = e.tenant_id
 AND env.envelope_id = e.envelope_id
LEFT JOIN alpha.event_extension x
  ON x.tenant_id = e.tenant_id
 AND x.event_row_id = e.event_row_id
WHERE env.envelope_status = 'processed';

• This is a view, not an Alpha table. It may expose Caliper-sourced columns because it stores nothing.
• alpha.event_extension is the only Events-owned sidecar here; it stores new Alpha columns such as event_kind, student_sourced_id, content_id, and org_sourced_id plus FKs to base rows.
• Do not add raw_event, canonical_event, event_hash, raw_envelope, credential_ref, score, mastery, or content-effectiveness columns to this public view.

Attendance events for one student and school week

List attendance moments for one student in the last 7 days, joined to People & Orgs as of eventDate.

Trace

EAITD-014, EAITD-016, EAITD-103

Dictionary

Run The Student Moments Query

curl "$EVENTS_BASE_URL/attendance-events?studentId=person_ada_lovelace&from=2026-05-28&to=2026-06-04&pageSize=50" \
  -H "Authorization: Bearer $TIMEBACK_JWT" \
  -H "X-Timeback-Tenant: $TENANT_ID"

SELECT
  ae.id,
  ae.event_date,
  ae.category,
  ae.duration_minutes,
  ae.student_id,
  p.first_name,
  p.last_name,
  pm.place_id AS school_id_as_of_event,
  pl.name AS school_name_as_of_event
FROM alpha.attendance_event_view ae
JOIN alpha.person p
  ON p.tenant_id = ae.tenant_id
 AND p.person_id = ae.student_id
JOIN alpha.place_membership pm
  ON pm.tenant_id = ae.tenant_id
 AND pm.person_id = ae.student_id
 AND pm.role_kind = 'student'
 AND pm.is_time_locatable = true
 AND pm.begin_date <= ae.event_date
 AND (pm.end_date IS NULL OR pm.end_date >= ae.event_date)
JOIN alpha.place pl
  ON pl.tenant_id = pm.tenant_id
 AND pl.place_id = pm.place_id
WHERE ae.tenant_id = :tenant_id
  AND ae.student_id = :student_id
  AND ae.event_date >= :as_of::date - interval '7 days'
  AND ae.event_date < :as_of::date
  AND ae.is_deleted = false
ORDER BY ae.event_date DESC, ae.id DESC
LIMIT :page_size;

• Use alpha.attendance_event_view at canonical attendance-event grain, not edfi.edfi_draft_record or raw payload_json alone.
• Descriptor-valued category must already be resolved through edfi.edfi_descriptor_code; a raw query should not carry its own attendance category table.
• The point-in-time join uses event_date, not current enrollment and not edfi.canonical_record.updated_at.

Discipline events for one student

List discipline moments for one student, with governed behavior/location values and redacted description handling.

Trace

EAITD-015, EAITD-016, EAITD-103, EAITD-111

Dictionary

Run The Student Moments Query

curl "$EVENTS_BASE_URL/discipline-events?studentId=person_ada_lovelace&from=2026-05-01&to=2026-06-04&pageSize=50" \
  -H "Authorization: Bearer $TIMEBACK_JWT" \
  -H "X-Timeback-Tenant: $TENANT_ID"

SELECT
  de.id,
  de.incident_id,
  de.incident_date,
  de.incident_time,
  de.behavior,
  de.location,
  de.participation_code,
  de.student_id,
  p.first_name,
  p.last_name,
  pm.place_id AS school_id_as_of_incident
FROM alpha.discipline_event_view de
LEFT JOIN alpha.person p
  ON p.tenant_id = de.tenant_id
 AND p.person_id = de.student_id
LEFT JOIN alpha.place_membership pm
  ON pm.tenant_id = de.tenant_id
 AND pm.person_id = de.student_id
 AND pm.role_kind = 'student'
 AND pm.is_time_locatable = true
 AND pm.begin_date <= de.incident_date
 AND (pm.end_date IS NULL OR pm.end_date >= de.incident_date)
WHERE de.tenant_id = :tenant_id
  AND de.student_id = :student_id
  AND de.incident_date >= :from_date
  AND de.incident_date < :to_date
  AND de.is_deleted = false
ORDER BY de.incident_date DESC, de.id DESC
LIMIT :page_size;

• Discipline description is sensitive and redacted by authorization policy; do not place real narrative text in public examples or logs.
• Behavior, participationCode, and location are descriptor-resolved governed values. Do not parse them out of description.
• Discipline actions, sanctions, transcript effects, and durable outcomes are not Events-owned fields.

Migration skeleton for attendance and discipline views

Create the Ed-Fi-backed raw-DB views without copying Ed-Fi canonical records into Alpha tables.

Trace

EAITD-012, EAITD-014, EAITD-015, EAITD-016

Dictionary

Run The Student Moments Query

Normal app writes route to the Ed-Fi 1EdTech base surface; production migration can call POST /source-imports with horizons_attendance_event_v1 or horizons_discipline_event_v1 and must get public view rows afterward.

CREATE VIEW alpha.attendance_event_view AS
SELECT
  c.tenant_id,
  c.edfi_local_id AS id,
  c.record_kind AS source_record_kind,
  c.student_sourced_id AS student_id,
  c.school_sourced_id AS school_id,
  c.class_sourced_id AS class_id,
  (c.payload_json #>> '{AttendanceEvent,EventDate}')::date AS event_date,
  dc.code_value AS category,
  (c.payload_json #>> '{ArrivalTime}')::time AS arrived_at,
  (c.payload_json #>> '{DepartureTime}')::time AS departed_at,
  COALESCE((c.payload_json #>> '{SchoolAttendanceDuration}')::integer,
           (c.payload_json #>> '{SectionAttendanceDuration}')::integer) AS duration_minutes,
  c.updated_at,
  c.is_deleted
FROM edfi.canonical_record c
JOIN edfi.edfi_descriptor_code dc
  ON dc.tenant_id = c.tenant_id
 AND dc.descriptor_type = 'AttendanceEventCategory'
 AND dc.code_value = c.payload_json #>> '{AttendanceEvent,AttendanceEventCategoryDescriptor}'
WHERE c.record_kind IN ('StudentSchoolAttendanceEvent', 'StudentSectionAttendanceEvent');

CREATE VIEW alpha.discipline_event_view AS
SELECT
  c.tenant_id,
  c.edfi_local_id AS id,
  c.source_key_json #>> '{IncidentIdentifier}' AS incident_id,
  c.student_sourced_id AS student_id,
  c.school_sourced_id AS school_id,
  (c.payload_json #>> '{IncidentDate}')::date AS incident_date,
  (c.payload_json #>> '{IncidentTime}')::time AS incident_time,
  behavior.code_value AS behavior,
  participation.code_value AS participation_code,
  location.code_value AS location,
  c.payload_json #>> '{IncidentDescription}' AS description,
  c.updated_at,
  c.is_deleted
FROM edfi.canonical_record c
LEFT JOIN edfi.edfi_descriptor_code behavior
  ON behavior.tenant_id = c.tenant_id
 AND behavior.descriptor_type = 'Behavior'
 AND behavior.code_value = c.payload_json #>> '{BehaviorDescriptor}'
LEFT JOIN edfi.edfi_descriptor_code participation
  ON participation.tenant_id = c.tenant_id
 AND participation.descriptor_type = 'DisciplineIncidentParticipationCode'
 AND participation.code_value = c.payload_json #>> '{DisciplineIncidentParticipationCodes,0}'
LEFT JOIN edfi.edfi_descriptor_code location
  ON location.tenant_id = c.tenant_id
 AND location.descriptor_type = 'IncidentLocation'
 AND location.code_value = c.payload_json #>> '{IncidentLocationDescriptor}'
WHERE c.record_kind IN ('DisciplineIncident', 'StudentDisciplineIncidentBehaviorAssociation');

• These are views over Ed-Fi canonical storage. There is no CREATE TABLE alpha.attendance_event or CREATE TABLE alpha.discipline_event carrying Ed-Fi-sourced columns.
• Descriptor joins are illustrative of the required raw-path rule; production SQL may normalize descriptor references differently as long as it uses edfi.edfi_descriptor_code.
• Ordinary public reads add is_deleted = false and role/scope filters on top of these views.