How to sync Ed-Fi ODS/API data with Kastr
Kastr does not consume the Ed-Fi API. A district-side job queries your ODS, shapes the resources into roster entries, and POSTs them. That is more work than the other routes in this cluster, ten to twenty engineering hours, and it is the right route for districts whose ODS is already the canonical operational data source.
| Ed-Fi resource | Pull | In the roster entry | Notes |
|---|---|---|---|
educationOrganizations / schools | Yes | Nothing; use it to scope which schools you send | The organisation hierarchy is not part of a roster entry |
students | Yes | Student entries | Take the unique student identifier, not the resource id |
studentSchoolAssociations | Yes | Who is in the batch | Leave out a student whose exit date has passed, and the next sync withdraws them |
studentEducationOrganizationAssociations | Yes | email, phone, languagePref | Holds electronicMails, telephones, addresses, language descriptors |
contacts (DS5) / parents (DS4) | Yes | Guardian entries | Renamed in Data Standard 5, version-detect before you write the extract |
studentContactAssociations (DS5) | Yes | guardianOfSourceId | Was studentParentAssociations in DS4 |
staffs | Yes | Teacher entries | Only if you want staff messaging from the ODS |
staffEducationOrganizationAssignmentAssociations | Yes | Which staff are current | Leave out anyone whose assignment has ended |
sections, studentSectionAssociations | Optional | Nothing | Not part of a roster entry; skip on a first pass |
studentSpecialEducationProgramAssociations and similar | Do not pull | , | Programme participation is not needed to send a message |
The last row is a position, not an oversight. Pulling special-education, homelessness or free-and-reduced-price-meal programme associations into a communications platform acquires a category of sensitivity in exchange for capability the platform does not have. If a future targeted-outreach feature needs it, that is a conversation with its own consent design, not a quiet addition to a nightly job.
Data Standard 4 to 5: the rename that breaks nightly jobs
Data Standard 5 renamed the guardian half of the model. What was parents is now contacts. What was studentParentAssociations is now studentContactAssociations. The change is sensible, a great many adults responsible for a student are not parents, and it silently breaks any extract that hard-codes the old paths.
Because ODS upgrades are frequently scheduled by someone other than the person who wrote the extract, put a version-detection step at the top of the job rather than trusting a calendar. Query the API's version metadata, branch on the result, and log which branch ran. Six lines of code that save a fortnight of confusion.
The failure mode if you do not: the job runs, the student half succeeds, the contact half 404s, and you POST a batch with students and no guardians. Every guardian missing from that batch is withdrawn, unless there are enough of them for the guard to abort the sync. Have the job count guardians before it POSTs and stop on a collapse, which is another reason to read the numbers rather than the exit code.
Descriptors, and where the mapping file lives
Ed-Fi expresses controlled vocabulary as descriptor URIs, and their values are set by the standard, by your state, and by your district in layers. A contact-priority descriptor from Texas does not look like one from Indiana.
The mapping between descriptors and Kastr's fields therefore belongs in your extract job, not inside Kastr. Three mappings you need:
- Relation descriptor → whether that adult is sent as a guardian at all; a roster entry has no relationship label. Mother, father and guardian obviously do. Neighbour and employer obviously do not. The middle of that list is a district decision.
- Contact priority → which contacts you send, since a roster entry has no rank. Ed-Fi gives you an explicit priority integer on the association, which is cleaner than most SIS models.
- Electronic mail type and telephone number type → which email and phone number go in the entry. Send a mobile: home and work numbers cannot take SMS, and Kastr has no voice channel to reach them. Getting this wrong is how a district texts a workplace switchboard for a year.
Keeping the mapping on your side means you can change it without a release from us, and it means the mapping is reviewable in your own version control alongside the job that uses it.
Authentication, and which ODS to point at
Ed-Fi uses OAuth2 client credentials: your job exchanges a key and secret for a short-lived token and presents it as a bearer token. Standard, uninteresting, and the only thing worth saying about it is where the secret lives.
Store the client secret in your secret manager. Kastr never needs it and cannot use it. On our side you hold an API key, SHA-256 hashed at rest and displayed exactly once. And if anyone tries to paste a credential-shaped string into a Kastr roster connector config , anything starting sk_, whsec_, AKIA, AIza, ghp_ or -----BEGIN , the save is rejected. You store a reference, not the secret. The dedicated OneRoster REST connection is separate: its client secret is accepted in the connection form and stored encrypted with AES-256-GCM.
District ODS, not the state ODS. Several state education agencies run Ed-Fi at scale, Texas through TSDS, plus Indiana, Arizona, Nebraska and Michigan among others. The state ODS is a reporting destination: it lags, it is scoped to what the state collects, and guardian contact detail is frequently not part of that collection. For a communications roster you want the district ODS, which is current and complete. Pointing a nightly comms sync at a state reporting environment is a mistake that looks reasonable in a diagram and fails in practice.
Kastr writes nothing back to your ODS. No attendance, no message events, no contact corrections. If you want message history in your Ed-Fi environment or a warehouse alongside it, pull it from our REST API on your own schedule.
Effort, cadence and what you get for it
Budget ten to twenty engineering hours for a first clean sync, the highest figure in this cluster. The work is not the POST, it is the descriptor mapping and paging through resources for a district-sized ODS. Districts that already have an Ed-Fi extract for another purpose can usually halve it.
What you get in exchange is the cleanest source model available. Ed-Fi carries explicit entry and exit dates on studentSchoolAssociations, explicit contact priority, explicit telephone types and explicit staff assignment dates. Every one of those makes your job's decisions easier: who is current, which contacts to send, and which number can take a text.
Nightly at 02:00 suits most districts. Twice daily for the first three weeks of the year. If your ODS is written throughout the day by an integration layer rather than by an overnight batch, there is no reason not to run more often, a sync where nothing changed writes nothing, because every record payload is hashed and compared before any write is considered.
Every run, including aborted ones, lands in the per-organisation append-only audit log. Its entries are chained with SHA-256 and the table has neither UPDATE nor DELETE available to the application role, so what the roster looked like on any given night is a question with an answer that cannot be edited afterwards.
Questions people actually ask
Does Kastr consume the Ed-Fi API directly?
No. Kastr never pulls from your ODS. A district-side job authenticates with OAuth2 client credentials, queries the resources it needs, shapes them into roster entries and POSTs those to our endpoint. We hold no Ed-Fi credential and cannot reach your environment.
What changed for guardian data between Ed-Fi Data Standard 4 and 5?
The parents resource became contacts, and studentParentAssociations became studentContactAssociations. An extract with hard-coded DS4 paths will 404 on the guardian half after an upgrade while the student half keeps working, which produces a roster of students nobody can reach. Put a version-detection step at the top of the job.
Should I pull from our district ODS or the state ODS?
The district ODS. The state ODS is a reporting destination, it lags, it is scoped to what the state collects, and guardian contact data is often not collected at all. A communications roster needs current and complete data, which is the district instance by definition.
Where are Ed-Fi descriptors such as contact priority handled?
In your extract job, not inside Kastr. Contact priority decides which contacts you send, the relation descriptor decides whether an adult is sent as a guardian, and the telephone number type decides which number goes in the phone field, since only a mobile can take SMS. A roster entry has no rank or relationship label. Keeping the mapping on your side means you can change it without waiting for a release from us.
Does Kastr write anything back into the Ed-Fi ODS?
No. There is no write path of any kind. If you want message history alongside your Ed-Fi data, pull it from the Kastr REST API into your warehouse on your own schedule. Kastr is a consumer of roster data and never a writer of it.
One price. Every feature. Locked for three years.
$3.50 per student per year under 5,000 students. No tiers or add-on modules. Normal messaging is included under a published fair-use allowance, with transparent cost recovery only above it.