Extracción del estado de aprendizaje de los usuarios mediante API

Propósito

Cyber Guru ofrece la posibilidad de obtener el estado de aprendizaje de los usuarios respecto a los contenidos asignados mediante una REST API que devuelve los datos en formato JSON, listos para integrarse en sistemas de reportes externos (por ejemplo, Docebo o plataformas LMS del cliente).
La API proporciona una lista unificada de usuarios con su respectivo estado de formación, un resumen agregado por estado y soporte para paginación para gestionar grandes volúmenes de datos.
Esta guía contiene las directrices y parámetros para invocar el servicio.

Ámbito

La información se aplica a la plataforma de Concienciación en Ciberseguridad Cyber Guru 2.0.

Requisitos previos

• El cliente debe contar con los recursos tecnológicos necesarios para poder consumir REST API.

Procedimiento

Cyber Guru pone a disposición dos REST API:

Obtener token:

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

Esta API permite obtener un token de autorización. Parámetros de la petición (método POST):

• client_id : ext-api
• client_secret : (proporcionado por Cyber Guru)
• grant_type : client_credentials

Obtener estado de aprendizaje de los usuarios:

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

Permite obtener la lista de usuarios con su respectivo estado de aprendizaje. Para invocar la API es necesario proporcionar el token obtenido previamente como Bearer token.
La API recibe los siguientes parámetros (método GET):

Mapeo de estados de usuario

Ejemplos de respuesta

Respuesta básica (sin paginación):

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

Respuesta con paginación:

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

Cuando se aplica el filtro status, el campo summary muestra el conteo solo para el estado filtrado.

Respuesta con filtro status (ej. 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 }
}

Los campos del objeto pagination tienen el mismo significado que en las demás API del servicio Rankings.

Errores

Notas técnicas

• Para datasets con más de 1000 usuarios se recomienda utilizar siempre los parámetros limit y page para evitar timeouts.
• El valor de limit debe elegirse en proporción al tamaño de la población de la empresa registrada en la plataforma.

Cyber Guru está disponible para apoyar al cliente en la fase de configuración y pruebas en el entorno de staging y, tras un resultado positivo, en el entorno de producción.