2.5/RealizarPersonalizaciones/Php

Personalizar archivos php y metadatos

PageOutline

En el sistema SIU-Diaguita se ha implementado el esquema de personalizaciones ofrecido por el SIU-Toba. Este esquema permite que se realicen cambios sobre un sistema entregado por el SIU y que estos cambios se persistan a través de diferentes versiones. Parte de este sistema consiste en la plataforma COLAB creada y administrada por el SIU, para brindar un espacio de desarrollo colaborativo a las instituciones que los implementan. Para más información ver el proyecto SIU-Diaguita en el COLAB.

A continuación se describe el mecanismo que permite desarrollar una personalización completa del SIU-Diaguita, basandonos en una instalación pre-existente de SIU-Diaguita versión 2.1.x realizada mediante el uso del instalador web (de la cual se utilizará la base de negocios). En futuras correcciones se documentará el proceso partiendo de la situación en que no se cuenta con una implementación.

Personalización intensiva del sistema

Prerequisitos

Para trabajar en la personalización de SIU-Diaguita, se debe contar con:

1. acceso al sistema COLAB (usuario, contraseña y nodo de la institución)
1. entorno SIU-Toba instalado en modo desarrollo, versión 2.7.x
1. servidor web Apache versión 2.2 a 2.4
1. PHP versión 5.4.x a 5.6.x preferentemente con módulos apc, php_pdo, php_pgsql, php_gd 
1. base de datos PostgreSQL versión 8.4 a 9.x
1. JRE versión 1.7
1. para acceder al repositorio COLAB, el cliente subversion versión 1.7.x 
1. identificar unívocamente a cada desarrollador del equipo con un ID numérico, que deben utilizar al momento de instalar SIU-Toba

---

Preparar el entorno de trabajo

Una vez instalado el entorno de desarrollo SIU-Toba, el primer paso consiste en descargarse desde el repositorio COLAB el sistema SIU-Diaguita para el nodo correspondiente a la institución y cargarlo en una instancia SIU-Toba. Mas detalles de la organización y casos de uso del repositorio COLAB para SIU-Diaguita se detalla en la wiki disponible.

#!sh
usuario@host:~$ cd /<ruta_toba_desarrollo>
usuario@host:~$ svn checkout https://colab.siu.edu.ar/svn/diaguita/nodos/<sigla_institucion>/trunk/2.1.0 proyectos/diaguita
usuario@host:~$ bin/toba proyecto cargar -pdiaguita -idesarrollo

Definir la conexión en el archivo

/<ruta_toba_desarrollo>/instalacion/bases.ini

a una base de datos diaguita pre-existente:

#!sh
[desarrollo diaguita diaguita]
motor    = "postgres7"
profile  = "localhost"
usuario  = "<usuario>"
clave    = "<clave>"
puerto   = "5432"
encoding = "LATIN1"
schema   = "diaguita"
base     = "<nombre_db_negocio>"

Migrar a desarrollo usuarios y perfiles propios

En el entorno de desarrollo, lo más habitual es reproducir la configuración del ambiente de producción. Para ello, se hace necesario obtener los usuarios, perfiles funcionales y de datos asociados a los mismos. Este proceso se realiza exportando desde producción los datos e importandolo en desarrollo.

El primer paso consiste en desactivar el modo perfiles propios momentáneamente, permitiendo exportar los mismos. Basta con cambiar el

parámetro usar_perfiles_propios

de 1 a 0. Luego se debe exportar los datos de perfiles funcionales, perfiles de datos y usuarios hacia el sistema de archivos (como metadatos SQL):

#!sh
usuario@host:~$ cd /<ruta_produccion>
usuario@host:~$ #desactivar usar_perfiles_propios
usuario@host:~$ nano instalacion/i__produccion/instancia.ini
usuario@host:~$ export TOBA_INSTALACION_DIR='/<ruta_produccion>/instalacion'
usuario@host:~$ # nos aseguramos que sea ejecutable...
usuario@host:~$ chmod +x toba/bin/toba
usuario@host:~$ toba/bin/toba proyecto exportar -pdiaguita -iproduccion
usuario@host:~$ toba/bin/toba instancia exportar_local -iproduccion
usuario@host:~$ #activar usar_perfiles_propios
usuario@host:~$ nano instalacion/i__produccion/instancia.ini

El siguiente paso consiste en importar en el entorno de desarrollo los datos previamente exportados, copiando el contenido del directorio global y p!__diaguita desde producción hacia desarrollo para luego regenerar el proyecto y la instancia:

#!sh
usuario@host:~$ cd /<ruta_toba_desarrollo>
usuario@host:~$ export TOBA_INSTALACION_DIR='/<ruta_toba_desarrollo>/instalacion'
usuario@host:~$ # copiar perfiles funcionales
usuario@host:~$ cp /<ruta_produccion>/aplicacion/metadatos/permisos/* /<ruta_toba_desarrollo>/proyectos/diaguita/metadatos/permisos/
usuario@host:~$ # regenerar desarrollo para cargar perfiles funcionales
usuario@host:~$ toba/bin/toba proyecto regenerar -pdiaguita -idesarrollo
usuario@host:~$ # copiar usuarios y perfiles de datos
usuario@host:~$ cp /<ruta_produccion>/instalacion/i__produccion/global/usuarios.sql /<ruta_toba_desarrollo>/instalacion/i__desarrollo/global/
usuario@host:~$ cp /<ruta_produccion>/instalacion/i__produccion/p__diaguita/usuarios.sql /<ruta_toba_desarrollo>/instalacion/i__desarrollo/p__diaguita/ -R
usuario@host:~$ # regenerar desarrollo para cargar usuarios
usuario@host:~$ toba/bin/toba instancia regenerar -idesarrollo

Al rengerar la instancia, preguntará si se desea conservar datos locales como usuarios y logs a lo que es necesario responder NO. Es importante destacar que gracias a este procedimiento es posible versionar los perfiles funcionales propios con los que cuenta la institución (correspondiente a los cambios en directorio metadatos/permisos).

Entorno de desarrollo con base distinta a la de producción

Cuando se realice una instalación de un entorno de desarrollo y sin utilizar una copia de la base de negocios, se pueden dar dos casos:

1. si en el entorno de producción no existe el usuario "toba", al momento de cargar los datos en el entorno de desarrollo puede producirse el siguiente error:

 ERROR ejecutando SQL:
  [CODIGO]: 7
  [SQLSTATE]: db_23503
  [MENSAJE]: ERROR:  inserción o actualización en la tabla 'apex_usuario_proyecto' viola la llave foránea 'apex_usu_proy_fk_usuario'
 DETALLE:  La llave (usuario)=(toba) no está presente en la tabla 'apex_usuario'.
  [SQL EJECUTADA]: COMMIT TRANSACTION;

Para solucionarlo, en vez de reemplazar el archivo

/<ruta_toba_desarrollo>/instalacion/i__desarrollo/global/usuarios.sql

, editarlo para unir ambos contenidos, de modo que el usuario toba permanezca en la instancia.

2. En el login o ingreso al sistema en modo desarrollo se indica que el usuario El usuario "xyz" no existe o se encuentra inhabilitado, por favor contactese con el administrador. . Esto se debe a que dicho usuario no existe en las tablas internas de la base de SIU-Diaguita (scp_usuarios, scp_usuarios_areas y scp_usuarios_grupos). Se deberán traer dichos datos desde la base de producción para corregir dichos usuarios.

---

Inicializar personalización

Para iniciar la personalización, es necesario que únicamente la persona que cumpla el rol de concentrador ejecute los siguientes comandos. El concentrador debe definir el esquema de PostgreSQL temporal a ser usado por el proceso de cálculo de diferencias en la personalización, en el archivo

/<ruta_toba_desarrollo>/proyectos/diaguita/personalizacion/personalizacion.ini

:

#!sh
iniciada = "no"
schema_personalizado = "<schema_personalizado>"

Y por último, inicializar propiamente la personalización. Es obligatorio que este cambio se suba al repositorio para mantener la configuración del ambiente de desarrollo. Para finalizar, el concentrador realiza el commit de los cambios realizados.

#!sh
usuario@host:~$ bin/toba personalizacion iniciar -pdiaguita -idesarrollo
usuario@host:~$ svn commit proyectos/diaguita

A partir de este momento, todas las personas que participen del equipo de desarrollo pueden seguir los pasos de la sección [#Prepararelentornodetrabajo Preparar el entorno de trabajo]. Estas personas podrán ejecutar todas las tareas relacionadas con el proyecto, excepto aquellas que se indican explícitamente a ser ejecutadas por el concentrador.

Nota: reemplazar <sigla_institucion> con la sigla del nodo COLAB que corresponda; <ruta_toba_desarrollo> con la ruta al directorio donde se encuentra instalado el entorno de desarrollo SIU-Toba; <ruta_produccion> con la ruta al directorio donde se encuentra instalado la versión produccion de SIU-Diaguita; <usuario>, <clave> y <nombre_db_negocio> con los datos de acceso al servidor PostgreSQL para la base de datos local e individual de desarrollo; <schema_personalizado> con un nombre de esquema que no exista en la db donde se encuentre instalado el entorno de desarrollo SIU-Toba.

---

Realizar la personalización

La siguiente guía es un ejemplo [./Personalizar paso a paso] para desarrollar una personalización de SIU-Diaguita, mediante el uso del toba-editor para la extensión y modificación de las funciones y características del mismo. Esto puede ser desarrollado de forma individual o en forma colaborativa con un equipo de desarrollo.

Nota: tener en cuenta que a partir de este momento, las tareas y pasos a realizar consisten en todas aquellas que se producen cuando se desarrolla normalmente un sistema con SIU-Toba (uso del toba-editor, exportar, actualizar, regenerar, commitear, etc). Bienvenido al team diaguita-devs ;)

---

Finalizar personalización

Una vez haya finalizado el desarrollo de la personalización, y habiendo subido previamente al repositorio COLAB todos los cambios realizados (incluyendo todos los archivos PHP y metadatos producidos y/o modificados), el concentrador debe exportar la personalización, agregar al control de versión los cambios y realizar el commit para finalizar el proceso:

#!sh
usuario@host:~$ bin/toba personalizacion exportar -pdiaguita -idesarrollo
usuario@host:~$ svn add proyectos/diaguita/personalizacion --force
usuario@host:~$ svn commit proyectos/diaguita/personalizacion

El último paso del proceso para finalizar la personalización consiste en publicar la nueva versión en el repositorio COLAB, para que a partir de ese momento pueda ser instalada en producción:

#!sh
usuario@host:~$ svn cp https://colab.siu.edu.ar/svn/diaguita/nodos/<sigla_institucion>/trunk/2.1.0 https://colab.siu.edu.ar/svn/diaguita/nodos/<sigla_institucion>/versiones/2.1.0.0

Es a partir de este momento en que se puede proceder a instalar y/o actualizar el entorno de producción que será la aplicación SIU-Diaguita junto con los ajustes realizados hasta el momento.

---

Distribuir e instalar personalización

Este instructivo considera la pre-existencia de una base de negocios de SIU-Diaguita (al momento de redactar, versión 2.1.x) generada mediante el instalador web. En futuras versiones de SIU-Diaguita estará disponible la capacidad de crear e inicializar correctamente una base de negocios vacía totalmente operativa para las instituciones que deseen realizar la personalización partiendo desde una nueva implementación.

Instalar manualmente desde cero

Está destinado para el caso en que se realice una instalación, ya sea que se trata de la primera vez se instala SIU-Diaguita, de la primera vez que pasa a producción una personalización o por cambio de versión mayor de SIU-Toba (esto tener en cuenta según los requerimientos).

Los pasos a realizar consisten en la descarga del proyecto sobre una instancia nueva de producción de SIU-Toba, cargarlo y compilarlo:

#!sh
usuario@host:~$ cd /<ruta_toba_produccion>
usuario@host:~$ svn checkout https://colab.siu.edu.ar/svn/diaguita/nodos/<sigla_institucion>/versiones/2.1.0.0 proyectos/diaguita
usuario@host:~$ bin/toba proyecto cargar -pdiaguita -iproduccion
usuario@host:~$ bin/toba proyecto compilar -pdiaguita -iproduccion

Nota: si se tiene una instalación de SIU-Diaguita realizada mediante el instalador web, se debe ignorar dicha instalación conservando solamente la base de negocios e instalar una instancia SIU-Toba en modo producción.

Los cambios a la estructura de la base de negocios, como ser adición de tablas/campos, se deben realizar de forma manual. En primer lugar se deben aplicar, si existen, los cambios SQL de la versión nueva (ej. para la versión 2.1.0.0):

#!sh
usuario@host:~$ psql <nombre-db-diaguita> < proyectos/diaguita/sql/repositorio_conversion/2.1.0.sql
usuario@host:~$ #opcional, si tienen cambios SQL propios de la personalización, aplicarlos ahora
usuario@host:~$ psql <nombre-db-diaguita> < proyectos/diaguita/personalizacion/sql/repositorio_conversion/2.1.0.0.sql

Cualquier conflicto que surga en los SQL deberá ser resuelto manualmente. Se debe finalizar la actualización de la base de negocios actualizando el esquema de auditoría para que también contenga las nuevas columnas/tablas y/o sus cambios.

#!sh
usuario@host:~$ bin/toba proyecto crear_auditoria -pdiaguita -iproduccion

Actualizar manualmente versión existente

Está destinado para el caso en que ya se cuente con una instalación de la personalización existente en producción y se desee actualizarla a una nueva versión sin migrar la estructura de SIU-Toba. Los pasos a realizar consisten en apuntar a la nueva versión del proyecto, cargarlo y compilarlo:

#!sh
usuario@host:~$ cd /<ruta_toba_produccion>
usuario@host:~$ svn switch https://colab.siu.edu.ar/svn/diaguita/nodos/<sigla_institucion>/versiones/2.1.0.1 proyectos/diaguita
usuario@host:~$ bin/toba instancia regenerar -pdiaguita -iproduccion
usuario@host:~$ bin/toba proyecto compilar -pdiaguita -iproduccion

Los cambios a la estructura de la base de negocios, como ser adición de tablas/campos, se deben realizar de forma manual. En primer lugar se deben aplicar, si existen, los cambios SQL de la versión nueva (ej. para la versión 2.1.0.1):

#!sh
usuario@host:~$ psql <nombre-db-diaguita> < proyectos/diaguita/sql/repositorio_conversion/2.1.0.sql
usuario@host:~$ #opcional, si tienen cambios SQL propios de la personalización, aplicarlos ahora
usuario@host:~$ psql <nombre-db-diaguita> < proyectos/diaguita/personalizacion/sql/repositorio_conversion/2.1.0.1.sql

Cualquier conflicto que surga en los SQL deberá ser resuelto manualmente. Se debe finalizar la actualización de la base de negocios actualizando el esquema de auditoría para que también contenga las nuevas columnas/tablas y/o sus cambios.

#!sh
usuario@host:~$ bin/toba proyecto crear_auditoria -pdiaguita -iproduccion

---

Actualizar la personalización a nueva versión

Cada vez que para el SIU-Diaguita este disponible una nueva versión (versión original generada por el equipo de SIU), se deberá migrar manualmente desde un entorno de desarrollo previo. El procedimiento de trabajo implica migrar la personalización desde la versión anterior a la siguiente sin saltearse ninguna versión intermedia. Para ello, desde el repositorio COLAB se tendrá que descargar la nueva versión y realizar la instalación nueva de un entorno SIU-Toba en modo desarrollo. Es recomendable no utlizar el entorno de desarrollo anterior, así este puede ser utilizado para realizar bugfixes y correcciones que sean necesarios para la actual versión en producción. Procediendo sobre una nueva instalación de SIU-Toba, realizar:

#!sh
usuario@host:~$ cd /<ruta_toba_desarrollo>
usuario@host:~$ svn checkout https://colab.siu.edu.ar/svn/diaguita/nodos/<sigla_institucion>/versiones/2.1.1 proyectos/diaguita
usuario@host:~$ svn merge https://colab.siu.edu.ar/svn/diaguita/nodos/<sigla_institucion>/versiones/2.1.0/personalizacion proyectos/diaguita/personalizacion
usuario@host:~$ bin/toba proyecto cargar -pdiaguita -idesarrollo

Una vez cargado el proyecto se procederá a iniciar la personalización, corregir los conflictos si se sucedieran, importar la personalización previa existente, exportar los metadatos y luego subir los cambios producidos por dichos comandos, al repositorio.

#!sh
usuario@host:~$ bin/toba personalizacion iniciar -pdiaguita -idesarrollo
usuario@host:~$ bin/toba personalizacion conflictos -pdiaguita -idesarrollo
usuario@host:~$ bin/toba personalizacion importar -pdiaguita -idesarrollo
usuario@host:~$ bin/toba proyecto exportar -pdiaguita -idesarrollo
usuario@host:~$ svn commit proyectos/diaguita

Los cambios a la estructura de la base de negocios, como ser adición de tablas/campos, se deben realizar de forma manual. En primer lugar se deben aplicar, si existen, los cambios SQL de la versión nueva (ej. para la versión 2.1.1):

#!sh
usuario@host:~$ psql <nombre-db-diaguita> < proyectos/diaguita/sql/repositorio_conversion/2.1.1.sql

Cualquier conflicto que surga en los SQL deberá ser resuelto manualmente. Se debe finalizar la actualización de la base de negocios actualizando el esquema de auditoría para que también contenga las nuevas columnas/tablas y/o sus cambios.

#!sh
usuario@host:~$ bin/toba proyecto crear_auditoria -pdiaguita -iproduccion

A partir de este punto, es posible continuar con el desarrollo de la personalización ya en una nueva versión de SIU-Diaguita. Si existen otros desarrolladores en el equipo, estos deberán seguir los pasos indicados en la sección [#Prepararelentornodetrabajo Preparar el entorno de trabajo] para desarrollar con la nueva versión.