Line Item service

A platform can associates 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');

If the context might have a large number of columns for the tool, you may wish to split the request into a number of smaller requests but specifying a limit to the number of columns which the platform's response should contain:

$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 lineitems 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 udpated 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();

The outcome for a 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);