Extraction de l’état d’apprentissage des utilisateurs via l’API

Objectif

Cyber Guru offre la possibilité d’obtenir l’état d’apprentissage des utilisateurs par rapport aux contenus qui leur sont attribués 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 (ex. Docebo ou plateformes LMS du client).
L’API fournit une liste unifiée des utilisateurs avec leur statut de formation, un résumé agrégé par statut et la prise en charge de la pagination pour la gestion de grands ensembles de données.
Ce guide contient les directives et paramètres pour l’appel du 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 technologiques nécessaires pour appeler des 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 le statut d’apprentissage des utilisateurs :

URL : https://<host>/ext/report/users-learning-status

Permet d’obtenir la liste des utilisateurs avec leur statut d’apprentissage. 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) :

Mappage des statuts utilisateur

Exemples de réponse

Réponse de base (sans pagination) :

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

Réponse avec pagination :

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

Lorsque le filtre status est appliqué, le champ summary indique uniquement le nombre d’utilisateurs pour le statut filtré.

Réponse avec filtre status (ex. 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 }
}

Les champs de l’objet pagination ont la même signification que ceux décrits pour les autres API du service Rankings.

Erreurs

Notes techniques

• Pour les ensembles de données de plus de 1000 utilisateurs, il est recommandé d’utiliser systématiquement les paramètres limit et page afin d’éviter les timeouts.
• La valeur de limit doit être choisie en fonction de la taille de la population d’utilisateurs enregistrée sur la plateforme.

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.