Formato JSON importación de usuarios y cuentas
Al utilizar el mecanismo de importación de usuarios via consola se necesita de un archivo JSON con los datos correspondientes.
Lo que detallamos a continuación es el formato de dicho archivo, el schema que se usa para su validación y las consideraciones puntuales sobre los datos.
Formato archivo
El archivo JSON en cuestión puede contener datos sobre personas, cuentas o ambas entidades lo que permite definir al momento de realizar el proceso cuales datos se necesitan incorporar.
Principalmente el archivo se divide en 3 secciones:
- Encabezado: Donde constan los datos de quien realiza la exportación de los mismos y los mantiene. Por ej la siguiente estructura:
{
"name": "agentesExport",
"description": "Exportación de usuarios para SIU-Araí.",
"mantainer": "toba",
"mantainer-email": "toba@siu.edu.ar",
}
- Personas: Donde se encuentran los registros que identifican a las personas usuarias del módulo / sistema que exporto los datos.
Los mismos incluyen datos identificatorios de la persona, de contacto e inclusive pueden contener datos laborales asociados (ej el atributo employeeNumber, que representa el número del legajo en SIU-Mapuche).
{
"people": [
{
"givenName": "JORGE ALEJANDRO",
"sn": "MARTINEZ",
"cn": "JORGE ALEJANDRO MARTINEZ",
"mail": "eljorgedelpueblo@yahoo.com.ar",
"bloqueada": "1",
"employeeNumber": "234",
"genero": "M",
"documento": {
"tipo": "DNI",
"numero": "34505855"
}
},
{
"givenName": "NORA CRISTINA",
"sn": "PAGANO",
"cn": "NORA CRISTINA PAGANO",
"mail": "hijadelviento@fibertel.com.ar",
"bloqueada": "1",
"employeeNumber": "71",
"genero": "F",
"documento": {
"tipo": "DNI",
"numero": "11533321"
}
}
]
}
Estos datos, si bien permiten identificar a la persona no brindan ninguna conexión con el módulo/s en particular. Algunos ejemplos pueden ser: datos de agentes de SIU-Mapuche, alumnos o docentes de SIU-Guaraní, así como cualquier fuente externa que pueda proveer información de personas.
Para generar dicha relación entre usuarios y acceso a módulos, se encuentra la última sección de Cuentas.
Atención: Existen mas datos en la estructura que los visualizados en el ejemplo, para determinar cual de ellos necesita le sugerimos se dirija al schema.
- Cuentas: Donde se encuentran los registros que relacionan a las personas usuarias con el módulo / sistema que exporto los datos.
Los mismos incluyen datos de identificación y autenticación, asi mismo contienen los datos de la persona a la cual se asocia la cuenta a fin de identificarla unívocamente.
{
"accounts": [
{
"uid": "141",
"appName": "SIU-Guarani",
"uniqueIdentifier": "141",
"password": "$2a$1354cGeON2kk7cA/TtsbrZHMOmQ1kDfh2.quIRLCdiQdf6DePL1kLmsS",
"passwordAlgorithm": "crypt",
"person": {
"givenName": "José Daniel",
"sn": "Arenero",
"cn": "Arenero, José Daniel",
"bloqueada": "0",
"genero": "F",
"documento": {
"tipo": "DNI",
"numero": "27945183"
}
}
},
{
"uid": "3123",
"appName": "SIU-Guarani",
"uniqueIdentifier": "3123",
"password": "$2a$10$5UkZ87uN1n4.Yn244O2G5uqVmEaWRC6f9cbe.12kB66FrnPH.7sei",
"passwordAlgorithm": "crypt",
"person": {
"givenName": "DELFINO RAUL",
"sn": "ABAJO",
"cn": "ABAJO, DELFINO RAUL",
"bloqueada": "0",
"genero": "F",
"documento": {
"tipo": "DNI",
"numero": "41667821"
}
}
},
]
}
El campo appName deberá contener el nombre con el que fue registrada la aplicación en Arai-Usuarios. Es posible que también figure bajo el campo appUniqueId, el cual en este caso debería contener el identificador único con el que está registrado dicha aplicación en Arai-Usuarios.
El campo uniqueIdentifier contendrá el identificador de la cuenta en el módulo/sistema en cuestión (id local), este valor no necesariamente coincidirá con el que deba utilizar el usuario al momento de autenticarse contra el componente IDP en Arai-Usuarios.
Consideraciones sobre los datos
Los ejemplos previos se incluyen a modo de visualización de la estructura, existen campos que no estan presentes allí que son de utilidad y otros que estando presentes tienen semánticas específicas.
Aplicación
El campo appName (o su alternativa appUniqueId) identifican la aplicación a la cual se vinculará la cuenta del usuario, su falta en el archivo json determina que dicha persona será ignorada durante la importación, ya que no se puede crear una cuenta sin una aplicación destino independientemente de que esta última existe o no en Arai-Usuarios.
Si únicamente desea incorporar los usuarios o no sabe a que aplicación se vincularán, utilice la sección people en su lugar.
Por otra parte, el campo mail por ejemplo en la sección correspondiente a las personas, si bien no es obligatorio (según la versión de Arai-Usuarios) es conveniente que dicho dato se encuentre presente pues:
- la completitud de los datos es fundamental (en un circuito de EEI, Sudocu requiere que el usuario tenga email)
- permite que el usuario pueda autogestionar sus cambios de contraseña
- es requerido para establecer un segundo factor de autenticación para el usuario
En algunas versiones de Araí-Usuarios, este campo permite incorporar mas de una dirección de mail separada por coma (,) (a partir de la v3.1.2), aunque dicho comportamiento se mantiene por el momento... recomendamos hacer uso de una estrategia alternativa para incorporar más de una direccion de mail en la persona.
A partir de la version v3.1.5 se incorporan como elementos separadores de cuentas de mails los siguientes caracteres: (;) punto y coma, (/) barra , (|) pipe.
En particular recomendamos utilizar el campo extra que permite indicar otros atributos de la persona, por tanto usar esto
{
"people": [
{
"givenName": "JORGE ALEJANDRO",
"sn": "MARTINEZ",
"cn": "JORGE ALEJANDRO MARTINEZ",
"mail": "eljorgedelpueblo@unx.edu.ar,",
"bloqueada": "1",
"employeeNumber": "234",
"genero": "M",
"documento": {
"tipo": "DNI",
"numero": "34505855"
},
"extra" : {
"mails": "eljorgedelpueblo@yahoo.com.ar, jorgemartinez1784@hotmail.com"
}
}
]
}
en lugar de
{
"people": [
{
"givenName": "JORGE ALEJANDRO",
"sn": "MARTINEZ",
"cn": "JORGE ALEJANDRO MARTINEZ",
"mail": "eljorgedelpueblo@unx.edu.ar, eljorgedelpueblo@yahoo.com.ar, jorgemartinez1784@hotmail.com",
"bloqueada": "1",
"employeeNumber": "234",
"genero": "M",
"documento": {
"tipo": "DNI",
"numero": "34505855"
}
}
]
}
En caso que se encuentre el segundo formato, por el momento se honrarán los datos y se tomará la siguiente semántica:
- La primer cuenta de mail incorporada será considerada como
mail principal(en el ejemplo,eljorgedelpueblo@unx.edu.ar) - El resto de las cuentas que figuren se considerarán como un atributo extra del usuario y se incoporarán dentro de
mails
Schema validación
Para validar la estructura del archivo se utiliza un JSON schema, el cual ademas validará el formato de los campos para que no se incluyan caracteres no válidos para los mismos.
Este schema se puede obtener desde el paquete Arai Json-Migrator el cual se instala junto al componente IDM de Arai-Usuarios, el mismo se puede visualizar aquí.
¿Como exporto los datos?
En general los sistemas basados en SIU-Toba poseen un mecanismo presente para la exportación de estos datos, queda a responsabilidad del módulo/sistema realizar los ajustes que sean necesarios (mediante extensión de comandos de consola) ya sea para recuperar los datos desde otras fuentes o para realizar ajustes sobre su procesamiento previo a la exportación.
¿Que modificar?
En caso que se necesite únicamente recuperar los datos desde una fuente alternativa, lo que se debería extender y redefinir sería el método toba_aplicacion_modelo_base::getDatosUsuarios respetando el nombre de las columnas y los datos incluídos en ellas.
En caso de ser necesario ajustes en el tratamiento de los datos es posible que necesite redefinir distintos métodos, entre ellos:
toba_aplicacion_comando_base::opcion__exportar_usuarios_arai para incorporar mas parámetros y/o agregar controles o procesamientos extra.
toba_aplicacion_modelo_base::generatePerson en caso de necesitar agregar campos especificos a la lista de atributos extra.
Tenga en cuenta que los módulos del ecosistema SIU pueden tener sus propios comandos para gestionar la exportación de usuarios/cuentas, en general debería seguir los parámetros antes expuestos pero sin dudas les recomendamos consultar con el equipo previo a realizar alguna modificación.
Implementando mi exportador
Podemos generar la exportacion de datos de diversas maneras, mediante un archivo PHP plano o utilizando el paquete siu-arai/arai-json-migrator que es el mismo utilizado por SIU-Arai.
Con PHP plano
Para exportar los datos via un PHP plano, lo unico que debemos hacer es recuperar los datos desde nuestra fuente, organizarlos en un array tipo recordset y luego utilizar la funcion de PHP para convertirlo en JSON.
Por ej:
function recuperarDatosFormateados()
{
$resultado = [];
$data = getDatosDb();
//Armamos la estructura ciclando por los datos
foreach($data as $valores) {
.
.
.
}
return $resultado;
}
$archivoNombre = './exportacion_arai.json';
$arregloDatos = recuperarDatosFormateados();
$archivo = file_put_contents($archivoNombre, json_encode($arregloDatos));
Usando siu-arai/arai-json-migrator
En este caso la exportación se realiza instanciando las clases de entidades del paquete e invocando a los metodos correspondientes para el seteo de los datos recuperados desde la/s fuente/s.
Un ejemplo de como instanciar y/o utilizar estas clases se puede ver aqui