Ltix.GradeService.Score (Ltix v0.1.0)

A score to post to the platform's gradebook.

Scores are write-only — the tool constructs them and POSTs to the platform. Use new/1 to build a validated score, then pass it to Ltix.GradeService.post_score/3.

The grading_progress must be :fully_graded for the platform to record the score as a final grade. Other values are considered partial and the platform may ignore them.

Examples

{:ok, score} = Ltix.GradeService.Score.new(
  user_id: "12345",
  score_given: 85,
  score_maximum: 100,
  activity_progress: :completed,
  grading_progress: :fully_graded
)

score.score_given
#=> 85

Summary

Types

t()

Functions

new(opts)

Build a validated score from keyword options.

to_json(score)

Serialize a score to a JSON-compatible map.

Types

t()

@type t() :: %Ltix.GradeService.Score{
  activity_progress:
    :initialized | :started | :in_progress | :submitted | :completed,
  comment: binary(),
  extensions: %{optional(binary()) => any()},
  grading_progress:
    :fully_graded | :pending | :pending_manual | :failed | :not_ready,
  score_given: number(),
  score_maximum: number(),
  scoring_user_id: binary(),
  submission: %{optional(atom()) => binary()},
  timestamp: %DateTime{
    calendar: term(),
    day: term(),
    hour: term(),
    microsecond: term(),
    minute: term(),
    month: term(),
    second: term(),
    std_offset: term(),
    time_zone: term(),
    utc_offset: term(),
    year: term(),
    zone_abbr: term()
  },
  user_id: binary()
}

Functions

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, Exception.t()}

Build a validated score from keyword options.

Auto-generates a timestamp with microsecond precision if not provided.

Options

:timestamp (struct of type DateTime) - When the score was set. Auto-generated if not provided.
:comment (String.t/0) - Plain text comment visible to both student and instructor.
:extensions (map/0) - Required. Extension properties keyed by fully qualified URLs. The default value is %{}.
:user_id (String.t/0) - Required. LTI user ID of the score recipient.
:activity_progress ("initialized" | "started" | "in_progress" | "submitted" | "completed") - Required. User's progress toward completing the activity.
:grading_progress ("fully_graded" | "pending" | "pending_manual" | "failed" | "not_ready") - Required. Status of the grading process. Must be :fully_graded for final scores.
:score_given (number/0) - Score value (must be >= 0). Requires score_maximum when present.
:score_maximum (number/0) - Maximum possible score (must be > 0). Required when score_given is present.
:scoring_user_id (String.t/0) - LTI user ID of the person who provided the score.
:submission (map/0) - Submission metadata with :started_at and :submitted_at ISO 8601 timestamps.

Examples

iex> {:ok, score} = Ltix.GradeService.Score.new(user_id: "u1", activity_progress: :completed, grading_progress: :fully_graded)
iex> score.user_id
"u1"

Strings are also accepted for activity_progress and grading_progress, which is convenient when values come from form params:

iex> {:ok, score} = Ltix.GradeService.Score.new(user_id: "u1", activity_progress: "completed", grading_progress: "fully_graded")
iex> score.activity_progress
:completed

to_json(score)

@spec to_json(t()) :: map()

Serialize a score to a JSON-compatible map.

Examples

iex> {:ok, score} = Ltix.GradeService.Score.new(user_id: "u1", activity_progress: :completed, grading_progress: :fully_graded, timestamp: ~U[2024-01-15 10:30:00.123456Z])
iex> json = Ltix.GradeService.Score.to_json(score)
iex> json["userId"]
"u1"