Line Items and Grades
The /api/lineitems
endpoints implement the Assignment and Grade Service and are used to access and manipulate line items and scores.
Retrieve line items¶
ROUTE | METHOD | AUTHENTICATION METHOD |
---|---|---|
/api/lineitems |
GET |
LTIK_AUTH_V1 |
Request¶
Parameters¶
PARAMETER | TYPE | LOCATION | REQUIRED |
---|---|---|---|
id |
String |
query |
|
resourceId |
String |
query |
|
tag |
String |
query |
|
label |
String |
query |
|
resourceLinkId |
Boolean |
query |
|
limit |
Number |
query |
|
url |
String |
query |
- id: Retrieves a specific line item by ID. Line item IDs are URLs so the parameter should be URL encoded.
- resourceId: Filters line items by resourceId.
- tag: Filters line items by tag.
- label: Filters line items by label.
- resourceLinkId: Filters line items by the resource link ID attached to the current launch context.
- limit: Limits the number of line items returned.
- url: Retrieves line items from a specific URL.
- When present, the
url
parameter causes every other parameter to be ignored. - The
url
parameter should be URL encoded. - In cases where not all line items are retrieved when the line item limit is reached, the returned object will contain a
next
field holding an URL that can be used to retrieve the remaining line items through theurl
parameter.
- When present, the
Example usage¶
app.get('/get-lineitems', async (req, res, next) => {
const ltik = req.query.ltik
const query = {
tag: 'grade_line',
label: 'Grade line'
}
const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
const response = await request.get('https://your.ltiaas.com/api/lineitems', { searchParams: query, headers: { Authorization: authorizationHeader } }).json()
return res.send(response.lineItems)
})
Response¶
Returns an object with a lineItems field containing an array of line items.
More information about line items can be found in the IMS Line Item Service specification.
- lineItems = Array of line items.
- next - URL of the next line item page. This field is only present if the line item limit was reached before the full list was retrieved.
- prev - URL of the previous line item page. This field is only present if the line item limit was reached before the full list was retrieved.
- first - URL of the first line item page. This field is only present if the line item limit was reached before the full list was retrieved.
- last - URL of the last line item page. This field is only present if the line item limit was reached before the full list was retrieved.
Example response¶
{
next: 'https://lms.example.com/sections/2923/lineitems/pages/2',
first: 'https://lms.example.com/sections/2923/lineitems/pages/1',
last: 'https://lms.example.com/sections/2923/lineitems/pages/3',
lineItems: [
{
id: 'https://lms.example.com/context/2923/lineitems/1',
scoreMaximum: 60,
label: 'Chapter 5 Test',
resourceId: 'a-9334df-33',
tag: 'grade',
resourceLinkId: '1g3k4dlk49fk',
endDateTime: '2018-04-06T22:05:03Z'
},
{
id: 'https://lms.example.com/context/2923/lineitems/47',
scoreMaximum: 100,
label: 'Chapter 5 Progress',
resourceId: 'a-9334df-33',
tag: 'originality',
resourceLinkId: '1g3k4dlk49fk'
},
{
id: 'https://lms.example.com/context/2923/lineitems/69',
scoreMaximum: 60,
label: 'Chapter 2 Essay',
tag: 'grade'
}
]
}
Create line item¶
ROUTE | METHOD | AUTHENTICATION METHOD |
---|---|---|
/api/lineitems |
POST |
LTIK_AUTH_V1 |
Request¶
Parameters¶
Requests MUST have a body representing a Line Item Object as specified in the IMS Line Item Object Specification.
The only required parameters are label and scoreMaximum.
PARAMETER | TYPE | LOCATION | REQUIRED |
---|---|---|---|
label |
String |
body |
✔️ |
scoreMaximum |
Number |
body |
✔️ |
- label: Line item label.
- scoreMaximum: Maximum score allowed for the line item.
Example usage¶
app.post('/create-lineitem', async (req, res, next) => {
const ltik = req.query.ltik
const lineitem = {
scoreMaximum: 60,
label: 'Grade line',
resourceId: 'quiz-231',
tag: 'grade',
resourceLinkId: '42', // Can be retrieved from ID Token's resource link ID (idtoken.launch.resource.id). Used to bind line item to LMS resource (activity).
startDateTime: '2022-03-06T20:05:02Z',
endDateTime: '2022-04-06T22:05:03Z'
}
const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
const response = await request.post('https://your.ltiaas.com/api/lineitems', { json: lineitem, headers: { Authorization: authorizationHeader } }).json()
return res.send(response)
})
Setting a resourceLinkId will bind the created line item to a specific resource (activity) in the LMS.
Response¶
Returns the newly created line item.
Example response¶
{
id: 'https://lms.example.com/context/2923/lineitems/1',
scoreMaximum: 60,
label: 'Chapter 5 Test',
resourceId: 'quiz-231',
tag: 'grade',
resourceLinkId: '1234',
startDateTime: '2018-03-06T20:05:02Z',
endDateTime: '2018-04-06T22:05:03Z'
}
Retrieve line item by ID¶
ROUTE | METHOD | AUTHENTICATION METHOD |
---|---|---|
/api/lineitems/:lineitemid |
GET |
LTIK_AUTH_V1 |
The line item ID is an URL so it MUST be URL encoded.
Request¶
Parameters¶
The /lineitems/:lineitemid
GET endpoint receives no parameters.
Example usage¶
app.get('/get-lineitem', async (req, res, next) => {
const ltik = req.query.ltik
const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
const response = await request.get(`https://your.ltiaas.com/api/lineitems/${lineitemId}`, { headers: { Authorization: authorizationHeader } }).json()
return res.send(response)
})
Response¶
Returns the requested line item.
Example response¶
{
id: 'https://lms.example.com/context/2923/lineitems/1',
scoreMaximum: 60,
label: 'Chapter 5 Test',
resourceId: 'quiz-231',
tag: 'grade',
startDateTime: '2018-03-06T20:05:02Z',
endDateTime: '2018-04-06T22:05:03Z'
}
Update line item by ID¶
ROUTE | METHOD | AUTHENTICATION METHOD |
---|---|---|
/api/lineitems/:lineitemid |
PUT |
LTIK_AUTH_V1 |
The line item ID is an URL so it MUST be URL encoded.
Request¶
Parameters¶
Requests MUST have a body representing a Line Item Object as specified in the IMS Line Item Object Specification.
The only required parameters are label and scoreMaximum.
PARAMETER | TYPE | LOCATION | REQUIRED |
---|---|---|---|
label |
String |
body |
✔️ |
scoreMaximum |
Number |
body |
✔️ |
- label: Line item label.
- scoreMaximum: Maximum score allowed for the line item.
Example usage¶
app.put('/update-lineitem', async (req, res, next) => {
const ltik = req.query.ltik
const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
const lineitem = {
scoreMaximum: 60,
label: 'Chapter 5 Updated'
}
const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
const response = await request.put(`https://your.ltiaas.com/api/lineitems/${lineitemId}`, { json: lineitem, headers: { Authorization: authorizationHeader } }).json()
return res.send(response)
})
Response¶
Returns the updated line item.
Example response¶
{
id: 'https://lms.example.com/context/2923/lineitems/1',
scoreMaximum: 60,
label: 'Chapter 5 Updated',
resourceId: 'quiz-231',
tag: 'grade',
startDateTime: '2018-03-06T20:05:02Z',
endDateTime: '2018-04-06T22:05:03Z'
}
Delete line item by ID¶
ROUTE | METHOD | AUTHENTICATION METHOD |
---|---|---|
/api/lineitems/:lineitemid |
DELETE |
LTIK_AUTH_V1 |
The line item ID is an URL so it MUST be URL encoded.
Request¶
Parameters¶
The /lineitems/:lineitemid
DELETE endpoint receives no parameters.
Example usage¶
app.delete('/launch', async (req, res, next) => {
const ltik = req.query.ltik
const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
await request.delete(`https://your.ltiaas.com/api/lineitems/${lineitemId}`, { headers: { Authorization: authorizationHeader } })
return res.sendStatus(204)
})
Response¶
Returns 204
status if the line item is successfully deleted.
Submit scores¶
ROUTE | METHOD | AUTHENTICATION METHOD |
---|---|---|
/api/lineitems/:lineitemid/scores |
POST |
LTIK_AUTH_V1 |
The line item ID is an URL so it MUST be URL encoded.
Request¶
Parameters¶
Requests MUST have a body representing a Score Object as specified in the IMS Score Specification.
The required parameters are userId, activityProgress and gradingProgress. The parameters timestamp and scoreMaximum are also required but are set automatically by LTIaaS.
PARAMETER | TYPE | LOCATION | REQUIRED |
---|---|---|---|
userId |
String |
body |
✔️ |
activityProgress |
String |
body |
✔️ |
gradingProgress |
String |
body |
✔️ |
- userId: Target user ID.
- activityProgress: Status of the user towards the activity's completion.
- gradingProgress: Status of the grading process.
Example usage¶
app.get('/submit-score', async (req, res, next) => {
const ltik = req.query.ltik
const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
const score = {
userId: '5323497',
activityProgress: 'Completed',
gradingProgress: 'FullyGraded',
scoreGiven: 83,
comment: 'This is exceptional work.',
}
const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
const response = await request.post(`https://your.ltiaas.com/api/lineitems/${lineitemId}/scores`, { json: score, headers: { Authorization: authorizationHeader } }).json()
return res.send(response)
})
Response¶
Returns the submitted score.
Example response¶
{
userId: '5323497',
activityProgress: 'Completed',
gradingProgress: 'FullyGraded',
scoreGiven: 83,
scoreMaximum: 100,
comment: 'This is exceptional work.',
timestamp: '2021-04-16T18:54:36.736+00:00',
}
Retrieve scores¶
ROUTE | METHOD | AUTHENTICATION METHOD |
---|---|---|
/api/lineitems/:lineitemid/scores |
GET |
LTIK_AUTH_V1 |
The line item ID is an URL so it MUST be URL encoded.
Request¶
Parameters¶
PARAMETER | TYPE | LOCATION | REQUIRED |
---|---|---|---|
userId |
String |
query |
|
limit |
Number |
query |
|
url |
String |
query |
- userId: Filters scores based on the user ID.
- limit: Limits the number of scores returned.
- url: Retrieves scores from a specific URL.
- When present, the
url
parameter causes every other parameter to be ignored. - The
url
parameter should be URL encoded. - In cases where not all scores are retrieved when the score limit is reached, the returned object will contain a
next
field holding an URL that can be used to retrieve the remaining scores through the url parameter.
- When present, the
Example usage¶
app.get('/launch', async (req, res, next) => {
const ltik = req.query.ltik
const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
const query = {
userId: 2,
limit: 10
}
const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
const response = await request.get(`https://your.ltiaas.com/api/lineitems/${lineitemId}/scores`, { searchParams: query, headers: { Authorization: authorizationHeader } }).json()
return res.send(response.scores)
})
Response¶
Returns an object with a scores field containing an array of scores.
More information about scores can be found in the IMS Result Service specification.
- scores - Array of scores.
- next - URL of the next score page. This field is only present if the score limit was reached before the full list was retrieved.
- prev - URL of the previous score page. This field is only present if the score limit was reached before the full list was retrieved.
- first - URL of the first score page. This field is only present if the score limit was reached before the full list was retrieved.
- last - URL of the last score page. This field is only present if the score limit was reached before the full list was retrieved.
Example response¶
{
next: 'https://lms.example.com/sections/2923/scores/pages/2',
first: 'https://lms.example.com/sections/2923/scores/pages/1',
last: 'https://lms.example.com/sections/2923/scores/pages/3',
scores: [
{
id: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem/results?type_id=1&user_id=2',
userId: '2',
resultScore: 100,
resultMaximum: 100,
scoreOf: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem?type_id=1',
timestamp: '2020-06-02T10:51:08-03:00'
},
{
id: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem/results?type_id=1&user_id=2',
userId: '3',
resultScore: 90,
resultMaximum: 100,
scoreOf: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem?type_id=1',
timestamp: '2020-06-02T10:51:08-03:00'
}
]
}