How the Integration Works
Edlink connects to iSAMS using the Batch API: a streaming XML POST to /api/batch/1.0/xml.ashx. Each sync step requests one (or a small set of) Batch method(s), parses the XML response, and transforms records into Edlink models.
Authentication uses OAuth 2.0 client_credentials against /auth/connect/token (default scope apiv1). Every Batch call sends both:
Authorization: Bearer <access_token>?apiKey=<client_id>(the OAuth client ID)
Configuration on the Edlink source:
| Field | Purpose |
|---|---|
url | iSAMS host (or full xml.ashx URL — both forms are accepted) |
client_id | OAuth client ID; also used as the Batch apiKey query parameter |
client_secret | OAuth client secret |
scope | Optional; defaults to apiv1 for Batch |
timezone | Optional IANA timezone |
Official iSAMS Batch documentation: iSAMS Batch API.
Entity Mapping
| iSAMS Entity / Source | Edlink Model |
|---|---|
| Synthesized from team/source | District |
| Synthesized (single school) | School |
Term (School_GetSchoolTerms) | Session |
Building (Estate_GetAllBuildingsAndClassrooms) | Facility |
| Classroom (nested under Building) | Room |
Department (Curriculum_GetDepartments) | Department |
Subject (Curriculum_GetSubjects) | Subject |
Course (Curriculum_GetCourses) | Course |
Class (Curriculum_GetClasses) | Class |
Staff member (HumanResources_GetCurrentStaff) | Person (Teacher or Staff) |
Pupil (Pupil_GetCurrentPupils) | Person (Student) |
Contact (ContactAdvanced_GetContacts) | Person (Guardian) |
| Contact ↔ Pupil link | Agent |
ClassStudent (Curriculum_GetClassStudents) | Enrollment (Student) |
| Class teacher ID(s) | Enrollment (Teacher) |
Period (Timetable_GetTimetableStructure) | Period |
Year (School_GetAllYears) | Lookup only (grade-level mapping for courses/classes) |
Block (Curriculum_GetBlocks) | Lookup only (links classes to periods) |
Contact type (ControlPanel_GetContactTypeGlobalList) | Lookup only (guardian parental-responsibility defaults) |
Cycle / Type (Curriculum_GetCycles, Curriculum_GetTypes) | Lookup only (filter iteration for curriculum methods) |
- District / School: One district and one school are created from the Edlink team name and fixed external IDs (
isams_district/isams_school), not from a multi-campus iSAMS org tree. - People: Teaching staff (
TeachingStaff=1) map to roleTeacher; other staff map toStaff. Pupils map toStudent. Contacts map toGuardian. - Agents: Guardian–student relationships are created from nested pupil links on contacts. Contacts with effective parental responsibility
Yesreceive theLegalGuardianagent flag. - Enrollments: Student enrollments are currently always emitted as
Activeas EdLink has only ever observed one value for@CourseStudentStatusId. Teacher enrollments are derived from teacher IDs on classes after staff are loaded. - Periods: Class→period linkage goes Class → Block → Period IDs. Without
Curriculum_GetBlocksallocated, classes sync without period links.
Batch Methods Used for Rostering
These methods are expected to be allocated on the Batch API client (and are checked during source validation):
| Method | Used for |
|---|---|
School_GetAllYears | Year / grade lookups |
School_GetSchoolTerms | Sessions |
Estate_GetAllBuildingsAndClassrooms | Facilities and rooms |
Curriculum_GetDepartments | Departments |
Curriculum_GetSubjects | Subjects |
Curriculum_GetCourses | Courses |
Curriculum_GetClasses | Classes |
Curriculum_GetClassStudents | Student enrollments |
Curriculum_GetCycles | Cycle IDs for filtered curriculum calls |
Curriculum_GetTypes | Type IDs for filtered curriculum calls |
HumanResources_GetCurrentStaff | Staff / teachers |
Pupil_GetCurrentPupils | Students |
ContactAdvanced_GetContacts | Guardians and agents |
Timetable_GetTimetableStructure | Periods |
Curriculum_GetBlocks | Class↔period linkage |
ControlPanel_GetContactTypeGlobalList | Contact-type defaults for guardians |
Some curriculum and contact methods require filter XML in the Batch request body (for example ContactAdvanced_GetContacts and several Curriculum_* methods). Edlink supplies those filters during sync.
Additional Notes
- Streaming responses: Roster XML can be large; Edlink streams and SAX-parses responses rather than buffering the full document.
- Errors: iSAMS application errors often return an XML
<Message>envelope (e.g.MethodsNotAllocatedToKeyException,InvalidApiKey,ServiceThrottled) rather than only HTTP status text. - REST API: An older REST OAuth path (scope
restapi) may exist in code for compatibility but is not what the rostering sync uses. - Historical / former pupils: Syncing historical data is not supported.
Custom Field Mapping
Custom field mapping is not supported.
The following fields can be custom-mapped in our dashboard UI: