Line Item service

A platform can associate each LTI resource link with a single column (line item) in its gradebook. The Basic Outcomes service introduced in LTI 1.1 interacts with this default column. The Line Item service provides a tool with the ability to create additional columns in the platform's gradebook; these columns need not be associated with a resource link, just the context.

Service availability

The availability of the Line Item service can be checked using the hasLineItemService() method; for example:

if ($resourceLink->hasLineItemService()) {
    ...
}

or

if ($context->hasLineItemService()) {
    ...
}

Line item properties

A line item object comprises the following properties:

• label - the title for the column;
• pointsPossible - the scale used for values in the column;
• ltiResourceLinkId - the LTI resource link ID with which the column is associated;
• resourceId - the tool's resource ID for the column;
• submitFrom - the date/time from which grades can be submitted to this column;
• submitUntil - the date/time until which grades can be submitted to this column;
• endpoint - the URL for accessing this column.

Get all line items

To retrieve a list of all the line items for a context, use the getLineItems method; for example:

$lineItems = $context->getLineItems();

This method returns an array of LineItem objects (or a value of false if an error occurred), one for each of the tool's line items in the platform's context. In order to limit this list to just those associated with a specific resource link, call the method from the ResourceLink object; for example:

$lineItems = $resourceLink->getLineItems();

In either case, the list may be further restricted to those which match a resourceId value and/or tag value. The following example limits the list to line items with a resourceId value of res123:

$lineItems = $context->getLineItems('res123');

To limit the list to those with a tag value of xyz:

$lineItems = $context->getLineItems(null, 'xyz');

Or to limit the list to those which have a resourceId value of res123 and a tag value of xyz:

$lineItems = $context->getLineItems('res123', 'xyz');

Since no limit was specified the service default (initialised to unlimited) will be applied to limit the size of responses sent by the platform. The can be changed by either changing the value of the Service\LineItem::$defaultLimit property, or by passing a limit parameter to the method call; for example:

$lineItems = $context->getLineItems(null, null, 50);

In this case, the method will return all of the tool's line items for the context, but the platform will only send up to 50 at a time so executing the method may generate more than one request to the platform. The line items are not persisted by the library, so you may wish to store any details you wish to re-use later to save making this request too often.

Create a new line item

A new line item can be added to a Platform's context as in following example:

use ceLTIc\LTI;
...
$lineItem = new LTI\LineItem($platform, 'New column', 75);
$lineItem->resourceId = 'My resource';
$lineItem->tag = 'Essay';

$ok = $context->createLineItem($lineItem);

The line item object will be updated with the endpoint assigned by the platform, as well as other changes the platform has made when creating the column. To automatically associate the line item with a resource link use the ResourceLink object to create it:

use ceLTIc\LTI;
...
$lineItem = new LTI\LineItem($platform, 'New column', 75);
$lineItem->resourceId = 'My resource';
$lineItem->tag = 'Essay';

$ok = $resourceLink->newLineItem($lineItem);

This will set the ltiResourceLinkId property of the line item to the ID of the resource link object being used to create it.

Managing a line item

The endpoint provided by the platform for a line item can be used for managing it. For example, its details can be retrieved as follows:

$lineItem = LTI\LineItem::fromEndpoint($platform, $endpoint);

The line item can be updated as follows:

$lineItem->submitUntil = strtotime('2020-11-30 17:00:00');
$ok = $lineItem->save();

The line item can be deleted as follows:

$ok = $lineItem->delete();

Managing outcomes

Each line item may contain an outcome for each user. An array of the current outcomes for a line item can be retrieved as follows:

$outcomes = $lineItem->getOutcomes();

Since no limit was specified the service default (initialised to 500) will be applied to limit the size of responses sent by the platform. This can be changed by either changing the value of the Service\Result::$defaultLimit property, or by passing a limit parameter to the method call (use a value of 0 for unlimited); for example:

$outcomes = $lineItem->getOutcomes(50);

If a default line item endpoint was passed by the platform (using a custom parameter named lineitem_url), its associated outcomes can be retrieved from the resource link object; for example:

$outcomes = $resourceLink->getOutcomes(50);

The outcome for a specific user can be obtained from the platform as follows:

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

$outcome = $lineItem->readOutcome($user);

The outcome for a user can be added or updated as follows:

$outcome = new LTI\Outcome(50, 60, 'Submitted', 'Pending');
$outcome->comment = 'Very good!';

$ok = $lineItem->submitOutcome($outcome, $user);

The outcome for a user in a line item can be deleted as follows:

$outcome = $lineItem->deleteOutcome($user);