Estrazione stato apprendimento utenti API

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):

Mappatura degli stati utente

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

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.