Crear grupo/subgrupo

Método: POST

URL: /admin/rest/administration/api/groups

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups
• Formulario:
  
  • external_id=exg1&name=Grupo1&description=Grupo para alumnos aula 1&parentId=1234&extendedField[Intercambio]=true&extendedField[Deporte]=1

Parámetros

• external_id = Id externo (String, obligatorio).  Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
• name = Nombre del grupo (sin comas) (String, obligatorio)
• description = Descripción del grupo (String, opcional)
• parentId = Id del grupo padre si se está creando un subgrupo (Long, opcional)
• extendedField[nombre del campo extendido] (lista) = Nombre y valor de los campos extensibles (clave-valor de Strings, opcional*)
  * solo son obligatorios aquellos campos extensibles que estén marcados como obligatorios y no tengan definido ningún valor por defecto
  
  • Valores permitidos:
    
    • Si el campo extendido es de tipo texto --> cualquier texto
    • Si el campo extendido es de tipo entero --> sólo números
    • Si el campo extendido es de tipo si/no --> valores "true" o "false"
    • Si el campo extendido es de tipo lista de valores --> un valor válido de la lista

Validaciones

• Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request) 
  
• El external id nuevo ya existe en un grupo --> Error ERR006 / 400 (Bad Request)
• El parent id es incorrecto --> Error GRP001 / 400 (Bad Request)
• El nombre no es válido, las comas no están permitidas --> Error GRP004 / 400 (Bad Request)
• El nombre de un campo extensible no existe --> Error DYN001 / 400 (Bad Request)
• El valor de un campo extensible tiene tipo incorrecto --> Error DYN002 / 400 (Bad Request)
• Falta algun campo extensible obligatorio --> Error DYN003 / 400 (Bad Request)
  
  • No se ha incluido el campo obligatorio en la petición y no tiene asignado el valor por defecto
  • Se ha incluido el campo en la petición pero se le ha asignado un valor vacío

Respuesta OK

• 201 (Created) + cabecera 'Location' con el link al recurso creado

Modificar grupo/subgrupo

Método: PUT

URL:

• Modificar por id: 
  
  • /admin/rest/administration/api/groups/id/{id}
• Modificar por id externo:
• • /admin/rest/administration/api/groups/externalid/{external_id}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487
• Formulario:
  • external_id=exg1&name=Grupo1&description=Grupo para alumnos aula 1&parentId=1234&extendedField[Intercambio]=true&extendedField[Deporte]=1

Parámetros

• external_id = Id externo nuevo (String, obligatorio)    Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /  
• name = Nombre del grupo (sin comas) (String, obligatorio)
• description = Descripción del grupo (String, opcional)
• parentId = Id del grupo padre si se está creando un subgrupo (Long, opcional)
• extendedField[nombre del campo extendido] (lista) = Nombre y valor de los campos extensibles (clave-valor de Strings, opcional*)
  * solo son obligatorios aquellos campos extensibles que estén marcados como obligatorios y no tengan definido ningún valor por defecto
  
  • Valores permitidos:
    
    • Si el campo extendido es de tipo texto --> cualquier texto
    • Si el campo extendido es de tipo entero --> sólo números
    • Si el campo extendido es de tipo si/no --> valores "true" o "false"
    • Si el campo extendido es de tipo lista de valores --> un valor válido de la lista

NOTA: Los campos no obligatorios que vayan vacíos se borrarán.

Validaciones

• Lista de parámetros vacía o algún campo obligatorio sin cubrir --> Error ERR001 / 400 (Bad Request)
• No existe el grupo --> Error 404 (Not Found)
• El external id nuevo ya existe en un grupo --> Error ERR006 / 400 (Bad Request)
• El parent id es incorrecto --> Error GRP001 / 400 (Bad Request)
• El nombre no es válido, las comas no están permitidas --> Error GRP004 / 400 (Bad Request)
• El nombre de un campo extensible no existe --> Error DYN001 / 400 (Bad Request)
• El valor de un campo extensible tiene tipo incorrecto --> Error DYN002 / 400 (Bad Request)
• Falta algun campo extensible obligatorio --> Error DYN003 / 400 (Bad Request)
  
  • No se ha incluido el campo obligatorio en la petición y no tiene asignado el valor por defecto
  • Se ha incluido el campo en la petición pero se le ha asignado un valor vacío
• Todo OK --> 200 (OK)

Obtener grupo

Método: GET

URL:

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

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/2

Campos devueltos en el Json

Grupo, cada grupo consta de los siguientes campos:

• id = Identificador
• external_id = Id externo.
• parentId = Identificador de grupo padre
• name = Nombre de grupo
• description = Descripción de grupo
• extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValue

Validaciones

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

Obtener grupos raíz sin paginar

Método: GET

URL: /admin/rest/administration/api/groups

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups

Campos devueltos en el Json

Listado de grupos raíz, cada grupo consta de los siguientes campos:

• id = Identificador
• external_id = Id externo
• parentId = Id del grupo al que pertenece en caso de que sea un grupo
• name = Nombre
• description = Descripción
• extendedFields = Campos extensibles

Validaciones

• El grupo no existe --> Error 404 (Not Found)
• El grupo no tiene subgrupos --> Error 204 (No Content)
• Error en la generación del Json --> Error 503 (Service Unavailable)
• Todo OK --> 200 (OK) + JSON

Obtener subgrupos de un grupo

Método: GET

URL:

• Obtener por id: 
  
  • /admin/rest/administration/api/groups/id/{id}/subgroups
• Obtener por external id:
• /admin/rest/administration/api/groups/externalid/{external_id}/subgroups

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/2564/subgroups

Campos devueltos en el Json

Listado de subgrupos, cada subgrupo consta de los siguientes campos:

• id = Identificador
• external_id = Id externo
• parentId = Id del grupo al que pertenece en caso de que sea un subgrupo
• name = Nombre
• description = Descripción
• e xtendedFields   = Campos extensibles

Validaciones

• El grupo no existe --> Error 404 (Not Found)
• El grupo no tiene subgrupos --> Error 204 (No Content)
• Error en la generación del Json --> Error 503 (Service Unavailable)
• Todo OK --> 200 (OK) + JSON

Eliminar grupo/subgrupo

Método: DELETE

URL:

• Eliminar por id: 
  
  • /admin/rest/administration/api/groups/id/{id}
• Eliminar por id externo:
• /admin/rest/administration/api/groups/externalid/{external_id}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487

Cabeceras

• NLC-includeSubgroups: Opcional, valores permitidos:
  • true: se borrarán también todos los subgrupos que cuelguen del grupo borrado
  • false: no se borrarán subgrupos. Si el grupo tiene subgrupos dará un error de validación.
  • El valor por defecto es false.

Validaciones

• No existe el grupo --> Error 404 (Not Found)
• El grupo tiene subgrupos --> Error 400 (Bad Request)
• Todo OK --> 200 (OK)

Añadir usuarios a un grupo/subgrupo (v1)

Método: POST

URL:

• Añadir por id: 
  
  • /admin/rest/administration/api/groups/id/{id}/users?action={action}
• Añadir por id externo:
  
  • /admin/rest/administration/api/groups/externalid/{external_id}/users?action={action}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/users?action=addByUserIds
• Formulario:
  • id=51476&id=654165&id=6566

Parámetros

• action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
  
  • Valores permitidos 
    
    • addByUserIds
    • addByUserExternalids
• id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)

Campos devueltos en el Json (en caso de que algún usuario haya dado error)

• status: KO
• ids / external ids: listado de ids o external ids que han dado error

Validaciones

• Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
• Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
• Se ha escogido la acción "addByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
• No existe el grupo --> Error 400 (Not Found)
• Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
• Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON

Añadir usuarios a un grupo/subgrupo (v2)

Método: POST

URL:

• Añadir por id: 
  
  • /admin/rest/administration/api/groups/id/{id}/users?action={action}
• Añadir por id externo:
  
  • /admin/rest/administration/api/groups/externalid/{external_id}/users?action={action}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/users?action=addByUserIds
• Formulario:
  • id=51476&id=654165&id=6566

Parámetros

• action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
  
  • Valores permitidos 
    
    • addByUserIds
    • addByUserExternalids
• id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)

Campos devueltos en el Json (en caso de que algún usuario haya dado error)

• status: KO
• ids / external ids: listado de ids o external ids que han dado error y los códigos de error
  
  • GRP002: El usuario no existe
  • GRP003: El usuario ya existe en el grupo

Validaciones

• Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
• Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
• Se ha escogido la acción "addByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
• No existe el grupo --> Error 400 (Not Found)
• Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
• Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON
  
  

Obtener los usuarios de un grupo/subgrupo

Método: GET

URL:

• Obtener por id: 
  
  • Sin paginación: /admin/rest/administration/api/groups/id/{id}/users
  • Sin paginación versión reducida: /admin/rest/administration/api/groups/id/{id}/users&reduced=true
  • Con paginación: /admin/rest/administration/api/groups/id/{id}/users?startIndex={startIndex}&count={count}
  • Con paginación versión reducida: /admin/rest/administration/api/groups/id/{id}/users?startIndex={startIndex}&count={count}&reduced=true
• Obtener por external id: 
  
  • Sin paginación: /admin/rest/administration/api/groups/externalid/{external_id}/users
  • Sin paginación versión reducida: /admin/rest/administration/api/groups/externalid/{external_id}/users&reduced=true
  • Con paginación: /admin/rest/administration/api/groups/externalid/{external_id}/users ?startIndex={startIndex}&count={count}
  • Con paginación versión reducida: /admin/rest/administration/api/groups/externalid/{external_id}/users ?startIndex={startIndex}&count={count}&reduced=true

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/345/users?startIndex=0&count=100

Parámetros

• startindex = índice inicial para la paginación (Integer, opcional)
• count = total de elementos a recuperar para la paginación (Integer, opcional)

Campos devueltos en el Json

Listado de usuarios, cada usuario consta de los siguientes campos:

• id = Identificador
• external_id = Id externo
• username = Nombre de usuario
• firstName = Nombre
• lastName = Apellidos
• preferredLanguage = Idioma predeterminado
• personTimezoneId = Zona horaria
• roles = Roles del usuario
• email = Correo electrónico del usuario
• officePhoneNumber = Teléfono de oficina
• mobilePhoneNumber = Teléfono móvil
• address = Dirección
• jobTitle = Puesto
• location = Departamento
• organization = Compañía
• aboutMe = Sobre mí
• interests = Intereses
• status = Estado
• extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValue

Cuando se pasa el parámetro reduced=true los campos devueltos serán los siguientes:

• id = Identificador
• external_id = Id externo
• username = Nombre de usuario
• email = Correo electrónico del usuario
• status = Estado

Validaciones

• Índices erróneos --> Error 416 (Requested Range Not Satisfiable)
  
  • Usando paginación, ambos índices deben tener un valor
• Si el grupo no existe --> Error 404 (Not Found)
• No hay usuarios --> Error 204 (No Content)
• Error en la generación del Json --> Error 503 (Service Unavailable)
• Todo OK 
  
  • Si no hay paginación --> 200 (OK) + JSON
  • Si hay paginación --> 206 (Partial Content) + JSON

Eliminar usuarios de un grupo/subgrupo

Método: DELETE

URL:

• Eliminar por id: 
  
  • /admin/rest/administration/api/groups/id/{id}/users?action={action}
• Eliminar por id externo:
  
  • /admin/rest/administration/api/groups/externalid/{external_id}/users?action={action}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/users?action=removeByUserIds
• Formulario:
  
  • id=51476&id=654165&id=6566

Parámetros

• action = acción que se quiere realizar (borrar usando ids de usuarios o ids externos) (String, obligatorio)
  
  • Valores permitidos 
    
    • removeByUserIds
    • removeByUserExternalids
• id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)    Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /

Campos devueltos en el Json (en caso de que algún usuario haya dado error)

• status: KO
• ids / external ids: listado de ids o external ids que han dado error

Validaciones

• Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
• Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
• Se ha escogido la acción "removedByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
• No existe el grupo --> Error 400 (Not Found)
• Ejecución OK y todos los usuarios han sido eliminados --> 200 (OK)
• Ejecución OK y algún usuario no ha podido ser eliminado --> 200 (OK) + JSON

Obtener administradores de grupo

Método: GET

URL:

• Obtener por id: 
  
  • /admin/rest/administration/api/groups/id/{id}/admins
• Obtener por external id: 
  
  • /admin/rest/administration/api/groups/externalid/{external_id}/admins

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/2/admins

Campos devueltos en el Json

Administrador, cada administrador consta de los siguientes campos:

• id = Identificador
• external_id = Id externo
• username = Nombre de usuario
• firstName = Nombre
• lastName = Apellidos
• preferredLanguage = Idioma predeterminado 
• personTimezoneId = Zona horaria 
• roles = Roles del usuario 
• email = Correo electrónico del usuario
• officePhoneNumber = Teléfono de oficina
• mobilePhoneNumber = Teléfono móvil
• address = Dirección
• jobTitle = Puesto
• location = Departamento
• organization = Compañía
• aboutMe = Sobre mí
• interests = Intereses
• status = Estado
• extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValues
• teamManagerUsername = Nombre de usuario del jefe de equipo

Validaciones

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

Añadir administradores a un grupo/subgrupo

Método: POST

URL:

• Añadir por id: 
  
  • /admin/rest/administration/api/groups/id/{id}/admins?action={action}
• Añadir por id externo:
  
  • /admin/rest/administration/api/groups/externalid/{external_id}/admins?action={action}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/admins?action=addByUserIds
• Body:
  

  • {
    "ids": [51476,654165]
    }

Parámetros

• action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
  
  • Valores permitidos 
    
    • addByUserIds
    • addByUserExternalids
• id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)

Campos devueltos en el Json (en caso de que algún usuario haya dado error)

• status: KO
• ids / external ids: listado de ids o external ids que han dado error y los códigos de error
  
  • GRP002: El usuario no existe
  • GRP003: El usuario ya es administrador de grupo
  • GRP005: El usuario no tiene rol de administrador de la formación.

Validaciones

• Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
• Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
• Se ha escogido la acción "addByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
• No existe el grupo --> Error 400 (Not Found)
• Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
• Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON

Eliminar administradores de un grupo/subgrupo

Método: DELETE

URL:

• Añadir por id: 
  
  • /admin/rest/administration/api/groups/id/{id}/admins?action={action}
• Añadir por id externo:
  
  • /admin/rest/administration/api/groups/externalid/{external_id}/admins?action={action}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/admins?action=deleteByUserIds
• Body:
  

  • {
    "ids": [51476,654165]
    }

Parámetros

• action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
  
  • Valores permitidos 
    
    • deleteByUserIds
    • deleteByUserExternalids
• id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)

Campos devueltos en el Json (en caso de que algún usuario haya dado error)

• status: KO
• ids / external ids: listado de ids o external ids que han dado error y los códigos de error
  
  • GRP002: El usuario no existe
  • GRP006: El usuario no es administrador del grupo.

Validaciones

• Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
• Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
• Se ha escogido la acción "deleteByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
• No existe el grupo --> Error 400 (Not Found)
• Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
• Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON