Skip to content
  • There are no suggestions because the search field is empty.

How to Include Student Subgroups in Your Roster Integration

This article explains how to send student subgroup data (e.g. ELL, SPED, Title I) in your roster feed. You’ll get the exact step-by-step process (both during initial onboarding and as an ongoing append), the CSV schema, SFTP setup, and how subgroup data appears in your Derivita Analytics dashboard. It also highlights the one scenario where a separate append usually isn’t needed: ClassLink’s Roster Server.

1. Why Send Subgroup Metadata?

Your core roster (students, enrollments, courses, etc.) typically doesn’t include all the district-defined subgroup flags you may need for reporting (e.g. “ELL”, “SPED”, “Title I”). Supplying that metadata lets downstream tools break out analytics by those subgroups.

Because the OneRoster v1.1 standard doesn’t natively support arbitrary subgroup flags for all districts, we use a supplemental upload mechanism (or embed it during onboarding) to carry that information. (imsglobal.org)

2. When to Include Subgroups: Initial Onboarding vs. Ongoing Append

2.1 During Initial Onboarding

If you’re setting up the roster integration for the first time, it's optimal to include subgroup data right away. This means we configure your integration to expect those subgroup columns from the start, so you don't have to retrofit later. That way, your reporting tools will have access to those subgroup attributes from day one.

If you skip this step initially, you’ll need to add subgroup support later via the append workflow below.

2.2 Ongoing Append / Supplement Process (after onboarding)

For districts that already have a roster integration running without subgroups, here’s how to layer it in:

  1. We update your roster integration settings to accept subgroup columns.

  2. We send you a secure setup link (just like when you onboarded) to configure file upload.

  3. You set up an SFTP connection (host, port, path) and choose a password.

  4. You upload the subgroup file on your normal schedule (e.g. nightly).

  5. You notify us (via email) once the setup and first upload are complete. That ensures we check the initial data quickly.

Once the data is validated and error-free, your subgroup metadata becomes part of reporting in your Derivita Analytics dashboard (at district, school, course, and student levels).

3. File Schema / CSV Format

Use a wide table format where each subgroup is its own column. Example:

student_id | ell | sped | title_i  
12345      | y   | n    | y  
67890      | n   | y    | n  
...

  • student_id must match the same identifier used in your roster files (e.g. SIS ID, state ID).

  • Each subgroup column is a flag (e.g. “y/n”, “yes/no”, “1/0”) per student. The values do not have to be just boolean like values. They can be any value. Coordinate with Derivita at set up.

  • You may have multiple subgroup columns, depending on your district’s needs.

  • If you add new subgroup categories in the future, coordinate with us so we map them correctly.

4. Step-by-Step Workflow

4.1 What We Do on Our Side

  1. Enable subgroup ingestion in your roster integration.

  2. Send you a secure setup link to configure the SFTP endpoint.

4.2 What You Do on Your Side

  1. Use the secure link to configure the SFTP connection. We provide host, port, path, and you set the password.

  2. Build your subgroup CSV file using the schema above.

  3. Upload the file via SFTP per your schedule.

  4. Email us to confirm that the setup and first upload are complete (so we can begin processing immediately).

4.3 After Upload & Validation

  1. We verify that the file is received and maps correctly.

  2. If any errors or mismatches occur (invalid IDs, missing columns, unmatched students), we’ll send you a report to fix.

  3. Once all is correct, subgroup data will flow into your Derivita Analytics dashboard for reporting at all levels.

5. ClassLink Exception: Why a Separate Append Often Isn’t Needed

If your district uses ClassLink Roster Server, the process is often simpler:

  • ClassLink’s Roster Server includes a preprocessor / metadata customization layer allowing districts to embed metadata (including subgroup fields) into the roster feed. (classlink.com)

  • Because ClassLink acts as the central roster broker, connected applications receive the enriched roster feed with subgroup attributes built in, without requiring a separate CSV append. (classlink.com)

  • During integration, you’d configure in ClassLink what metadata fields (ELL, SPED, etc.) you want shared and make sure permissions are set appropriately.

So for ClassLink districts, the integration is more seamless — you usually don’t need to manage a standalone subgroup file.

6. Best Practices & Tips

  • Upload subgroup file shortly after your main roster export to avoid lag in reporting.

  • Keep the schema stable — don’t rename or reorder subgroup columns without coordination.

  • Validate that all student IDs in the subgroup file appear in the roster feed.

  • If you add new subgroup categories later, communicate to us so mapping is maintained.

  • Use logs, timestamps, or audit trails so changes to subgroup assignments can be tracked.

  • Monitor error reports for mismatches or missing data, especially early in the process.