API Acciones formativas

Owned by Netex Sistemas
Last updated: Dec 20, 2022 by Netex Support
8 min read

Usar codificación de caracteres UTF-8 en el envío de datos

Manual de autenticación y versionado: manual (autenticación y versionado)

Por motivos de seguridad el external_id no puede contener los caracteres \ ni /  (http://tomcat.apache.org/security-6.html).


Obtener acción formativa (v1)

Método: GET

URL: 

  • Obtener por id: 
    • /admin/rest/administration/api/sessions/id/{id}
  • Obtener por external id: 
    • /admin/rest/administration/api/sessions/externalid/{externalid}


Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /

Ejemplo:

Cabeceras

  • NLC-datesFormat. Opcional, valores permitidos:
    • milliseconds. Las fechas se devolverán en milisegundos
    • en otro caso se seguirá el formato de texto: "yyyy-MM-dd HH:mm:ss"

Campos devueltos en el Json

Cada acción formativa consta de los siguientes campos:

  • id = Identificador
  • external_id = Id externo
  • name = Nombre de la acción formativa
  • sessionType = Tipo de acción formativa (uno de los Strings siguientes):
    • classroom
    • externalLink
    • externalwebconference
    • file
    • practicalCase
    • performanceReview
    • scorm
    • video
    • webconference

  • startDate = Fecha de inicio de acción formativa (UTC)

  • endDate = Fecha de fin de acción formativa (UTC)

  • capacity = Capacidad de alumnos

  • estimateDuration = Duración estimada

  • confirmed = Valor true/false. Indica si la acción está confirmada

  • description = Descripción de la acción formativa

  • objectives = Objetivos de la acción formativa

  • comments = Comentarios de la acción formativa

  • status = Estado de la acción formativa.

  • moduleActivity = Objeto de relación de actividad y módulo
    • id = Identificador
    • moduleId = Identificador de módulo

    • activityId = Identificador de actividad

  • extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValues

Validaciones

  • No existe la acción formativa --> Error 404 (Not Found)
  • Error en la generación del Json --> Error 503 (Service Unavailable)
  • Todo OK --> 200 (OK) + JSON

Obtener acción formativa (v2)

Método: GET

URL: 

  • Obtener por id: 
    • /admin/rest/administration/api/sessions/id/{id}
  • Obtener por external id: 
    • /admin/rest/administration/api/sessions/externalid/{externalid}


Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /

Ejemplo:

Cabeceras

  • NLC-datesFormat. Opcional, valores permitidos:
    • milliseconds. Las fechas se devolverán en milisegundos
    • en otro caso se seguirá el formato de texto: "yyyy-MM-dd HH:mm:ss"

Campos devueltos en el Json

Cada acción formativa consta de los siguientes campos:

  • id = Identificador
  • external_id = Id externo
  • name = Nombre de la acción formativa
  • sessionType = Tipo de acción formativa (uno de los Strings siguientes):
    • classroom
    • externalLink
    • externalwebconference
    • file
    • practicalCase
    • performanceReview
    • scorm
    • video
    • webconference

  • startDate = Fecha de inicio de acción formativa (UTC)

  • endDate = Fecha de fin de acción formativa (UTC)

  • capacity = Capacidad de alumnos

  • estimateDuration = Duración estimada

  • confirmed = Valor true/false. Indica si la acción está confirmada

  • description = Descripción de la acción formativa

  • objectives = Objetivos de la acción formativa

  • comments = Comentarios de la acción formativa

  • status = Estado de la acción formativa.

  • moduleActivity = Objeto de relación de actividad y módulo
    • id = Identificador
    • moduleId = Identificador de módulo

    • activityId = Identificador de actividad

  • extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValues
  • moderatorUrl = Url de acceso para el formador (* Solo para el caso de sessionType = externalwebconference) 
  • studentUrl = Url de acceso para el estudiante (* Solo para el caso de sessionType = externalwebconference) 
  • trainers = Formadores de la acción formativa (* Solo pasa el caso de sessionType = classroom o externalwebconference o practicalCase o webconference)
    • id = Identificador del formador
    • firstName = Nombre del formador
    • lastName = Apellidos del formador
    • username = Nombre de usuario del formador
    • email = Email del formador
  • rooms = Salas vinculadas a la acción formativa (* Solo para el caso de sessionType = classroom) 
    • id = Identificador de la sala 
    • name = Nombre de la sala
  • scorable = Acción formativa evaluable 
  • minScore = Nota mínima para superar 
  • maxScore = Nota máxima que se puede obtener 
  • scoreToPass = Nota de superación 
  • weightInModule = Peso dentro del curso (* Solo tendrá valor para el caso de evaluación por puntuación mínima) 
  • percentageWeightInModule = Porcentaje del peso dentro del curso (* Solo tendrá valor para el caso de evaluación por puntuación mínima) 

Validaciones

  • No existe la acción formativa --> Error 404 (Not Found)
  • Error en la generación del Json --> Error 503 (Service Unavailable)
  • Todo OK --> 200 (OK) + JSON

Obtener evaluaciones

Método: GET

URL:

  • Obtener por id:
    • /admin/rest/administration/api/sessions/id/{id}/evaluations
  • Obtener por external id:
    • /admin/rest/administration/api/sessions/externalid/{external_id}/evaluations


Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /

Ejemplo:

Parámetros

  • personId= filtra por el id de un alumno (Long, opcional)
  • personExternalId=filtra por el id externo de un alumno (String, opcional)
  • username= filtra por el nombre de usuario de un alumno (String, opcional)

Campos devueltos en el Json

Listado de evaluaciones de los alumnos del curso, cada evaluación consta de los siguientes campos:

  • evaluation_id = Identificador de la evaluación
  • student_id = Identificador del alumno.
  • external_id = Identificador externo del alumno.
  • username = nombre de usuario.
  • score = nota del alumno en la acción formtiva (en caso de tener), esta nota está normalizada (entre 0 y 100).
  • totaltime = tiempo dedicado a la acción formativa por el alumno en horas, minutos y segundos.
  • firstAccess = fecha del primer acceso del alumno a la acción formativa.
  • lastAccess = fecha del último acceso del alumno a la acción formativa.
  • status = Estado del alumno en la acción formativa (PASSED, NOT_PASSED, NOT_ATTEMPTED, EVALUATION_PENDING, IN_PROGRESS, BLOCKED, AVAILABLE, PENDING). 

  • attendance = Asistencia a la acción formativa

  • timesAttempted = Número de intentos

  • timesAccessedWeb = Número de accesos desde la interfaz web

  • timesAccessedApp = Número de accesos desde la app

  • comments = Observaciones

  • rawScore = Nota en crudo, las scorm serán igual (entre 0 y 100), pero en las presenciales evaluables la nota irá en el rango configurado (nota mínima-nota máxima).

Validaciones

  • Id. de acción formativa inexistente --> Error ERR004 / 404 (Not Found)
  • Id. externo de acción formativa inexistente --> Error ERR005 / 404 (Not Found)
  • Error en la generación del Json --> Error 503 (Service Unavailable)
  • Todo OK --> 200 (OK) + JSON
  • Todo OK sin contenido (No hay evaluaciones)--> 204 (No content)

Modificar evaluaciones

Método: PUT

URL:

  • Obtener por id:
    • /admin/rest/administration/api/sessions/id/{id}/evaluations
  • Obtener por external id:
    • /admin/rest/administration/api/sessions/externalid/{external_id}/evaluations

Ejemplo:

https://demo.central-lms.com/admin/rest/administration/api/sessions/id/2004/evaluations


BODY - application/x-www-form-urlencoded
[
   { 
      "evaluation_id":70,
      "student_id":1,
      "external_id":null,
      "username":"admin",
      "score":0.0,
      "totaltime":"00:00:11",
      "firstAccess":"2018-11-19 09:38:19",
      "lastAccess":"2018-11-19 09:38:19",
      "status":"IN_PROGRESS",
      "attendance":true,
      "timesAttempted":0,
      "timesAccessedWeb":1,
      "timesAccessedApp":0,
      "comments":null,
      "rawScore":0.0
   },
...
{...}
]


 Parámetros

Listado de evaluaciones de los alumnos del curso, cada evaluación consta de los siguientes campos:

  • evaluation_id = Identificador de la evaluación, no editable. Este campo es el que tendremos en cuenta para editar la evaluación concreta, al pasarse un listado de ellas.
  • student_id = Identificador del alumno, no editable.
  • external_id = Identificador externo del alumno, no editable.
  • username = nombre de usuario, no editable.
  • score = nota del alumno en la acción formtiva (en caso de tener), esta nota está normalizada (entre 0 y 100), no editable. La nota que editamos será rawScore.
  • totaltime = tiempo dedicado a la acción formativa por el alumno en horas, minutos y segundos. Formato HH:mm:ss.
  • firstAccess = fecha del primer acceso del alumno a la acción formativa. Formato YYYY-MM-dd HH:mm:ss. Va siempre con el timezone UTC.
  • lastAccess = fecha del último acceso del alumno a la acción formativa. Formato YYYY-MM-dd HH:mm:ss. Va siempre con el timezone UTC.
  • status = Estado del alumno en la acción formativa (PASSED, NOT_PASSED, NOT_ATTEMPTED, IN_PROGRESS). Sólo aceptamos los siguientes cuatro estados. Este además es un campo calculado, modificaremos lo necesario para que su estado pase a ser el que se indica y controlaremos que los parámetros que les afectan sean válidos (rawScore y attendance).
    • NOT_ATTEMPTED: se corresponde con una evaluación reseteada, o no iniciada. Debería tener el resto de campos editables reseteados.
    • NOT_PASSED se corresponde con un estado de no superación. Se comprobará que la asistencia y la nota sean correctas para tener este estado. No rebasar la nota mínima en presenciales evaluables y asistencia en función del tipo de actividad. En presenciales no evaluables tiene que ser false, en las tipo scorm tiene que ser true (false sería estado NOT_ATTEMPTED) y en las automáticas (link, fichero, vídeo) tiene que ser false. Si es de tipo scorm se pondrán los valores de completion/success a complete/failed. En las aaff presenciales este estado NUNCA podrá darse, ya que requiere que la acción formativa se cierre, por lo tanto vamos a dejar la evaluación para que cuando se cierre la acción formativa pase a este estado.
    • PASSED se corresponde con un estado de superación. Se comprobará que la asistencia y la nota sean correctas para tener este estado (nota mínima en presenciales evaluables y asistencia a true en cualquiera). Para actividades tipo scorm se pondrán los estados de superación y compleción a complete/passed. En las aaff presenciales este estado NUNCA podrá darse, ya que requiere que la acción formativa se cierre, por lo tanto vamos a dejar la evaluación para que cuando se cierre la acción formativa pase a este estado.
    • IN_PROGRESS: Se corresponde con el estado de en progreso. Se valida únicamente la asistencia. attendance=true. En actividades tipo scorm se pondrán los valores de completion/success a incomplete/failed.

  • attendance = Asistencia a la acción formativa

  • timesAttempted = Número de intentos

  • timesAccessedWeb = Número de accesos desde la interfaz web

  • timesAccessedApp = Número de accesos desde la app

  • comments = Observaciones

  • rawScore = Nota en crudo, las scorm serán igual (entre 0 y 100), pero en las presenciales evaluables la nota irá en el rango configurado (nota mínima-nota máxima). Se valida que la nota esté en rango.

Validaciones

  • No existe una acción formativa con ese id/externalid --> Error 404 (Not Found) código de error ERR004/ERR005 dependiendo de si es id o externalid.
  • El estado de la acción formativa es incorrecto --> Error SEV001 / 400 (Bad Request)
  • Evaluaciones. Como pasamos un listado de evaluaciones vamos a modificar las que estén correctas e ignoraremos las que tengan algún error. Por lo tanto devolveremos un código 200, pero devolveremos un json con un listado de errores, con todas las validaciones que fallaron. Estas tendrán un formato similar al de los errores devueltos en WS, salvo que irán en un listado y que tendrán un atributo extra para indicar la evaluación que falló (campo entity_id coincidirá con el campo evaluation_id de la evaluación). El incumplimiento de las siguientes validaciones devolverá un código 200.
    • El formato de las fechas o hora es incorrecto --> Error ERR008
    • El estado configurado no es compatible con la asistencia --> Error SEV002
    • El estado configurado no es compatible con la nota --> Error SEV003
    • Curso finalizado/Alumno no encontrado/Evaluación no encontrada --> Error SEV004 (en el mensaje irá la causa exacta: CONTAINER_FINISH, STUDENT_NOT_FOUND, EVALUATION_ID_NOT_FOUND)
    • Nota fuera de rango --> Error SEV005
    • Puntuación no permitida para este tipo de actividad --> Error SEV006
    • Estado no válido, tiene que ser uno de los siguientes: PASSED, NOT_PASSED, NOT_ATTEMPTED, IN_PROGRESS --> Error SEV007
    • Se puso estado NOT_ATTEMPTED y no tiene todos los valores editables a 0 o null --> Error SEV008
    • La fecha de primer y último acceso se tienen que mandar ambas o ninguna, además la fecha de primer acceso tiene que ser menor o igual a la de último acceso --> Error SEV009
  • Error inesperado –> Error 500
  • Todo OK --> 200 (OK)

Inscribir alumnos

Método: POST

URL:

  • Obtener por id:
    • /admin/rest/administration/api/sessions/id/{id}/students
  • Obtener por external id:
    • /admin/rest/administration/api/sessions/externalid/{external_id}/students

Ejemplo:

https://demo.central-lms.com/admin/rest/administration/api/sessions/id/2004/students


BODY - application/json
{
  "ids":[1,2,3],
  "externalIds":["ext1", "ext2", "ext4"]
}

Cabeceras

  • NLC-enrolInCourseIfNeeded. Opcional, valores permitidos:
    • true. Si el alumno no está inscrito en el curso/plan, lo inscribirá también.
    • en otro caso no se creará nada y devolverá error en el caso de que haya al menos un alumno que no esté inscrito en el curso.

 Parámetros

Objeto json con dos listados:

  • ids = Listado de identificadores de alumnos.
  • externalIds = Listado de identificadores externos de alumnos.

Validaciones

  • No existe una acción formativa con ese id/externalid --> Error 404 (Not Found) código de error ERR004/ERR005 dependiendo de si es id o externalid.
  • El estado de la acción formativa es incorrecto --> Error SEV001 / 400 (Bad Request)
  • Errores que provocan un estado 200, se devuelve un listado de json con códigos de errores y se inscriben el resto de alumnos que no dieron error (si no queda ninguno también devuelve un 200).
    • Alumno no inscrito en el curso (no está a true la cabecera de inscribir también al alumno en el curso) --> Error SEV010 / 200.
    • Id de alumno no encontrado --> Error SEV012 / 200
    • Id externo de alumno no encontrado --> Error SEV011 / 200
    • El alumno ya está incrito en la acción formativa --> Error SEV013 / 200
  • Error inesperado –> Error 500
  • Todo OK --> 200 (OK)

Actualizar urls de acceso (v3)

Método: PUT

URL:

  • Actualizar por id:
    • /admin/rest/administration/api/sessions/id/{id}/webconferenceurls
  • Actualizar por external id:
    • /admin/rest/administration/api/sessions/externalid/{external_id}/webconferenceurls

Ejemplo:

https://clowd-central.learningcloud.me/admin/rest/administration/api/sessions/id/2004/webconferenceurls


BODY - application/json

{
    "trainerUrl" : "www.google.es/trainer",
    "studentUrl" : "www.google.es/student"
}

 Parámetros

Objeto json con dos posibles parámetros:

  • trainerUrl = Url de acceso del formador a la videoconferencia.
  • studentUrl = Url de acceso del estudiante a la videoconferencia.

Validaciones

  • No existe una acción formativa con ese id/externalid --> Error 404 (Not Found) código de error ERR004/ERR005 dependiendo de si es id o externalid.
  • El estado de la acción formativa es incorrecto --> Error SES002 / 400 (Bad Request)
  • La acción formativa no es de tipo videoconferencia externa --> Error SES001 / 400 (Bad Request)
  • No se pasan ninguno de los parámetros (al menos uno es obligatorio) --> Error 404 (Not Found) código de error ERR001
  • Error inesperado –> Error 500
  • Todo OK --> 200 (OK)