GradeSync
in package
Push a Plus course column and its scores to the controlling LMS.
A line item is created when the link first gets a result, and again when a grade arrives and the link still has none. The returned id is stored on lti_link.lti13_lineitem. A later grade posts to that line item.
A failed send leaves server_status set and does not replace server_grade. The next grade send tries again. There is no background retry.
Table of Contents
Constants
- KIND_LINEITEM : mixed = 'lineitem_create'
- KIND_LINEITEM_UPDATE : mixed = 'lineitem_update'
- KIND_SCORE : mixed = 'score'
Methods
-
activityLog()
: array{failures: array
>, successes: array >} - Line-item and score rows for this course. Failures and successes are separate so the grade book can list errors first. Roster pulls are left out.
- applyOverride() : array{ok: bool, status: string, message?: string}
- Store a teacher override. A link that already has a line item is sent.
- blockReason() : string|null
- Why this link should not be posted, or null when the LMS call can proceed.
- columnReady() : mixed
- A column needs a title and a positive point total. Anything else stays local.
- deliverIfPlus() : mixed
- Plus activities are sent here. The course-navigation link is not a column.
- earnedPoints() : float|null
- Points shown for a result. score_given wins when the tool stored one.
- endDateTime() : string|null
- Due instant for the line item. A course zone uses 23:59:59 that day in the zone. An empty zone sends the stored clock time unchanged.
- ensureLineItem() : mixed
- Create the line item for a new result when the link can have a column.
- isShellLink() : mixed
- lineItemBody() : object|null
- Line item body, or null when this link should not become a column.
- pointsMaximum() : mixed
- pushDueDateForKey() : array{ok: bool, status: string, message?: string}
- PUT the line item after this link's due date changed. A link with no line item is left for the create path, which already sends the due date.
- requestLineItem() : array{ok: bool, status: string, message?: string}
- Teacher asked for this link's line item. A quiz with no point total on the link uses the sum of its question points, and that sum is stored on the link before the LMS call.
- scoreGiven() : float|null
- withheld() : mixed
- grades_released 0 holds the score. Null and 1 send it.
- activityRows() : array<int, array<string, mixed>>
- adoptQuizPoints() : array<string, mixed>
- A quiz's question points become the link total when the link has none.
- appendDebug() : mixed
- configGap() : string|null
- createLineItem() : array{url?: string, error?: string}
- createUnderLock() : array{url?: string, error?: string}
- debugText() : mixed
- decodeLogDetail() : array{detail: string, debug: string}
- ensureFromRow() : mixed
- gapMessage() : mixed
- httpStatus() : int|null
- kindLabel() : mixed
- lineItemToken() : string|false
- loadLink() : array<string, mixed>|null
- loadLinkByKey() : array<string, mixed>|null
- loadResult() : array<string, mixed>|null
- lock() : bool|null
- True when this request holds the lock, false when another request holds it, null when the database cannot lock and the caller should continue.
- mark() : mixed
- Success stores the 0–1 fraction the LMS accepted and clears the error.
- pointsMessage() : mixed
- postScore() : string|null
- quizPoints() : float|null
- scoreToken() : string|false
- storeLineItem() : mixed
- storeOverride() : mixed
- token() : string|false
- unlock() : mixed
- updateExistingLineItem() : string|null
- withDeploymentClaim() : mixed
- writeLog() : mixed
- zone() : DateTimeZone|null
Constants
KIND_LINEITEM
public
mixed
KIND_LINEITEM
= 'lineitem_create'
KIND_LINEITEM_UPDATE
public
mixed
KIND_LINEITEM_UPDATE
= 'lineitem_update'
KIND_SCORE
public
mixed
KIND_SCORE
= 'score'
Methods
activityLog()
Line-item and score rows for this course. Failures and successes are separate so the grade book can list errors first. Roster pulls are left out.
public
static activityLog(int $contextId) : array{failures: array>, successes: array>}
Parameters
- $contextId : int
Return values
array{failures: arrayapplyOverride()
Store a teacher override. A link that already has a line item is sent.
public
static applyOverride(int $resultId, mixed $points) : array{ok: bool, status: string, message?: string}
This does not create a line item.
Parameters
- $resultId : int
- $points : mixed
Return values
array{ok: bool, status: string, message?: string}blockReason()
Why this link should not be posted, or null when the LMS call can proceed.
public
static blockReason(array<string, mixed> $row) : string|null
exists means the line item is already stored.
Parameters
- $row : array<string, mixed>
Return values
string|nullcolumnReady()
A column needs a title and a positive point total. Anything else stays local.
public
static columnReady(mixed $title, mixed $maximum) : mixed
Parameters
- $title : mixed
- $maximum : mixed
deliverIfPlus()
Plus activities are sent here. The course-navigation link is not a column.
public
static deliverIfPlus(int|string|false $resultId, mixed $grade, string|null $comment, string $activity, string $grading[, array<int, mixed>|false &$debug = false ]) : mixed
Returns true when this send was handled, including a local-only skip.
Parameters
- $resultId : int|string|false
- $grade : mixed
-
0–1 fraction already stored on the result
- $comment : string|null
- $activity : string
- $grading : string
- $debug : array<int, mixed>|false = false
earnedPoints()
Points shown for a result. score_given wins when the tool stored one.
public
static earnedPoints(array<string, mixed> $row) : float|null
Parameters
- $row : array<string, mixed>
Return values
float|nullendDateTime()
Due instant for the line item. A course zone uses 23:59:59 that day in the zone. An empty zone sends the stored clock time unchanged.
public
static endDateTime(mixed $due, mixed $timezone) : string|null
Parameters
- $due : mixed
- $timezone : mixed
Return values
string|nullensureLineItem()
Create the line item for a new result when the link can have a column.
public
static ensureLineItem(int $linkId) : mixed
A failure is logged. The launch still finishes.
Parameters
- $linkId : int
isShellLink()
public
static isShellLink(mixed $linkId, mixed $shellLinkId) : mixed
Parameters
- $linkId : mixed
- $shellLinkId : mixed
lineItemBody()
Line item body, or null when this link should not become a column.
public
static lineItemBody(int $linkId, mixed $title, mixed $maximum, mixed $due, mixed $timezone) : object|null
Parameters
- $linkId : int
- $title : mixed
- $maximum : mixed
- $due : mixed
- $timezone : mixed
Return values
object|nullpointsMaximum()
public
static pointsMaximum(array<string, mixed> $row) : mixed
Parameters
- $row : array<string, mixed>
pushDueDateForKey()
PUT the line item after this link's due date changed. A link with no line item is left for the create path, which already sends the due date.
public
static pushDueDateForKey(int $contextId, string $linkKey) : array{ok: bool, status: string, message?: string}
Parameters
- $contextId : int
- $linkKey : string
Return values
array{ok: bool, status: string, message?: string}requestLineItem()
Teacher asked for this link's line item. A quiz with no point total on the link uses the sum of its question points, and that sum is stored on the link before the LMS call.
public
static requestLineItem(int $linkId) : array{ok: bool, status: string, message?: string}
Parameters
- $linkId : int
Return values
array{ok: bool, status: string, message?: string}scoreGiven()
public
static scoreGiven(mixed $grade, mixed $maximum) : float|null
Parameters
- $grade : mixed
-
0–1 fraction
- $maximum : mixed
Return values
float|nullwithheld()
grades_released 0 holds the score. Null and 1 send it.
public
static withheld(mixed $flag) : mixed
Parameters
- $flag : mixed
activityRows()
private
static activityRows(int $contextId, int $success) : array<int, array<string, mixed>>
Parameters
- $contextId : int
- $success : int
Return values
array<int, array<string, mixed>>adoptQuizPoints()
A quiz's question points become the link total when the link has none.
private
static adoptQuizPoints(array<string, mixed> $row) : array<string, mixed>
Parameters
- $row : array<string, mixed>
Return values
array<string, mixed>appendDebug()
private
static appendDebug(array<int, mixed>|false &$debug, array<int, mixed> $more) : mixed
Parameters
- $debug : array<int, mixed>|false
- $more : array<int, mixed>
configGap()
private
static configGap(array<string, mixed> $row) : string|null
Parameters
- $row : array<string, mixed>
Return values
string|nullcreateLineItem()
private
static createLineItem(array<string, mixed> $row, array<int, mixed>|false &$debug) : array{url?: string, error?: string}
Parameters
- $row : array<string, mixed>
- $debug : array<int, mixed>|false
Return values
array{url?: string, error?: string}createUnderLock()
private
static createUnderLock(array<string, mixed> $row, array<int, mixed>|false &$debug) : array{url?: string, error?: string}
Parameters
- $row : array<string, mixed>
- $debug : array<int, mixed>|false
Return values
array{url?: string, error?: string}debugText()
private
static debugText(array<int, mixed> $debug) : mixed
Parameters
- $debug : array<int, mixed>
decodeLogDetail()
private
static decodeLogDetail(mixed $raw) : array{detail: string, debug: string}
Parameters
- $raw : mixed
Return values
array{detail: string, debug: string}ensureFromRow()
private
static ensureFromRow(array<string, mixed> $row, array<int, mixed>|false &$debug) : mixed
Parameters
- $row : array<string, mixed>
- $debug : array<int, mixed>|false
gapMessage()
private
static gapMessage(string $status) : mixed
Parameters
- $status : string
httpStatus()
private
static httpStatus(array<int, mixed> $debug) : int|null
Parameters
- $debug : array<int, mixed>
Return values
int|nullkindLabel()
private
static kindLabel(mixed $kind) : mixed
Parameters
- $kind : mixed
lineItemToken()
private
static lineItemToken(array<string, mixed> $row, array<int, mixed> &$debug) : string|false
Parameters
- $row : array<string, mixed>
- $debug : array<int, mixed>
Return values
string|falseloadLink()
private
static loadLink(int $linkId) : array<string, mixed>|null
Parameters
- $linkId : int
Return values
array<string, mixed>|nullloadLinkByKey()
private
static loadLinkByKey(int $contextId, string $linkKey) : array<string, mixed>|null
Parameters
- $contextId : int
- $linkKey : string
Return values
array<string, mixed>|nullloadResult()
private
static loadResult(int|string|false $resultId) : array<string, mixed>|null
Parameters
- $resultId : int|string|false
Return values
array<string, mixed>|nulllock()
True when this request holds the lock, false when another request holds it, null when the database cannot lock and the caller should continue.
private
static lock(int $linkId) : bool|null
Parameters
- $linkId : int
Return values
bool|nullmark()
Success stores the 0–1 fraction the LMS accepted and clears the error.
private
static mark(int $resultId, float|null $grade, string|null $error) : mixed
Failure stamps the attempt time and leaves the last accepted grade.
Parameters
- $resultId : int
- $grade : float|null
- $error : string|null
pointsMessage()
private
static pointsMessage(float $maximum) : mixed
Parameters
- $maximum : float
postScore()
private
static postScore(array<string, mixed> $row, mixed $grade, string|null $comment, string $activity, string $grading, array<int, mixed>|false &$debug) : string|null
Parameters
- $row : array<string, mixed>
- $grade : mixed
- $comment : string|null
- $activity : string
- $grading : string
- $debug : array<int, mixed>|false
Return values
string|null —The error, or null when the score was accepted
quizPoints()
private
static quizPoints(int $linkId) : float|null
Parameters
- $linkId : int
Return values
float|nullscoreToken()
private
static scoreToken(array<string, mixed> $row, array<int, mixed> &$debug) : string|false
Parameters
- $row : array<string, mixed>
- $debug : array<int, mixed>
Return values
string|falsestoreLineItem()
private
static storeLineItem(int $linkId, string $url) : mixed
Parameters
- $linkId : int
- $url : string
storeOverride()
private
static storeOverride(int $resultId, float $grade, float $earned, float $maximum) : mixed
Parameters
- $resultId : int
- $grade : float
- $earned : float
- $maximum : float
token()
private
static token(array<string, mixed> $row, array<int, mixed> &$debug, bool $lineItem) : string|false
Parameters
- $row : array<string, mixed>
- $debug : array<int, mixed>
- $lineItem : bool
Return values
string|falseunlock()
private
static unlock(int $linkId) : mixed
Parameters
- $linkId : int
updateExistingLineItem()
private
static updateExistingLineItem(array<string, mixed> $row, object $body, array<int, mixed>|false &$debug) : string|null
Parameters
- $row : array<string, mixed>
- $body : object
- $debug : array<int, mixed>|false
Return values
string|nullwithDeploymentClaim()
private
static withDeploymentClaim(callable $fn) : mixed
Parameters
- $fn : callable
writeLog()
private
static writeLog(array<string, mixed> $row, string $kind, bool $success, int|null $http, string $url, object|array<string, mixed>|null $request, string $detail, array<int, mixed>|false $debug) : mixed
Parameters
- $row : array<string, mixed>
- $kind : string
- $success : bool
- $http : int|null
- $url : string
- $request : object|array<string, mixed>|null
- $detail : string
- $debug : array<int, mixed>|false
zone()
private
static zone(mixed $timezone) : DateTimeZone|null
Parameters
- $timezone : mixed