Extracción del progreso de finalización del usuario mediante API

Propósito

Cyber Guru ofrece la posibilidad de obtener las tasas de finalización de los módulos formativos para cada usuario de la organización a través de una REST API que devuelve los datos en formato JSON, listos para integrarse en sistemas de reportes externos.

Para cada usuario, la API devuelve el número de módulos asignados y completados, el porcentaje total de finalización y el detalle por cada servicio (Awareness y Channel).
Esta guía contiene las directrices y los parámetros para invocar el servicio.

Ámbito

La información se aplica a la plataforma de Cyber Security Awareness 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 llamada (método POST):

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

Obtener progreso de finalización de usuarios:

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

Permite obtener el detalle del progreso formativo de cada usuario de la empresa. Para invocar la API es necesario proporcionar el token obtenido previamente como Bearer token.
La API recibe los siguientes parámetros (método GET):

Estructura de la respuesta

Cada registro de usuario en la respuesta contiene los siguientes campos:

El porcentaje de finalización es 0 cuando aún no se ha asignado ningún módulo para ese servicio.

Ejemplos de respuesta

Respuesta básica (sin paginación):

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

Respuesta con paginación:

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

Los campos del objeto pagination tienen el mismo significado que en los demás servicios de reportes.

Errores

Notas técnicas

• Para conjuntos de datos con muchos 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.
• Los datos devueltos excluyen automáticamente a los usuarios eliminados, suspendidos y sin licencia activa, así como a los usuarios a los que aún no se les ha asignado ningún módulo.

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.