Rest API GraphQL

Beschreibung

Die GraphQL-basierte API von HAWK Intelligent Technologies bietet dir die Möglichkeit, verschiedene Daten für die Personal- und Produktionsplanung in getaiplan abzufragen. Mit einer flexiblen Struktur kannst du genau die Daten anfordern, die du benötigst, und so den Overhead minimieren. In dieser Dokumentation findest du grundlegende Informationen zur API-Nutzung, zur Abfrage von Arbeitszeiten, Qualifikationen, Schichtplänen und Mitarbeiterdaten sowie die passenden Beispiele.

Zusammenfassung

Die API erlaubt es dir, Daten effizient abzufragen und bietet volle Kontrolle über die Auswahl der gewünschten Daten.

Die API ist über GraphQL zugänglich und unterstützt verschiedene Query-Typen, um gezielt Informationen zu Arbeitszeiten, Qualifikationen, Schichten und Mitarbeiterdaten zu erhalten. Du kannst individuelle Filter anwenden, um nur die relevanten Informationen zu bekommen. Dank der flexiblen GraphQL-Struktur werden unnötige Daten vermieden, was zu effizienteren Abfragen führt.

Ziel

Dieses Tutorial zeigt dir, wie du die wichtigsten Query-Typen der GraphQL-API nutzt, um relevante Daten für die Personaleinsatzplanung und Schichtverwaltung abzufragen.

Arbeitszeiten (targetworktimes)

Du kannst mit dieser Query geplante Arbeitszeiten für einen bestimmten Zeitraum und eine Rolle abfragen.

Beispiel:

{
  targetworktimes(timeframe: "[2024-01-01, 2024-01-31)", role: "Hawk") {
    staffnumber
    prename
    surname
    plandate
    planworktime
  }
}

Parameter:

• timeframe (Daterange!): Der gewünschte Datumsbereich, z.B. "[2024-01-01, 2024-01-31)".

• role (String): Optionaler Filter für die Rolle des Mitarbeiters, z.B. "Hawk".

Beispiel-Antwort:

{
  "data": {
    "targetworktimes": [
      {
        "staffnumber": "001",
        "prename": "Max",
        "surname": "Mustermann",
        "plandate": "2024-01-15",
        "planworktime": "8:00"
      }
    ]
  }
}

Qualifikationen (qualifications)

Mit dieser Query kannst du Qualifikationsdaten der Mitarbeiter abrufen, gefiltert nach Gültigkeitsdatum und weiteren Parametern.

Beispiel:

{
  qualifications(validDate: "2024-12-31", usePortationidents: true, limit: 5, offset: 0) {
    userPrename
    userSurname
    qualificationRole
    qualificationValidFrom
    qualificationValidUntil
    qualificationLevelName
    qualificationLevelValue
  }
}

Parameter:

• validDate (Date): Optional, um nur Qualifikationen zu erhalten, die zu einem bestimmten Datum gültig sind.

• usePortationidents (Boolean): Entscheidet, ob Portation-Idents oder Titel verwendet werden.

• limit (Int): Optionale Begrenzung der Anzahl der Ergebnisse.

• offset (Int): Startpunkt der Datenabfrage für Pagination.

Beispiel-Antwort:

{
  "data": {
    "qualifications": [
      {
        "userPrename": "John",
        "userSurname": "Doe",
        "qualificationRole": "Software Engineer",
        "qualificationValidFrom": "2022-01-01",
        "qualificationValidUntil": "2025-12-31",
        "qualificationLevelName": "Expert",
        "qualificationLevelValue": 5
      }
    ]
  }
}

Schichten (shifts)

Diese Query liefert Informationen über Schichten basierend auf einem Zeitraum und anderen Filtern.

Beispiel:

{
  shifts(t0: "2023-09-01", t1: "2024-09-30", sort: start_asc, limit: 5, offset: 0) {
    systemtitle
    shifttitle
    firmstructure
    shifttype
    start
    end
    allday
    product
  }
}

Parameter:

• t0 (Date): Startdatum des Abfragezeitraums.

• t1 (Date): Enddatum des Abfragezeitraums.

• sort (ShiftinstanceDataEnum): Sortierreihenfolge, z.B. nach Startzeit.

• limit (Int): Begrenzung der Ergebnisse.

• offset (Int): Startpunkt für Pagination.

Beispiel-Antwort:

{
  "data": {
    "shifts": [
      {
        "systemtitle": "Schicht 1",
        "shifttitle": "Frühschicht",
        "firmstructure": "Abteilung A",
        "shifttype": "Unkategorisiert",
        "start": "2023-09-01T08:00:00",
        "end": "2023-09-01T16:00:00",
        "allday": false,
        "product": null
      }
    ]
  }
}

Mitarbeiter (users)

Diese Query ermöglicht es, Mitarbeiterdaten basierend auf verschiedenen Filtern abzufragen.

Beispiel:

{
  users(staffnumber: "12345", limit: 1, offset: 0) {
    externid
    staffnumber
    prename
    surname
    location
    position
    rightrole
  }
}

Parameter:

• staffnumber (String): Filtert nach der Mitarbeiternummer.

• limit (Int): Begrenzung der Anzahl der Ergebnisse.

• offset (Int): Startpunkt der Datenabfrage.

Beispiel-Antwort:

{
  "data": {
    "users": [
      {
        "externid": null,
        "staffnumber": "12345",
        "prename": "Max",
        "surname": "Mustermann",
        "location": "Köln",
        "position": null,
        "rightrole": "Mitarbeiter"
      }
    ]
  }
}

Gut zu wissen

Wo im Programm

Die API kann über die GraphiQL-Oberfläche getestet und genutzt werden. Hier hast du direkten Zugriff auf das API-Schema und kannst Queries interaktiv durchführen.

Rechteeinstellung

Um auf die API zuzugreifen, ist eine Authentifizierung notwendig. Die API nutzt Basic Authentifikation, bei der Benutzername und Passwort im Header der HTTP-Anfrage übermittelt werden. Stelle sicher, dass alle API-Abfragen über HTTPS gesendet werden, um die Daten zu schützen.

Definitionen

GraphQL: Ein Abfragesystem, das es ermöglicht, nur die benötigten Daten von einem Server abzurufen.
Query: Eine Anfrage, die an die API gesendet wird, um Daten zu erhalten.
Daterange: Ein Datumsbereich, der für Zeitabfragen verwendet wird.

Fachbegriffe

Basic Authentifikation: Ein Authentifizierungsverfahren, bei dem Benutzername und Passwort in Base64 kodiert im HTTP-Header gesendet werden.
Pagination: Die Technik, Daten in Seiten zu unterteilen, um große Mengen an Ergebnissen Schritt für Schritt abzurufen.

Keywords

GraphQL, API, Arbeitszeiten, Qualifikationen, Schichten, Mitarbeiter, Abfragen, Personalplanung