headless_lms_models/library/credit_registration/
study_registry.rs

1//! What the study registry answers, in the pipeline's own terms. The credit registration worker's
2//! Suotar adapter reads Suotar's wire records into these; nothing here knows the wire format.
3
4use chrono::NaiveDate;
5use secrecy::SecretString;
6
7use super::grade_mapping::MappedGrade;
8use crate::prelude::*;
9
10/// The final attainment type in Sisu; any other type on a registered submission is partial
11/// evidence.
12pub const ATTAINMENT_TYPE_COURSE_UNIT: &str = "CourseUnitAttainment";
13
14/// Serialized into the frozen payload as `{fi, sv, en}`.
15#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
16pub struct LocalizedName {
17    pub fi: Option<String>,
18    pub sv: Option<String>,
19    pub en: Option<String>,
20}
21
22/// Sisu's `LocalDateRange`: start inclusive, end exclusive, either end possibly open.
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct DatePeriod {
25    pub start_date: Option<NaiveDate>,
26    pub end_date: Option<NaiveDate>,
27}
28
29impl DatePeriod {
30    /// Whether `date` falls in the range; the end date itself is already outside it, and an open
31    /// end contains every date on that side.
32    pub fn contains(&self, date: NaiveDate) -> bool {
33        self.start_date.is_none_or(|start| start <= date)
34            && self.end_date.is_none_or(|end| date < end)
35    }
36}
37
38/// Sisu's credit range. An import against one missing either bound is refused.
39#[derive(Debug, Clone, PartialEq)]
40pub struct CreditRange {
41    pub min: Option<f64>,
42    pub max: Option<f64>,
43}
44
45/// One of a student's enrolments on a course code. Only the id is certain: every other field may
46/// be missing or unreadable in the registry's data.
47#[derive(Debug, Clone, PartialEq)]
48pub struct RegistryEnrolment {
49    pub id: String,
50    pub state: Option<String>,
51    pub kind: Option<String>,
52    pub course_unit_realisation_id: Option<String>,
53    pub course_unit_realisation_name: Option<LocalizedName>,
54    pub activity_period: Option<DatePeriod>,
55    /// The assessment item's scale, else the course unit's.
56    pub grade_scale_id: Option<String>,
57    /// The course unit's range; `None` when Sisu gives none, which no import can go against.
58    pub credits: Option<CreditRange>,
59    /// `None` when the study right could not be resolved, which is no proof it is invalid.
60    pub study_right_validity_period: Option<DatePeriod>,
61    pub enrolment_date_time: Option<DateTime<Utc>>,
62}
63
64/// An attainment the registry holds, or one a submission of ours created. Every field but the id
65/// and the type may be missing.
66#[derive(Debug, Clone, PartialEq, Eq)]
67pub struct RegistryAttainment {
68    pub id: String,
69    pub attainment_type: String,
70    pub state: Option<String>,
71    pub attainment_date: Option<NaiveDate>,
72    pub registration_date: Option<NaiveDate>,
73    pub grade_scale_id: Option<String>,
74    pub grade_id: Option<String>,
75}
76
77impl RegistryAttainment {
78    /// The grade the registry holds, or `None` when it gave no scale or no grade.
79    pub fn held_grade(&self) -> Option<MappedGrade> {
80        MappedGrade::from_columns(self.grade_scale_id.as_deref(), self.grade_id.as_deref())
81    }
82
83    /// The grade as a timeline line names it, with its scale: "1" is a pass on one scale and a one
84    /// out of five on the other. `None` when the registry gave no grade.
85    pub fn display_grade(&self) -> Option<String> {
86        let grade_id = self.grade_id.as_deref()?;
87        Some(match self.grade_scale_id.as_deref() {
88            Some(scale) => format!("{grade_id} on {scale}"),
89            None => grade_id.to_string(),
90        })
91    }
92}
93
94/// One person a course roster lists, once per realisation they are enrolled on.
95#[derive(Debug, Clone)]
96pub struct RosterPerson {
97    pub student_number: SecretString,
98    pub person_id: SecretString,
99    pub first_names: Option<SecretString>,
100    pub last_name: Option<SecretString>,
101    pub primary_email: Option<SecretString>,
102    pub secondary_email: Option<SecretString>,
103    pub enrolment: Option<RosterEnrolment>,
104}
105
106impl RosterPerson {
107    /// When the roster says they enrolled, if it says.
108    pub fn enrolled_at(&self) -> Option<DateTime<Utc>> {
109        self.enrolment
110            .as_ref()
111            .and_then(|enrolment| enrolment.enrolment_date_time)
112    }
113}
114
115/// The enrolment a roster lists a person under; every field may be absent.
116#[derive(Debug, Clone, PartialEq, Eq)]
117pub struct RosterEnrolment {
118    pub id: Option<String>,
119    pub course_unit_realisation_id: Option<String>,
120    pub state: Option<String>,
121    pub enrolment_date_time: Option<DateTime<Utc>>,
122}
123
124/// What the pipeline asks of the study registry, one variant per kind of request. The Suotar
125/// adapter maps each to its endpoint.
126#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
127pub enum RegistryOperation {
128    ResolvePersons,
129    ResolveEnrolments,
130    ImportAttainments,
131    VerifyAttainments,
132    ListCourseRoster,
133    ValidateCourseCodes,
134}
135
136impl RegistryOperation {
137    /// An item this operation never answered is uncertain, not retryable: re-sending it can put a
138    /// second attainment on a real transcript.
139    pub fn creates_attainments(self) -> bool {
140        matches!(self, Self::ImportAttainments)
141    }
142}
143
144/// How a whole request to the study registry failed. Failures of single items are answers, not
145/// these.
146#[derive(Debug, Clone, Copy, PartialEq, Eq)]
147pub enum RegistryErrorKind {
148    /// Our credentials.
149    AuthenticationFailure,
150    /// Our request, including one refused before it left.
151    MalformedRequest,
152    /// Another refusal of the request as a whole.
153    RejectedRequest,
154    /// The registry's own lookups failed before anything was written or sent.
155    TemporarilyUnavailable,
156    ServerError,
157    /// The connection itself failed, so the request provably never arrived.
158    NotDelivered,
159    /// The request left and no answer arrived, as on a timeout.
160    NoAnswer,
161    /// An answer arrived that was not a batch answer.
162    ProtocolViolation,
163}
164
165impl RegistryErrorKind {
166    /// Whether the registry may have acted on the request. An import that may have landed must be
167    /// verified rather than re-sent, or a transcript gets a second attainment.
168    pub fn may_have_been_acted_on(self) -> bool {
169        !matches!(
170            self,
171            Self::AuthenticationFailure
172                | Self::MalformedRequest
173                | Self::RejectedRequest
174                | Self::TemporarilyUnavailable
175                | Self::NotDelivered
176        )
177    }
178
179    /// Whether the registry or the network is down rather than anything being wrong with the
180    /// request, so the same request may succeed once they are back.
181    pub fn is_outage(self) -> bool {
182        matches!(
183            self,
184            Self::TemporarilyUnavailable | Self::ServerError | Self::NotDelivered | Self::NoAnswer
185        )
186    }
187}
headless_lms_models/library/credit_registration/study_registry.rs

headless_lms_models/library/credit_registration/
study_registry.rs
