Extraction de la progression de complétion des utilisateurs via l’API

Objectif

Cyber Guru offre la possibilité d’obtenir les taux de complétion des modules de formation pour chaque utilisateur de votre organisation via une API REST qui renvoie les données au format JSON, prêtes à être intégrées dans des systèmes de reporting externes.

Pour chaque utilisateur, l’API fournit le nombre de modules attribués et complétés, le pourcentage global de complétion ainsi que le détail par service (Awareness et Channel).
Ce guide contient les instructions et paramètres nécessaires pour appeler le service.

Périmètre

Les informations s’appliquent à la plateforme de Cyber Security Awareness Cyber Guru 2.0.

Prérequis

• Le client doit disposer des ressources techniques nécessaires pour appeler une API REST.

Procédure

Cyber Guru met à disposition deux API REST :

Obtenir un token :

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

Cette API permet d’obtenir un jeton d’autorisation. Paramètres d’appel (méthode POST) :

• client_id : ext-api
• client_secret : (fourni par Cyber Guru)
• grant_type : client_credentials

Obtenir la progression des utilisateurs :

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

Permet d’obtenir le détail de la progression de formation pour chaque utilisateur de l’entreprise. Pour appeler l’API, il est nécessaire de fournir le token obtenu précédemment comme Bearer token.
L’API accepte les paramètres suivants (méthode GET) :

Structure de la réponse

Chaque enregistrement utilisateur dans la réponse contient les champs suivants :

Le pourcentage de complétion est de 0 lorsqu’aucun module n’a encore été attribué pour ce service.

Exemples de réponse

Réponse de base (sans pagination) :

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

Réponse avec pagination :

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

Les champs de l’objet pagination ont la même signification que pour les autres services de reporting.

Erreurs

Notes techniques

• Pour les jeux de données comportant de nombreux utilisateurs, il est conseillé d’utiliser systématiquement les paramètres limit et page afin d’éviter les timeout. La valeur de limit doit être choisie en fonction de la taille de la population d’utilisateurs enregistrée sur la plateforme.
• Les données renvoyées excluent automatiquement les utilisateurs supprimés, suspendus ou sans licence active, ainsi que les utilisateurs à qui aucun module n’a encore été attribué.

Cyber Guru reste à disposition pour accompagner le client lors de la configuration et des tests sur l’environnement de staging et, après validation, sur l’environnement de production.