API: Erläuterung zu den Person-Daten: Struktur und Aufbau

[xwolfde]

Erläuterung zu den Personendaten aus der API:

Eine Person, die über die API erfragt wird, hat 1 Zordnung mit Kerndaten zum Schema Person in /persons/ und 1-n Zuordnungen zu einer Funktion bei einer Organisation und 0-n Zuordnungen zu einem Arbeitsplatz in /contacts/.

Ein Datensatz einer Person (Endpoint /person/) kann dabei so aussehen:

{
  "data": [
    {
      "@context": {
        "@base": "https://api.fau.de/pub/v1/opendir/"
      },
      "@type": "Person",
      "@id": "persons/1234567890",
      "identifier": "1234567890",
      "givenName": "Erika",
      "familyName": "Musterfrau",
      "pronoun": "he/she/it",
      "personalTitle": "Prof. Dr.",
      "personalTitleSuffix": "Ph.D.",
      "titleOfNobility": "van",
      "email": "[email protected]",
      "telephone": "+49 9131 85-12345",
      "contacts": [
        {
          "@type": "Contact",
          "@id": "contacts/0123456789",
          "identifier": "0123456789",
          "organization": {
            "@type": "Organization",
            "@id": "organizations/abc0123456",
            "identifier": "abc0123456",
            "longDescription": {
              "de": "Testorganisationseinheit",
              "en": "Test Organizational Unit"
            },
            "name": "Testorganisationseinheit"
          },
          "function": "scientific_employee",
          "functionLabel": {
            "de": "Wissenschaftliche Mitarbeiter",
            "en": "Scientific staff"
          }
        }
      ]
    }
  ]
  
}

Der Array der Contacts beeinhaltet dann die Informationen, woran die Person hängt. Also an welcher Organisation und dort in welchen Funktionen.

Die Endpoint /contacts/ zeigt dann die verschiedene Funktionen (mindestens 1) und etwaige Arbeitsplätze (0 bis n) die die Person dabei haben kann.

{
  "data": [
    {
      "@context": {
        "@base": "https://api.fau.de/pub/v1/opendir/"
      },
      "@type": "Contact",
      "@id": "contacts/abc1234567",
      "identifier": "abc1234567",
      "person": {
        "@type": "Person",
        "@id": "persons/bc12345678",
        "identifier": "bc12345678"
      },
      "organization": {
        "@type": "Organization",
        "@id": "organizations/c123456789",
        "identifier": "c123456789",
        "longDescription": {
          "de": "Testorganisationseinheit",
          "en": "Test Organizational Unit"
        },
        "name": "Testorganisation"
      },
      "givenName": "Erika",
      "familyName": "Musterfrau",
      "pronoun": "he/she/it",
      "personalTitle": "Prof. Dr.",
      "personalTitleSuffix": "Ph.D.",
      "titleOfNobility": "van",
      "nameSuffix": "OMG",
      "function": "scientific_employee",
      "functionLabel": {
        "de": "Wissenschaftliche Mitarbeiter",
        "en": "Scientific staff"
      },
      "socials": [
        {
          "platform": "github",
          "url": "https://github.com/erikamusterfrau"
        }
      ],
      "workplaces": [
        {
          "room": "01.234",
          "floor": "01",
          "street": "Musterstraße 1",
          "zip": "91058",
          "city": "Erlangen",
          "faumap": "https://karte.fau.de/api/v1/iframe/famos/12345",
          "phones": [
            "+49 9131 85-12345"
          ],
          "fax": "+49 9131 85-1234567",
          "url": "https://www.test.fau.de/person/erika-musterfrau/",
          "mails": [
            "[email protected]"
          ],
          "officeHours": [
            {
              "weekday": 1,
              "from": "07:30",
              "to": "16:00"
            }
          ],
          "consultationHours": [
            {
              "weekday": 2,
              "from": "07:30",
              "to": "16:00",
              "comment": "nur über Zoom",
              "url": "https://fau.zoom-x.de/j/1234567890?pwd=fG5xSxQ2dXNu3EMwAWgzSUpBSEFqUT16"
            }
          ],
          "consultationHoursByAggreement": true,
          "consultationHoursContactType": "mail",
          "consultationHoursContactHint": "omg"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "count": 20,
    "total": 1009,
    "offset": 0,
    "remaining": 989,
    "page": 1
  }
}

Wichtig dabei:

• Eine Funktion hängt auch immer an einer Organisation.
• Es kann auch sein, dass eine Person über keinen Arbeitsplatz verfügt!
• Jeder Arbeitsplatz hängt an der Funktion. Je Arbeitsplatz kann es unterschiedliche Kontaktdaten, z.B. Sprechstundenzeiten und auch Mailadressen/Telefon geben.

Wenn wir also eine Person anzeigen wollen gbt es mehrere Modi:

• Person im allgemeinen Kontext mit allen Verküpfungen zu verschiedenen Organisationen und unterschiedlichen Funktionen zeigen (selten)
• Person allgemein im Kontext einer Organisation zeigen, z.B. als Mitarbeiter eines Lehrstuhls mit einer oder mehreren Funktionen
• Person mit einer spezifischen Funktion im Kontext einer Organisation zeigen, z.B. in der Liste der wissenschaftlichen Mitarbeiter

[xwolfde]

Addendum: Welche Funktionsrollen gibt es?

Die function kann derzeit folgende Default-Werte enthalten:

• administrative_employee
• assistentprofessor
• campo_administrator
• custom
• custom_public
• deputy
• doctoratecandidate_without_contract
• employee
• guestlecturer
• guestresearcher
• honorary_professor
• idm_coordinator
• it_support_staff
• junior_professor
• leader
• professor
• researchassistant
• retired_professor
• scholarshipholder
• scientific_employee
• secretary
• studentemployee
• technical_employee
• trainee
• visitinglecturer
• workplace_manager

Bei jeder Instanz wird aber neben "function" auch "functionLabel" mit den Übersetzungen geliefert, also z.B. für scientific_employee:

functionLabel: { "de" : "Wissenschaftliche Mitarbeitende", "en" : "Research associates" }

Die beiden Rollen "custom" und "custom_public" sind benutzerdefinierte Rollen. Ein Beispiel von unserem CISO:

{ ..., "function" : "custom", "functionLabel" : { "de" : "CISO", "en" : "CISO" }, ... }

Die o.g. Liste kann man auch wie folgt über die API ermitteln:

curl --request GET \
  --url 'https://api.fau.de/pub/v1/opendir/aggr/distinct/contacts?distinct=function' \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: {{apikey}}' 

Allerdings muss man hier auf Übersetzungen aufpassen.

[xwolfde]

Hinweis zur Suche nach Personen:
Wenn man mit der Mailadresse nach Personen sucht, muss man nach aktuellem Stand möglicherweise zwei Suchen machen.
Wenn eine Person mindestens einen oder mehrere Arbeitsplätze hat, ist die Mailadresse einem Arbeitsplatz zugeordnet und dann nicht mehr im Endpoint /persons/ ! Das hat die Konsequenz, dass man bei Suche nach einer Mailadresse zuerst im contacts -Endpoint suchen muss. Und erst, wenn dort kein Treffer kommt, sucht man nochmal mit dem /persons/ Endpoint.

Vgl. auch #64