Zweck
Cyber Guru bietet die Möglichkeit, die Abschlussquoten der Schulungsmodule für jeden Nutzer Ihrer Organisation über eine REST-API abzurufen. Die Daten werden im JSON-Format bereitgestellt und können einfach in externe Berichtssysteme integriert werden.
Für jeden Nutzer liefert die API die Anzahl der zugewiesenen und abgeschlossenen Module, die gesamte Abschlussquote sowie Details zu den einzelnen Services (Awareness und Channel).
Diese Anleitung enthält die Vorgaben und Parameter für die Nutzung des Dienstes.
Geltungsbereich
Die Informationen beziehen sich auf 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 progress completion:
URL: https://<host>/ext/report/users-progress-completion
Mit dieser API erhalten Sie detaillierte Informationen zum Lernfortschritt jedes Nutzers Ihres Unternehmens. Für den Aufruf der API muss das zuvor erhaltene Token als Bearer-Token übergeben werden.
Die API akzeptiert folgende Parameter (GET-Methode):
| Parameter | Typ | Pflichtfeld | Beschreibung |
| team | String | Nein | Filtert die Ergebnisse für ein bestimmtes Team |
| limit | Integer | Nein | Maximale Anzahl an Ergebnissen pro Seite (min: 1, max: 1000) |
| page | Integer | Nein | Ergebnisseite, die abgerufen werden soll (Standard: 1) |
Struktur der Response
Jeder Nutzerdatensatz in der Antwort enthält folgende Felder:
| Feld | Beschreibung |
| E-Mail-Adresse des Nutzers | |
| assigned_total | Gesamtzahl der zugewiesenen Module über alle Services |
| completed_total | Gesamtzahl der abgeschlossenen Module über alle Services |
| completion_rate_total | Gesamte Abschlussquote (0–100), gerundet auf 2 Dezimalstellen |
| services.awareness | Details zu zugewiesenen, abgeschlossenen Modulen und Abschlussquote für den Service Awareness |
| services.channel | Details zu zugewiesenen, abgeschlossenen Modulen und Abschlussquote für den Service Channel |
Die Abschlussquote beträgt 0, wenn für diesen Service noch kein Modul zugewiesen wurde.
Beispiele für Responses
Basis-Response (ohne Paginierung):
{
"users": [
{
"email": "anna.ferrari@company.com",
"assigned_total": 20, "completed_total": 17, "completion_rate_total": 85.00,
"services": {
"awareness": { "assigned": 12, "completed": 11, "completion_rate": 91.67 },
"channel": { "assigned": 8, "completed": 6, "completion_rate": 75.00 }
}
},
{
"email": "marco.rossi@company.com",
"assigned_total": 20, "completed_total": 20, "completion_rate_total": 100.00,
"services": {
"awareness": { "assigned": 12, "completed": 12, "completion_rate": 100.00 },
"channel": { "assigned": 8, "completed": 8, "completion_rate": 100.00 }
}
}
],
"total_users": 2
}
Response mit Paginierung:
{
"users": [ { "email": "anna.ferrari@company.com", ... } ],
"total_users": 230,
"pagination": {
"current_page": 1, "per_page": 10, "total_items": 230, "total_pages": 23,
"from": 1, "to": 10, "has_next": true, "has_prev": false,
"next_page": 2, "prev_page": null, "first_page": 1, "last_page": 23
}
}
Die Felder des Objekts "pagination" haben die gleiche Bedeutung wie bei den anderen Berichtsdiensten.
Fehler
| HTTP-Code | Fehlercode | Beschreibung |
| 400 | EXT_1000 | Ungültiger Eingabeparameter (die Nachricht gibt an, welcher Parameter und welche Werte zulässig sind) |
| 400 | EXT_1000 | Die angeforderte Seite existiert nicht (die Nachricht gibt die Gesamtzahl der verfügbaren Seiten an) |
| 404 | EXT_1003 | Fehler beim Abrufen der Daten |
| 422 | EXT_1004 | Das angegebene Team existiert im Unternehmen nicht |
| 500 | EXT_1001 | Token abgelaufen oder ungültig |
Technische Hinweise
- Bei Datensätzen mit vielen Nutzern empfiehlt es sich, immer die Parameter "limit" und "page" zu verwenden, um Timeouts zu vermeiden. Der Wert für "limit" sollte entsprechend der Größe der im System erfassten Unternehmenspopulation gewählt werden.
- Die zurückgegebenen Daten schließen automatisch gelöschte, gesperrte und nicht lizenzierte Nutzer sowie Nutzer, denen noch kein Modul zugewiesen wurde, aus.
Cyber Guru unterstützt Sie gerne bei der Konfiguration und beim Testen in der Staging-Umgebung und nach erfolgreichem Abschluss auch in der Produktionsumgebung.