Outcomes service

The library supports the following outcomes-related services:

• Basic Outcomes service (defined in LTI 1.1)
• Score publish service (defined in Assignment and Grades Services)
• Result service (defined in Assignment and Grades Services)
• Unofficial Outcomes extension service

Support is also included for the resultData extension to the Basic Outcomes service. The doOutcomesService method in this library will automatically use whichever of these services is available.

The user's grade may be retrieved from the grade book in the platform using a read operation:

$outcome = new LTI\Outcome();
if ($resourceLink->doOutcomesService(LTI\Enum\ServiceAction::Read, $outcome, $user)) {
  $score = $outcome->getValue();
}

The user's grade may be saved to the grade book in the platform using a write operation:

$outcome = new LTI\Outcome($score);
$ok = $resourceLink->doOutcomesService(LTI\Enum\ServiceAction::Write, $outcome, $user);

The score should normally be a decimal value between 0 and 1, but the doOutcomesService method makes every effort to convert the value passed to a format which is accepted by the platform; for example, a percentage of 65% may be converted to a decimal 0.65. If the value cannot be converted to a decimal and the platform supports the Outcomes extension service then an attempt will be made to use this service instead. But the points possible for an Outcome object may also be specified; for example:

$outcome = new LTI\Outcome(65, 100);

The delete operation can be used to remove a grade from the grade book.

$outcome = new LTI\Outcome();
$resourceLink->doOutcomesService(LTI\Enum\ServiceAction::Delete, $outcome, $user);

The additional properties of the Outcome object are only used by the Scores and Results services. For example:

$score = 50;
$pointsPossible = 75;
$activityProgress = 'Submitted';
$gradingProgress = 'Pending';
$outcome = new LTI\Outcome($score, $pointsPossible, $activityProgress, $gradingProgress);
$outcome->comment = 'Good work!';
$ok = $resourceLink->doOutcomesService(LTI\Enum\ServiceAction::Write, $outcome, $user);

Basic Outcomes service

When using the Basic Outcomes service, a grade book entry for a specific user is identified by their associated result sourcedid; this value is passed when the user launches the tool and is automatically retained by the library for future use. The result sourcedid for the current user could be saved as a session variable as part of the onLaunch method, but the value may be obtained by loading the UserResult record from its user ID:

$user = LTI\UserResult::fromResourceLink($resourceLink, $ltiUserId);

The comment property of an Outcome object will also be used when the resultData extension is supported. If the value is a URL then this will be passed as either a url or ltiLaunchUrl element, depending upon which is noted as being supported in the ext_outcome_data_values_accepted parameter passed in message from the platform. Otherwise, the comment is passed as text. The format used can be forced by setting the parameter value accordingly; for example:

$resourceLink->setSetting('ext_outcome_data_values_accepted', 'ltiLaunchUrl');

will send the comment value as an LTI launch URL.

Outcomes extension service

If the platform has not given access to the Outcomes service, then the doOutcomesService method will use the unofficial Outcomes extension service if available. This has the same functionality but also supports value types other than decimal (set using the type property of the Outcome object).