Zum Hauptinhalt springen

Liste bekannter Personenkontexte.

GET 
/personen-info

Liefert die Personenkontext-IDs der dem Dienst bekannten und derzeit aktiven Personenkontexte sowie gegebenenfalls den Löschzeitpunkt.

Der Aufruf dieses Endpunkts erfolgt immer im Kontext des Dienstes. Der Dienst authentisiert sich durch den Client Credentials Flow.

Die Anfrage muss mit HTTP-GET gestellt werden. Als Antwort erfolgt eine Liste aus Datenobjekten, welche jeweils die Struktur einer Antwort der API person-info haben, jedoch nur drei Daten-Attribute enthalten: pid, id und gegebenenfalls den Löschzeitpunkt.

Personen und Personenkontexte, welche in der Liste nicht aufgeführt sind, sind als gelöscht anzunehmen und alle lokalen Daten des Dienstes zu dieser Person und diesem Personenkontext sind zu löschen.

Bei der Auslieferung von /personen-info wird im HTTP-Header ein ETag mitgeliefert. Bei nachfolgenden Abrufen der Personen-Information vom Schulconnex-Service kann der Dienst ein „If-None-Match“ Tag mit diesem ETag in den Request-Header mit aufnehmen.

Hat sich der Datensatz seit Auslieferung des ETag-Headers nicht geändert, so antwortet der Server mit einem Status 304 (Not Modified) und sendet den Datensatz nicht erneut.

Die Personenkontext-ID id ist die für den jeweiligen Dienst individuell pseudonymisierte ID des Personenkontexts.

Die Schnittstelle /personen-info ermöglicht das Verwenden eines Filterparameters zum Auslesen der vollständigen Datensätze der gelisteten Personen oder Personenkontexte im selben Umfang, wie sie auch bei /person-info geliefert werden.

Der Filter vollstaendig kann die Werte personen, personenkontexte, organisationen, gruppen oder beziehungen annehmen. Mehrere Werte können, getrennt durch Kommas, in einem Filter genutzt werden.

Zu beachten ist hierbei, dass bei Objekt-Hierarchien untergeordnete Objekte nur dann ausgegeben werden, wenn auch die in der Hierarchie direkt darüber liegenden Objekte ausgegeben werden. So werden bei der Auswahl von vollstaendig=personen,organisationen Informationen zu den Organisationen nicht mit ausgegeben, da diese nicht Teil von personen sind, sondern von personenkontexten. Sollen Informationen zu Organisationen mit ausgegeben werden, so ist als Filter vollstaendig=personen,personenkontexte,organisationen zu benutzen.

Darüber hinaus kann auch eine Filterung nach Personen, Personenkontexten, Gruppen und Organisationen anhand der jeweiligen ID erfolgen.

Welche Filterfunktionen genutzt werden können, wird durch eine vertragliche Absprache zwischen Dienstanbieter und Betreiber des Schulconnex-Servers geregelt.

Entsprechen keine Werte den angegebenen Filtern, so wird als Resultat eine leere Liste geliefert.

FilterTypParameterBeschreibung
vollstaendigStringpersonenMöglichkeit, statt nur der pid zu jeder der gelisteten Personen die vollständige Beschreibung nach Datenmodell Person für Dienstanbieter, anzuzeigen.
personenkontexteMöglichkeit, statt nur id und loeschung zu jedem der gelisteten Personenkontexte die vollständige Beschreibung nach Datenmodell Personenkontext für Dienstanbieter, anzuzeigen.
gruppenMöglichkeit, statt nur der Gruppen-ID zu jeder gelisteten Gruppe die vollständige Beschreibung nach Datenmodell Gruppe für Dienstanbieter anzuzeigen.
organisationenMöglichkeit, statt nur der Organisations-ID zu jeder gelisteten Organisation die vollständige Beschreibung nach Organisation anzuzeigen.
beziehungenMöglichkeit, die Beziehungen, welche aus einem Personenkontext heraus bestehen, aufzulisten Es werden nur die hat_als Beziehungen ausgegeben. Der Default ist keine Ausgabe von Beziehungen.
pidStringMit diesem Filter kann der Datensatz einer einzelnen Person anhand ihrer pid ausgelesen werden.
personenkontext.idStringMit diesem Filter kann der Datensatz einer einzelnen Person mit einem einzelnen Personenkontext anhand der Kontext-ID ausgelesen werden. Die Informationen zur entsprechenden Person werden, unter Berücksichtigung des Filters vollstaendig, entsprechend der Client-Berechtigungen ausgeliefert.
gruppe.idStringMit diesem Filter können die Datensätze aller Personen ausgegeben werden, welche einer Gruppe zugeordnet sind. Die Informationen zur entsprechenden Person werden, unter Berücksichtigung des Filters vollstaendig, entsprechend der Client-Berechtigungen ausgeliefert. Es ist abhängig vom Schulconnex-Server, ob alle existierenden Personen der Gruppe mit aufgeführt werden oder nur solche, welche schon von dem Dienst abgerufen wurden und damit dem Dienst bekannt sind.
organisation.idStringMit diesem Filter können die Datensätze aller Personen ausgegeben werden, welche einer Organisation zugeordnet sind. Die Informationen zur entsprechenden Person werden, unter Berücksichtigung des Filters vollstaendig, entsprechend der Client-Berechtigungen ausgeliefert. Es ist abhängig vom Schulconnex-Server, ob alle existierenden Personen einer Organisation mit aufgeführt werden oder nur solche, welche schon von dem Dienst abgerufen wurden und damit dem Dienst bekannt sind.

Request​

Query Parameters

    vollstaendig string[]

    Possible values: [personen, personenkontexte, organisationen, gruppen]

    pid string
    personenkontext.id string
    gruppe.id string
    organisation.id string

Responses​

OK

Schema

  • Array [

    • pid stringrequired

    Pseudonymisierte ID. Referenziert ein bestehendes Objekt des Schulconnex-Servers.

    person

    object

    stammorganisation

    object

    Organisation.

    id stringrequired

    ID der Organisation.

    kennung string

    Die optionale Kennung (Identifikations-ID) einer Organisation.

    name string

    Offizieller Name einer Organisation.

    anschrift

    object

    postleitzahl string

    Postleitzahl.

    ort string

    Amtlicher Gemeindename.

    ortsteil string

    Teil eines Orts, falls genauere Untergliederung gewünscht.

    typ components-code-Organisationstyp (string)

    Possible values: [Schule, Anbieter, Sonstige]

    Wie folgt:

    • Schule
    • Anbieter
    • Sonstige sonstige Organisationen / Einrichtungen

    name

    object

    required

    familienname stringrequired

    Familienname(n) der Person. Mehrere Familiennamen werden durch Leerzeichen separiert.

    vorname stringrequired

    Mehrere Vornamen werden durch Leerzeichen separiert.

    initialenfamilienname string

    Possible values: <= 8 characters

    Initial oder Initialen des Familiennamens, maximal acht Zeichen.

    initialenvorname string

    Possible values: <= 8 characters

    Initial oder Initialen des Vornamens, maximal acht Zeichen.

    rufname string

    Possible values: <= 32 characters

    Bei mehreren Vornamen wird der täglich im Gebrauch genutzte Vorname geführt, maximal 32 Zeichen.

    titel string

    Possible values: <= 128 characters

    Titel der Person (bspw. ein akademischer Grad, Dienst- und Amtsbezeichnungen oder militärische Ränge), maximal 128 Zeichen.

    anrede string[]

    Possible values: <= 64 characters

    Liste (Array) von Namenszusätzen bei der Anrede. Jeder einzelne Namenszusatz hat eine Maximallänge von 64 Zeichen, die Maximallänge für alle Namenszusätze liegt bei 512 Zeichen.

    namenssuffix string[]

    Possible values: <= 64 characters

    Liste (Array) von Namenssuffixen. Jeder einzelne Namenssuffix hat eine Maximallänge von 64 Zeichen, die Maximallänge für alle Namenssuffixe liegt bei 1024 Zeichen.

    sortierindex string

    Possible values: Value must match regular expression ^[0-9]+$

    Index des Buchstabens des Nachnamens, nach dem sortiert werden soll. Der Index ist Null-basiert, d. h. ein Wert von „4“ zeigt an, dass die ersten vier Buchstaben ignoriert und ab dem fünften Buchstaben des Nachnamens sortiert werden soll. Ist kein Sortierindex angegeben, so ist der Nachname entsprechend dem ersten Buchstaben in Listen einzusortieren, äquivalent zum Sortierindex „0“.

    geburt

    object

    datum date

    Geburtsdatum einer Person.

    volljaehrig components-code-Boolean (string)

    Possible values: [Ja, Nein]

    Gibt an, ob eine Person volljährig ist.

    geburtsort string

    Geburtsort einer Person, bestehend aus Ortsname und Land, beispielsweise „Eindhoven, Niederlande“. Wird kein Land angegeben, so wird als Land „Deutschland“ angenommen, d.h. der Geburtsort „Erfurt“ ist wie „Erfurt, Deutschland“ zu behandeln.

    geschlecht components-code-Geschlecht (string)

    Possible values: [m, w, d, x]

    Geschlecht:

    • m männlich
    • w weiblich
    • d divers
    • x keine Angabe
    lokalisierung string

    Basierend auf RFC 5646. Mögliche Beispiele:

    • de deutsch
    • de-XX deutsch, Anrede du, einfache Sprache
    • en-GB englisch (Vereinigtes Königreich)
    vertrauensstufe components-code-Vertrauensstufe (string)

    Possible values: [Kein, Unbe, Teil, Voll]

    Wie folgt:

    • Kein - kein - Der Schlüsselbesitzer ist nicht vertrauenswürdig.
    • Unbe - unbekannt - Der Schlüsselbesitzer ist unbekannt.
    • Teil - vertraut - Dem Schlüsselbesitzer wird vertraut.
    • Voll - verifiziert - Der Schlüsselbesitzer ist eindeutig und formal identifiziert.

    personenkontexte

    object[]

  • Array [

    • id stringrequired

    ID des Personenkontexts. Referenziert ein bestehendes Objekt des Schulconnex-Servers.

    organisation

    object

    required

    Organisation.

    id stringrequired

    ID der Organisation.

    kennung string

    Die optionale Kennung (Identifikations-ID) einer Organisation.

    name string

    Offizieller Name einer Organisation.

    anschrift

    object

    postleitzahl string

    Postleitzahl.

    ort string

    Amtlicher Gemeindename.

    ortsteil string

    Teil eines Orts, falls genauere Untergliederung gewünscht.

    typ components-code-Organisationstyp (string)

    Possible values: [Schule, Anbieter, Sonstige]

    Wie folgt:

    • Schule
    • Anbieter
    • Sonstige sonstige Organisationen / Einrichtungen

    gruppen

    object[]

  • Array [

    • gruppe

    object

    required

    id stringrequired

    ID der Gruppe.

    orgid string

    ID der Organisation.

    bezeichnung stringrequired

    Bezeichnung der Gruppe.

    thema string

    Thema der Gruppe in Kurzform.

    beschreibung string

    Possible values: <= 1024 characters

    Zusätzliche optionale Beschreibung der Gruppe.

    typ components-code-Gruppentyp (string)required

    Possible values: [Klasse, Kurs, Sonstig]

    Wie folgt:

    • Klasse Schulklasse
    • Kurs Kurs/Unterricht
    • Sonstig Sonstige Gruppe
    bereich components-code-Gruppenbereich (string)

    Possible values: [Pflicht, Wahl, Wahlpflicht]

    Diese Codeliste ist spezifisch für das Bundesland Niedersachsen:

    • Pflicht Pflichtunterricht
    • Wahl Wahlunterricht
    • Wahlpflicht Wahlpflichtunterricht
    optionen components-code-Gruppenoption (string)[]

    Possible values: [``]

    differenzierung components-code-Gruppendifferenzierung (string)

    Possible values: [G, E, Z, gA, eA]

    Diese Codeliste ist spezifisch für das Bundesland Niedersachsen:

    • G G-Kurs
    • E E-Kurs
    • Z Z-Kurs
    • gA grundlegendes Anforderungsniveau
    • eA erhöhtes Anforderungsniveau
    bildungsziele components-code-Bildungsziel (string)[]

    Possible values: [GS, HS, RS, GY-SEK-I, GY-SEK-II]

    jahrgangsstufen components-code-Jahrgangsstufe (string)[]

    Possible values: [01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13]

    faecher

    object[]

  • Array [

    • oneOf

    kennung components-code-Fächerkanon (string)

    Possible values: [BI, CH, CI, DE, DS, EK, EN, FR, GR, NL, IT, SN, KU, LA, RS, GE, PO, PW, RE, RI, RK, SP, SU, TE, TG, WE, WN, WS, DA, MA, HW, MU, PA, PH, IF, AW, GL, PWI, PTE, PGUS, NAT]

    Diese Codeliste ist spezifisch für das Bundesland Niedersachsen:

    • BI Biologie
    • CH Chemie
    • CI Chinesisch
    • DE Deutsch
    • DS Darstellendes Spiel
    • EK Erdkunde
    • EN Englisch
    • FR Französisch
    • GR Griechisch
    • NL Niederländisch
    • IT Italienisch
    • SN Spanisch
    • KU Kunst
    • LA Latein
    • RS Russisch
    • GE Geschichte
    • PO Politik
    • PW Politik/Wirtschaft
    • RE Evangelische Religion
    • RI Islamische Religion
    • RK Katholische Religion
    • SP Sport
    • SU Sachunterricht
    • TE Technik
    • TG Textiles Gestalten
    • WE Gestaltendes Werken
    • WN Werte und Normen
    • WS Wirtschaft
    • DA Deutsch als Zweitsprache
    • MA Mathematik
    • HW Hauswirtschaft
    • MU Musik
    • PA Pädagogik
    • PH Physik
    • IF Informatik
    • AW Arbeit-Wirtschaft-Technik
    • GL Gesellschaftslehre
    • PWI Profil Wirtschaft
    • PTE Profil Technik
    • PGUS Profil Gesundheit und Soziales
    • NAT Naturwissenschaften

  • ]

    • laufzeit

    object

    oneOf

    von date

    Anfang des Gültigkeitszeitraums der Gruppe. Dieser Zeitpunkt kann auch in der Zukunft liegen.

    bis date

    Ende des Gültigkeitszeitraums der Gruppe.

    gruppenzugehoerigkeit

    object

    rollen components-code-Gruppenrolle (string)[]required

    Possible values: [Lern, Lehr, KlLeit, Foerd, VLehr, SchB, GMit, GLeit], >= 1

    sonstige_gruppenzugehoerige

    object[]

  • Array [

    • ktid stringrequired

    ID des Personenkontexts, welcher der Gruppe zugeordnet ist. Referenziert ein bestehendes Objekt des Schulconnex-Servers.

    rollen components-code-Gruppenrolle (string)[]required

    Possible values: [Lern, Lehr, KlLeit, Foerd, VLehr, SchB, GMit, GLeit]

    von date

    Beginn der Gruppenzugehörigkeit. Dieser Zeitpunkt kann auch in der Zukunft liegen.

    bis date

    Ende der Gruppenzugehörigkeit.

  • ]

  • ]

    • beziehungen

    object

    hat_als_beziehungen

    object[]

  • Array [

    • ktid stringrequired

    ID des Personenkontexts, zu dem eine Beziehung besteht. Referenziert ein bestehendes Objekt des Schulconnex-Servers.

    beziehung components-code-Beziehungen (string)required

    Possible values: [SchB, SorgBer]

    Beziehungen ist eine Liste von Beziehungen, welche zwischen zwei Personen innerhalb von Personenkontexten bestehen können:

    • SorgBer Sorgeberechtigter oder Sorgeberechtigte
    • SchB Schulbegleiter oder Schulbegleiterin

  • ]

    • ist_von_beziehungen

    object[]

  • Array [

    • ktid stringrequired

    ID des Personenkontexts, zu dem eine Beziehung besteht. Referenziert ein bestehendes Objekt des Schulconnex-Servers.

    beziehung components-code-Beziehungen (string)required

    Possible values: [SchB, SorgBer]

    Beziehungen ist eine Liste von Beziehungen, welche zwischen zwei Personen innerhalb von Personenkontexten bestehen können:

    • SorgBer Sorgeberechtigter oder Sorgeberechtigte
    • SchB Schulbegleiter oder Schulbegleiterin

  • ]

    • erreichbarkeiten

    object[]

  • Array [

    • typ components-code-Erreichbarkeitstyp (string)required

    Possible values: [E-Mail]

    Wie folgt:

    • E-Mail E-Mail-Adressen müssen RFC 5322 (Internet Message Format) erfüllen
    kennung emailrequired

    Konkrete Angabe der zum Erreichen der Person oder Organisation notwendigen Information.

  • ]

    • personenstatus components-code-Personenstatus (string)

    Possible values: [Aktiv]

    Wie folgt:

    • Aktiv aktiv
    jahrgangsstufe components-code-Jahrgangsstufe (string)

    Possible values: [01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13]

    Wie folgt:

    • 01 Jahrgangsstufe 1
    • 02 Jahrgangsstufe 2
    • 03 Jahrgangsstufe 3
    • 04 Jahrgangsstufe 4
    • 05 Jahrgangsstufe 5
    • 06 Jahrgangsstufe 6
    • 07 Jahrgangsstufe 7
    • 08 Jahrgangsstufe 8
    • 09 Jahrgangsstufe 9
    • 10 Jahrgangsstufe 10
    • 11 Jahrgangsstufe 11
    • 12 Jahrgangsstufe 12
    • 13 Jahrgangsstufe 13
    rolle components-code-Rolle (string)required

    Possible values: [Lern, Lehr, SorgBer, Extern, OrgAdmin, Leit, SysAdmin, SchB, NLehr]

    Wie folgt:

    • Lern Lernende/-r
    • Lehr Lehrende/-r
    • SorgBer Sorgeberechtigte/-r
    • Extern externe Person
    • OrgAdmin Organisationsadministrator
    • Leit Organisationsleitung
    • SysAdmin Systemadministrator
    • Schulbegleiter/-in
    • Nicht-lehrendes Personal

    loeschung

    object

    zeitpunkt date-time

    Datum und Uhrzeit der Löschung des Personenkontexts.

  • ]

  • ]

Loading...