Zum Hauptinhalt springen

Personendatensätze des Quellsystemanbieters.

GET 
/personen

Mittels dieses Endpunkts werden alle Personendatensätze zurückgegeben, auf die der Quellsystemanbieter zugreifen darf.

Ein READ muss mit einer HTTP-GET Anfrage erfolgen. Die Schnittstelle /personen ermöglicht das Verwenden von Filterparametern zur Präzisierung der Anfrage bei HTTP-GET. Werden mehrere Filter angegeben, so sind sie als mit „und“ verknüpft anzusehen. Die mehrfache Nutzung des gleichen Filters in einer Anfrage darf nicht erfolgen. Entsprechen keine Werte den angegebenen Filtern, so wird als Resultat eine leere Liste geliefert.

Folgende Tabelle listet die zur Verfügung stehenden Filter:

FilterTypBeschreibung
referrerStringMöglichkeit, die Ergebnisliste der Anfrage nach dem Fremdschlüssel referrer zu filtern. Der Schulconnex-Server überprüft, ob der Wert des Filterparameters ohne Beachtung von Groß- und Kleinschreibung im Filter-Attribut beinhaltet ist (contains).
mandantStringMöglichkeit, die Ergebnisliste der Anfrage nach dem Attribut mandant zu filtern. Der Schulconnex-Server überprüft, ob der Wert des Filterparameters unabhängig von Groß- und Kleinschreibung im Filter-Attribut beinhaltet ist (contains).
familiennameStringMöglichkeit, die Ergebnisliste der Anfrage nach dem Attribut person.name.familienname zu filtern. Der Schulconnex-Server überprüft, ob der Wert des Filter-parameters ohne Beachtung von Groß- und Kleinschreibung im Filter-Attribut beinhaltet ist (contains).
vornameStringMöglichkeit, die Ergebnisliste der Anfrage nach dem Attribut person.name.vorname zu filtern. Der Schulconnex-Server überprüft, ob der Wert des Filter-parameters ohne Beachtung von Groß- und Kleinschreibung im Filter-Attribut beinhaltet ist (contains).
sichtfreigabeStringErlaubt es Personen, abhängig davon aufzulisten, ob diese von einer anderen Organisation zum Lesen freigegeben wurden. Die möglichen Optionen sind sichtfreigabe=ja, um nur die durch externe Organisationen freigegebenen Personen beziehungsweise Personenkontexte aufzulisten und sichtfreigabe=nein, um nur eigene Personen beziehungsweise Personenkontexte aufzulisten. Wird nicht nach Sichtfreigabe gefiltert, so werden alle lesbaren Personen, beziehungsweise Personenkontexte geliefert.

Die Antwort-Nutzdaten (Response Payload) beinhalten ein Array von JSON-Objekten vom Datentyp „Personendatensatz“, sofern Einträge (ggf. passend zu den optionalen Filtern) existieren. Siehe auch die einzelnen Datenmodelle zu Personendatensatz und Person.

Die Ergebnisliste beinhaltet ausschließlich Datensätze vom Datentyp „Person“ beziehungsweise erweitert über das Attribut personendatensatz.personenkontexte Personenkontexte, welche der eigenen Organisation zugeordnet werden können. Der Schulconnex-Server übernimmt diese Information aus dem access_token.

Request​

Query Parameters

    referrer string
    mandant string
    familienname string
    vorname string
    sichtfreigabe string

Responses​

OK

Schema

  • Array [

    • person

    object

    id stringrequired

    ID der Person. Wird vom Schulconnex-Server vergeben und ist eindeutig. Dieses Attribut ist unveränderbar (immutable).

    mandant stringrequired

    ID des Mandanten, dem die Personen zugeordnet ist. Wird vom Schulconnex-Server vergeben und ist eindeutig.

    revision stringrequired

    Revision der Person. Wird vom Schulconnex-Server mit der Erstellung des Datensatzes sowie Aktualisierung generiert. Dieser Wert kann nicht von Quellsystemen oder Diensten gesetzt werden.

    referrer string

    Identifikations-ID einer Person. Wird vom Quellsystem vergeben und muss im Quellsystem eindeutig sein (z. B. eine einheitliche Personalnummer).

    stammorganisation string

    ID der Stammorganisation. Personen können einer Organisation angehören, jedoch zeitweise an einer anderen Organisation tätig sein. Der häufigste Anwendungsfall ist die Abordnung eines Lehrenden an eine andere Dienststelle. Die Stammorganisation ist unabhängig vom Personenkontext.

    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.

    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.
    auskunftssperre components-code-Boolean (string)required

    Possible values: [Ja, Nein]

    Die Codeliste „Boolean“ regelt das Mapping der deutschen Wörter „ja“ und „nein“ auf die englischen Begriffe „true“ und „false“:

    • Ja true
    • Nein false

    personenkontexte

    object[]

  • Array [

    • id stringrequired

    ID des Personenkontexts.

    mandant stringrequired

    ID des Mandanten, dem der Personenkontext zugeordnet ist.

    organisation

    object

    Organisation.

    id stringrequired

    ID der Organisation.

    referrer string

    ID des Personenkontexts im Quellsystem.

    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
    sichtfreigabe components-code-Boolean (string)

    Possible values: [Ja, Nein]

    Die Codeliste „Boolean“ regelt das Mapping der deutschen Wörter „ja“ und „nein“ auf die englischen Begriffe „true“ und „false“:

    • Ja true
    • Nein false

    loeschung

    object

    zeitpunkt date-time

    Datum und Uhrzeit der Löschung des Personenkontexts.

    revision stringrequired

    Revision des Personenkontexts.

  • ]

  • ]

Loading...