Estrazione completamento progressi utente API

Scopo

Cyber Guru offre la possibilità di acquisire i tassi di completamento dei moduli formativi per ogni utente della propria organizzazione mediante una REST API che restituisce i dati in formato JSON, pronti per essere integrati in sistemi di reportistica esterni.

Per ogni utente l’API restituisce il numero di moduli assegnati e completati, la percentuale di completamento complessiva e il dettaglio per singolo servizio (Awareness e Channel).
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 progress completion:

URL: https://<host>/ext/report/users-progress-completion

Consente di ottenere il dettaglio del progresso formativo per ogni utente della company. Per invocare l’API è necessario fornire il token ottenuto in precedenza come Bearer token.
L’API prende in ingresso i seguenti parametri (metodo GET):

Struttura della response

Ogni record utente nella risposta contiene i seguenti campi:

La percentuale di completamento vale 0 quando non è ancora stato assegnato alcun modulo per quel servizio.

Esempi di response

Response base (senza paginazione):

{
  "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 con paginazione:

{
  "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
  }
}

I campi dell’oggetto pagination hanno lo stesso significato descritto per gli altri servizi di reportistica.

Errori

Note tecniche

• Per dataset con molti 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.
• I dati restituiti escludono automaticamente utenti cancellati, sospesi e privi di licenza attiva, nonché utenti a cui non è ancora stato assegnato alcun modulo.

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.