Grading Service Class Documentation

Table of Contents

Introduction

LTI-Typescript implements the LTI® 1.3 Assignment and Grading Service Specification in the form of the GradeService Class.

Usage

Sending grades to a platform

LTI-Typescript is able to send grades to a platform in the application/vnd.ims.lis.v1.score+json LTI® standard:

{ 
  "userId" : "200",
  "scoreGiven" : 83,
  "scoreMaximum" : 100,
  "comment" : "This is exceptional work.",
  "activityProgress" : "Completed",
  "gradingProgress": "FullyGraded"
}

This excludes the timestamp field of the specification, because the submitScore method generates it automatically.

Submitting Grades

/**
 * sendGrade
 */
provider.app.post('/grade', async (req, res) => {
  try {
    const idtoken = res.locals.token; // IdToken
    const score = req.body.grade; // User numeric score sent in the body
    // Creating Grade object
    const gradeObj = {
      userId: idtoken.user,
      scoreGiven: score,
      scoreMaximum: 100,
      activityProgress: 'Completed',
      gradingProgress: 'FullyGraded',
    };

    // Selecting lineItem ID
    let lineItemId = idtoken.platformContext.endpoint.lineitem; // Attempting to retrieve it from idtoken
    if (!lineItemId) {
      const response = await provider.GradeService.getLineItems(idtoken, { resourceLinkId: true });
      const lineItems = response.lineItems;
      if (lineItems.length === 0) {
        // Creating line item if there is none
        console.log('Creating new line item');
        const newLineItem = {
          scoreMaximum: 100,
          label: 'Grade',
          tag: 'grade',
          resourceLinkId: idtoken.platformContext.resource.id,
        }
        const lineItem = await provider.GradeService.createLineItem(idtoken, newLineItem);
        lineItemId = lineItem.id;
      } else lineItemId = lineItems[0].id;
    }

    // Sending Grade
    const responseGrade = await provider.GradeService.submitScore(idtoken, lineItemId, gradeObj);
    return res.send(responseGrade);
  } catch (err) {
    return res.status(500).send({ err: err.message });
  }
});
Retrieving Grades

LTI-Typescript is able to retrieve grades from a platform:

provider.app.get('/grade', async (req, res) => {
  // Retrieves grades from a platform, only for the current user
  const idtoken = res.locals.token; // IdToken
  const response = await provider.GradeService.getScores(idtoken, idtoken.platformContext.endpoint.lineitem, { userId: idtoken.user });
  return res.send(result);
});
Line Item Retrieval, Creation, Update, and Deletion Example
// Retrieving lineitems
provider.app.get('/lineitem', async (req, res) => {
  // Retrieves lineitems from a platform
  const result  = await provider.GradeService.getLineItems(res.locals.token);
  return res.send(result);
});

// Creating lineitem
provider.app.post('/lineitem', async (req, res) => {
  const lineItem = {
    scoreMaximum: 100,
    label: 'Grade',
    tag: 'grade',
  };
  // Sends lineitem to a platform
  await provider.GradeService.createLineItem(res.locals.token, lineItem);
  return res.sendStatus(201);
});

// Update lineitem
provider.app.post('/lineitem', async (req, res) => {
  const lineItem = {
    scoreMaximum: 100,
    label: 'Grade',
    tag: 'grade',
  };
  // Sends lineitem to a platform
  await provider.GradeService.updateLineItemById(res.locals.token, req.body.lineitemid, lineItem);
  return res.sendStatus(201);
});

// Delete lineitem
provider.app.delete('/lineitems', async (req, res) => {
  // Deleting lineitem on a platform
  await provider.GradeService.deleteLineItemById(res.locals.token, req.body.lineitemid, { tag: 'tag' });
  return res.sendStatus(204);
});

Documentation

getLineItems(idToken: IdToken, options?: { … }, accessToken?: AccessTokenType): Promise;

getLineItemById(idToken: IdToken, lineItemId: string, accessToken?: AccessTokenType): Promise;

createLineItem(idToken: IdToken, lineItem: CreateLineItem, options?: { resourceLinkId: boolean = false }, accessToken?: AccessTokenType): Promise;

updateLineItem(idToken: IdToken, lineItemId: string, lineItem: CreateLineItem, accessToken?: AccessTokenType): Promise;

deleteLineItemById(idToken: IdToken, lineItemId: string, accessToken?: AccessTokenType): Promise;

submitScore(idToken: IdToken, lineItemId: string, score: Omit, accessToken?: AccessTokenType): Promise;

License

APACHE2 License

Learning Tools Interoperability® (LTI®) is a trademark of the IMS Global Learning Consortium, Inc. (https://www.imsglobal.org)

This library is a derivative work of CVM Costa's original LTIJS library.