Abruf des Lernstatus der Nutzer per API

Zweck

Cyber Guru bietet die Möglichkeit, den Lernstatus der Nutzer in Bezug auf die ihnen zugewiesenen Inhalte über eine REST API abzurufen. Die Daten werden im JSON-Format bereitgestellt und können einfach in externe Berichtssysteme (z. B. Docebo oder kundeneigene LMS-Plattformen) integriert werden.
Die API liefert eine einheitliche Liste der Nutzer mit ihrem jeweiligen Lernstatus, eine aggregierte Zusammenfassung nach Status sowie Unterstützung für die Paginierung zur Verwaltung großer Datensätze.
Diese Richtlinie enthält die Vorgaben und Parameter für die Nutzung des Dienstes.

Geltungsbereich

Die Informationen gelten für die Cyber Security Awareness Plattform Cyber Guru 2.0.

Voraussetzungen

• Der Kunde muss über die technischen Ressourcen verfügen, um REST APIs aufrufen zu können.

Vorgehensweise

Cyber Guru stellt zwei REST APIs zur Verfügung:

Get token:

URL: https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token

Mit dieser API kann ein Autorisierungstoken abgerufen werden. Aufrufparameter (POST-Methode):

• client_id : ext-api
• client_secret : (wird von Cyber Guru bereitgestellt)
• grant_type : client_credentials

Get users learning status:

URL: https://<host>/ext/report/users-learning-status

Ermöglicht das Abrufen der Nutzerliste mit dem jeweiligen Lernstatus. Für den API-Aufruf muss das zuvor erhaltene Token als Bearer Token übergeben werden.
Die API akzeptiert folgende Parameter (GET-Methode):

Mapping der Nutzerstatus

Beispiele für Responses

Basis-Response (ohne Paginierung):

{
  "users": [
    { "firstname": "Anna", "lastname": "Ferrari", "email": "anna.ferrari@company.com", "team": "Finance", "status": "aligned" },
    { "firstname": "Marco", "lastname": "Rossi", "email": "marco.rossi@company.com", "team": "IT Operations", "status": "regular" },
    { "firstname": "Luigi", "lastname": "Bianchi", "email": "luigi.bianchi@company.com", "team": "Sales EMEA", "status": "not-active" }
  ],
  "total_users": 3,
  "summary": {
    "not-active": 1,
    "not-regular": 0,
    "regular": 1,
    "aligned": 1
  }
}

Response mit Paginierung:

{
  "users": [
    { "firstname": "Anna", "lastname": "Ferrari", "email": "anna.ferrari@company.com", "team": "Finance", "status": "aligned" },
    { "firstname": "Marco", "lastname": "Rossi", "email": "marco.rossi@company.com", "team": "IT Operations", "status": "regular" }
  ],
  "total_users": 150,
  "summary": { "not-active": 10, "not-regular": 30, "regular": 50, "aligned": 60 },
  "pagination": {
    "current_page": 1, "per_page": 10, "total_items": 150, "total_pages": 15,
    "from": 1, "to": 10, "has_next": true, "has_prev": false,
    "next_page": 2, "prev_page": null, "first_page": 1, "last_page": 15
  }
}

Wenn der Status-Filter angewendet wird, enthält das summary-Feld ausschließlich die Zählung für den gefilterten Status.

Response mit Status-Filter (z. B. status=0):

{
  "users": [
    { "firstname": "Luigi", "lastname": "Bianchi", "email": "luigi.bianchi@company.com", "team": "Sales EMEA", "status": "not-active" }
  ],
  "total_users": 1,
  "summary": { "not-active": 1 }
}

Die Felder des Objekts pagination haben die gleiche Bedeutung wie bei den anderen APIs des Rankings-Services.

Fehler

Technische Hinweise

• Für Datensätze mit mehr als 1000 Nutzern sollten immer die Parameter limit und page verwendet werden, um Timeouts zu vermeiden.
• Der Wert für limit sollte im Verhältnis zur Größe der in der Plattform erfassten Unternehmenspopulation gewählt werden.

Cyber Guru steht Ihnen gerne zur Verfügung, um Sie bei der Konfiguration und beim Testen in der Staging-Umgebung zu unterstützen und nach erfolgreichem Abschluss auch in der Produktionsumgebung zu begleiten.