Scopo
Cyber Guru offre la possibilità di acquisire lo stato di apprendimento degli utenti rispetto ai contenuti loro assegnati mediante una REST API che restituisce i dati in formato JSON, pronti per essere integrati in sistemi di reportistica esterni (es. Docebo o piattaforme LMS del cliente).
L’API fornisce una lista unificata degli utenti con il relativo stato formativo, un riepilogo aggregato per stato e supporto alla paginazione per la gestione di grandi dataset.
La presente linea guida contiene le direttive e i parametri per l’invocazione del servizio.
Ambito
Le informazioni si applicano alla piattaforma di Cyber Security Awareness Cyber Guru 2.0.
Prerequisiti
- Il cliente deve disporre delle risorse tecnologiche per poter chiamare REST API.
Procedura
Cyber Guru mette a disposizione due REST API:
Get token:
URL: https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
Questa API consente di ottenere un token di autorizzazione. Parametri di chiamata (metodo POST):
- client_id : ext-api
- client_secret : (fornito da Cyber Guru)
- grant_type : client_credentials
Get users learning status:
URL: https://<host>/ext/report/users-learning-status
Consente di ottenere la lista degli utenti con il relativo stato di apprendimento. Per invocare l’API è necessario fornire il token ottenuto in precedenza come Bearer token.
L’API prende in ingresso i seguenti parametri (metodo GET):
| Parametro | Tipo | Obbligatorio | Descrizione |
| service | stringa | No | Filtra per servizio: aw = Awareness, ch = Channel |
| team | stringa | No | Filtra per team specifico |
| status | intero | No | 0 = not-active, 1 = not-regular, 2 = regular, 3 = aligned |
| limit | intero | No | Numero massimo di risultati per pagina (min: 1, max: 1000) |
| page | intero | No | Pagina di risultati da recuperare (default: 1) |
Mappatura degli stati utente
| Valore | Label | Descrizione |
| 0 | not-active | L’utente non ha ancora accettato la policy |
| 1 | not-regular | L’utente ha molti contenuti in sospeso |
| 2 | regular | L’utente ha pochi contenuti in sospeso |
| 3 | aligned | L’utente ha completato tutti i contenuti assegnati |
Esempi di response
Response base (senza paginazione):
{
"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 con paginazione:
{
"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
}
}
Quando viene applicato il filtro status, il campo summary riporta il conteggio esclusivamente per lo stato filtrato.
Response con filtro status (es. 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 }
}
I campi dell’oggetto pagination hanno lo stesso significato descritto per le altre API del servizio Rankings.
Errori
| Codice HTTP | Codice errore | Descrizione |
| 400 | EXT_1000 | Parametro di input non valido (il messaggio indica quale parametro e i valori ammessi) |
| 400 | EXT_1000 | La pagina richiesta non esiste (il messaggio indica il totale delle pagine disponibili) |
| 404 | EXT_1003 | Errore nel recupero dei dati |
| 422 | EXT_1004 | Il team indicato non esiste nella company |
| 500 | EXT_1001 | Token scaduto o non valido |
Note tecniche
- Per dataset con più di 1000 utenti è consigliato utilizzare sempre i parametri limit e page per evitare timeout.
- Il valore di limit dovrebbe essere scelto in proporzione alla dimensione della popolazione aziendale censita in piattaforma.
Cyber Guru è a disposizione per supportare il cliente nella fase di configurazione e di test su ambiente di staging e, a valle dell’esito positivo, in ambiente di produzione.