Memberships

The Names and Roles Provisioning Service lets a tool fetch the roster of a course. A tool uses it to show a teacher their class list, to pre-create accounts, or to know who it should expect to see.

One request type is involved: MEMBERSHIPS_GET.

caution

Requires Names and Roles enabled on your account, and MEMBERSHIPS_READ in the tool's permissions.

The Request

{
  "type": "MEMBERSHIPS_GET",
  "parameters": {
    "context": "2022CSEa5e6c431b91",
    "clientId": "qR8E0iHqSdR30DdfQAbcaBGjKT65"
  }
}

Your Response

Return the context and everyone in it.

async function handleMemberships(decoded, res) {
  const { context } = decoded.parameters

  const course = await db.courses.find(context)
  if (!course) return res.status(404).json({ error: 'Course not found' })

  const enrollments = await db.enrollments.forCourse(course.id)

  return res.status(200).json({
    context: {
      id: course.id,
      label: course.code,
      title: course.name
    },
    members: enrollments.map(e => ({
      id: e.user.id,
      name: e.user.name,
      givenName: e.user.firstName,
      familyName: e.user.lastName,
      email: e.user.email,
      roles: [e.isTeacher ? 'CONTEXT_INSTRUCTOR' : 'CONTEXT_LEARNER']
    }))
  })
}

Fields

Field	Required	Notes
context.id	yes	Echo back the context you were asked about
context.label, context.title	no	Course code and name
members[].id	yes	Must match the user value you send on launches
members[].roles	yes	Role keys, not IMS URLs
members[].name, givenName, familyName, middleName, email	no	Filtered by the tool's privacy level

tip

members[].id has to be the same identifier you pass as user when starting a launch. If they differ, the tool cannot match the person in the roster to the person who launched, and features like "grade this student" break in confusing ways.

Personal Data Is Filtered for You

Send complete records. LTIAAS strips names and emails according to the tool's privacy level before the roster reaches it — a NONE tool receives IDs and roles only.

It also converts your role keys into the full IMS role URLs, so CONTEXT_LEARNER becomes http://purl.imsglobal.org/vocab/lis/v2/membership#Learner on the wire. You never write those URLs yourself.

Large Courses

The roster is returned in one response. For very large enrollments, fetch only the columns you need and consider a short cache — tools tend to poll the roster far more often than it changes.

Next Steps

• Line items — the grade lines tools create against a course.
• Scores and results — recording grades for the people in this roster.