- Introducción
- Estructura de carpetas
- Requerimientos
- Creación de la base de datos local
- Configuración de la aplicación
- Configuración de CAS
- Instalación y prueba
- Creación de indicadores
- Agregar "detalle" a un indicador
- Crear filtros para consultas de "detalle"
- Configurar la actualización automática
- Ayuda al usuario final
- Personalización y consideraciones finales
e-status es una aplicación java web que actúa como panel de visualización de información. Funciona con dos accesos a bases de datos, una siendo la base local de e-status (donde guardará usuarios y configuraciones) y otra siendo la base "remota" en donde se encuentra la información a consultar.
La aplicación consume datos de la base remota en base a "indicadores" que el encargado de administrar la aplicación deberá definir. Básicamente cada indicador tiene un nombre y una consulta SQL que se ejecutará contra la base remota. En este manual se detallará la instalación de la aplicación y la creación de indicadores.
e-status está licenciado bajo la GPLv3 (e-status/LICENSE.txt).
e-status ├── extra (scripts de instalación, configuración y este archivo de ayuda) ├── lib (librerías externas) ├── nbproject (carpeta de proyecto de Netbeans) ├── src (código fuente java) │ ├── conf │ └── java │ └── uy │ └── edu │ └── ceip │ └── estatus │ ├── db │ ├── filters │ └── servlets └── web (jsp, javascript, estilos y otros recursos estáticos) ├── META-INF ├── static │ ├── css │ ├── font │ ├── highcharts_4.0.1 │ ├── img │ ├── jquery │ ├── js │ └── spin └── WEB-INF ├── jsp │ └── errors └── jspf
| Requerimiento | Solución utilizada | Observaciones |
|---|---|---|
| Java | OpenJDK 7 | No requiere OpenJDK pero la versión de Java debe ser 7 o superior. |
| Servlet container | Tomcat 7 | No se ha probado con otras soluciones pero no tiene dependencias de Tomcat. |
| Base de datos | PostgreSQL 9.3+ | No se ha probado con otro motor de base de datos pero no usa funcionalidades exclusivas de PostgreSQL. En caso usar otro motor se deberá cambiar, como mínimo, el JDBC y el script de creación de la base de datos. |
| Single Sign-on | CAS 4.0.0+ | e-status no realiza autenticación de usuarios por su cuenta, pero puede adaptarse para ello. En su defecto, CAS 4.0.0 o superior es necesario. |
| Entorno de desarrollo | Netbeans 8 | La aplicación se entrega como un proyecto de Netbeans pero debería poder importarse en cualquier IDE. |
| Planificador de tareas + aplicación que realice peticiones HTTP | cron + curl | Cualquier planificador de tareas en conjunto con una aplicación capaz de realizar peticiones HTTP es suficiente. |
En caso de no utilizar PostgreSQL es posible que el script de instalación requiera alguna modificación.
- Ejectuar el archivo de creación de usuarios e-status/extra/users.sql. Los usuarios son creados sin contraseña, esta tarea deberá ser realizada manualmente por el administrador.
- Crear la base de datos. Se debe tener en cuenta el nombre de la misma para el apartado Configuración de la aplicación.
- Conectado a la nueva base, ejectuar el archivo de creación del esquema e-status/extra/create_schema.sql.
- Insertar los parámetros necesarios ejecutando el archivo e-status/extra/insert_parameters.sql. Más adelante se le asignarán valores a cada uno.
- Ejectuar el archivo de creación de roles e-status/extra/insert_roles.sql.
e-status mantiene toda su configuración en la tabla parameters en su base de datos local, excepto por un conjunto mínimo de propiedades que necesita antes de poder conectarse a dicha base. Estas propiedades se encuentran en el archivo e-status/src/java/estatus.properties.
- db_host: IP o hostname del servidor de base de datos.
- db_name: nombre de la base de datos local (creada en el paso 2 del apartado Creación de la base de datos local).
- db_port: puerto en cual escucha el servidor de base de datos.
- estatus_user: nombre del usuario estatus (el script de instalación lo crea con nombre "estatus", pero puede ser otro). Este es el usuario que la aplicación utiliza cuando necesita actualizar datos de forma automática.
- estatus_password: contraseña del usuario anterior.
- normal_user: usuario normal (el script de instalación lo crea con nombre "estatus_user", pero puede ser otro). Todos los usuarios con permisos normales se conectarán a la base de datos usando este usuario.
- normal_user_password: contraseña del usuario anterior.
- admin_user: usuario administrador (el script de instalación lo crea con nombre "estatus_admin", pero puede ser otro). Todos los usuarios con permisos de administración se conectarán a la base de datos usando este usuario.
- admin_user_password: contraseña del usuario anterior.
- revision: versión de la aplicación.
Ahora procederemos a darle valores a los parámetros en la base de datos (tabla parameters):
- host: IP o hostname del servidor de base de datos remoto que actuará como fuente de datos.
- port: puerto en cual escucha el servidor de base de datos.
- user: nombre del usuario utilizado para extraer información de la base de datos remota.
- password: contraseña del usuario anterior.
- name: nombre de la base de datos remota.
- ajax_period: período de tiempo (en milisegundos) cada cual la página principal deberá actualizarse automáticamente.
- news_content: e-status puede mostrar una "noticia" a los usuarios luego de loguearse. El contenido (en HTML) se ingresa en este parámetro y funciona en conjunto con la columna must_see_news de la tabla local_user.
En el archivo e-status/web/WEB-INF/web.xml ubicar la siguiente sección:
<filter> <filter-name>CAS Authentication Filter</filter-name> <filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class> <init-param> <param-name>casServerLoginUrl</param-name> <param-value>https://localhost:8443/cas/login</param-value> </init-param> <init-param> <param-name>service</param-name> <param-value>https://localhost:8443/estatus/</param-value> </init-param> </filter> <filter> <filter-name>CAS Validation Filter</filter-name> <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class> <init-param> <param-name>casServerUrlPrefix</param-name> <param-value>https://localhost:8443/cas/p3</param-value> </init-param> <init-param> <param-name>serverName</param-name> <param-value>https://localhost:8443</param-value> </init-param> </filter> <filter> <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name> <filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class> </filter> <filter> <filter-name>CAS Assertion Thread Local Filter</filter-name> <filter-class>org.jasig.cas.client.util.AssertionThreadLocalFilter</filter-class> </filter>
Hay 4 parámetros que incluyen valores por defecto asumiendo una instalación de CAS y e-status en el mismo servidor, y siendo los context path de cada uno /cas y /estatus respectivamente. Se deberán modificar estos parámetros según las características de la infraestructura local:
-
CAS Authentication Filter
- casServerLoginUrl: URL del servicio de autenticación de CAS (mantener la ruta /login).
- service: URL de la aplicación e-status.
-
CAS Validation Filter
- casServerUrlPrefix: URL del servicio de validación de CAS (mantener la ruta /p3).
- serverName: URL del servidor donde está instalado e-status (sin context path).
Si el servidor de CAS tiene un certificado "self-signed" se deberá importar el mismo a la TrustStore del servidor en donde e-status está instalado. Por ejemplos de este requerimiento u otros problemas con la configuración de CAS referirse a los siguientes documentos:
- https://wiki.jasig.org/display/CASUM/SSL+Troubleshooting+and+Reference+Guide
- https://wiki.jasig.org/display/CASC/Configuring+the+Jasig+CAS+Client+for+Java+in+the+web.xml
Luego es necesario indicarle al servlet de e-status Exit la URL del servicio de cierre de sesión de CAS. Ubicar la siguiente sección:
<servlet> <servlet-name>Exit</servlet-name> <servlet-class>uy.edu.ceip.estatus.servlets.Exit</servlet-class> <init-param> <param-name>casServerLogoutUrl</param-name> <param-value>https://localhost:8443/cas/logout</param-value> </init-param> </servlet>
En ella, reeplazar la URL del servicio de autenticación de CAS (mantener la ruta /logout).
Por último, migrar los usuarios necesarios a la tabla local_user con el rol deseado.
Construir el war usando el método preferido. En caso de no usar Ant probablemente sea necesario indicar las dependencias del proyecto: las mismas se encuentran en la carpeta e-status/lib.
Hacer el deploy en el servlet container e ingresar. Debería verse un imagen de fondo (puede reemplazarse por otra en e-status/web/static/img/background1.jpg) y un footer.
Los indicadores son las únidades básicas de información de e-status. Se muestran al usuario como rectángulos en la pantalla principal con un número dentro, resultado de una consulta SQL.
Los indicadores se componen por una consulta SQL que como resultado debe devolver una fila con una columna de tipo numérico (la consulta principal), un nombre, una segunda consulta SQL (opcional) que actúa como desagregación de la consulta principal, y varios parámetros de configuración. Técnicamente, un indicador no es más que un registro en la tabla indicator. A continuación se detallan todas las columnas de dicha tabla:
- name: nombre del indicador
- query: consulta principal. Debe devolver una fila con una columna de tipo numérico.
- active: variable de actividad del indicador. Si está en falso, el indicador no actualizará sus datos ni se mostrará a los usuarios.
- val_is_integer: indica si el valor devuelto por la consulta principal es un número entero. El formato con que se muestre el número en pantalla dependerá de este valor.
- val_is_percentage: indica si el valor devuelto por la consulta principal es un porcentaje. El formato con que se muestre el número en pantalla dependerá de este valor.
- update_interval: período de actualización en minutos del indicador.
- classification: los indicadores se ordenarán en pantalla según este valor en orden alfabético. Este valor también es el que determina el color de la etiqueta del indicador según los estilos definidos en e-status/web/static/css/main.css (buscar el comentario "Tag colors").
- explanation: descripción del dato que está mostrando el indicador.
- detail: consulta de detalle. Esta consulta no tiene restricciones en cuanto a filas o columnas y, aunque es una consulta totalmente independiente de la principal, su objetivo es actuar como un nivel de desagregación de la misma. Esta consulta se ejecuta contra la base remota a demanda del usuario. Si no se desea tener consulta de detalle en cierto indicador, dejar esta columna con valor NULL.
Tal como se explicó en el apartado anterior, los indicadores pueden tener una consulta adicional denominada "consulta de detalle". Esta consulta puede devolver cualquier cantidad de filas o columnas y se ejcutará a demanda del usuario contra la base remota.
La consulta de detalle se guarda en la columna detail de la tabla indicator. Si su valor es NULL, e-status entiende que el indicador no tiene detalle y no muestra al usuario el botón correspondiente.
La única restricción de la consulta de detalle es la "filters wildcard". La "filters wildcard" no es más que un comentario ubicado en el texto de la consulta el cual será reemplazado por varias cláusulas AND obtenidas de los filtros indicados por el usuario (los filtros se describen en el apartado siguiente). La "filters wildcard" debe ser el comentario --filters y debe estar ubicado luego de una cláusula WHERE. Si la consulta no tiene necesidad de una cláusula WHERE, deberá agregarse una con la "filters wildcard" de la siguiente manera: WHERE TRUE --filters.
Las consultas de detalle pueden tener filtros definidos por el administrador de la aplicación. Hay tres tablas relacionadas con los filtros:
- filter: definición del filtro. A continuación se listan las columnas.
- name: nombre del filtro.
- filter_type: identificador del tipo del filtro. Los tipos de filtros se encuentran definidos en e-status/src/java/uy/edu/ceip/estatus/FilterType.java.
- field_name: nombre de la columna en la tabla de destino (base remota) que debe filtrarse.
- filter_operator: identificador del operador. Los operadores de filtros se encuentran definidos en e-status/src/java/uy/edu/ceip/estatus/FilterOperator.java. Tener en cuenta que los operadores disponibles dependen del tipo de filtro, referirse al método buildExpression del archivo e-status/src/java/uy/edu/ceip/estatus/DetailFilter.java para ver las combinaciones válidas.
- filter_order: define el orden en que se mostrarán los filtros en la página, de menor a mayor.
- filter_option: opciones disponibles de un filtro de tipo COMBO. A continuación se listan las columnas.
- filter: referencia al filtro al cual pertenecen esta opción. El filtro debe ser de tipo COMBO.
- option_value: texto de la opción. El filtro comparará por igualdad el valor de la columna de destino con cada texto de opción.
- rel_filter_indicator: definición de qué filtros deben estar disponibles para cada indicador.
e-status depende de alguna herramienta externa para actualizar de forma automática sus indicadores.
El método consiste en realizar periódicamente una petición a una URL especial de e-status que invocará las rutinas necesarias para que todos los indicadores que lo necesiten se actualicen. La URL en particular es /actualizar. Se debe tener en cuenta que esta URL no está protegida por autenticación para facilitar la petición, pero existe un filtro en e-status que solo permite que esta URL sea accedida desde el mismo host en donde la aplicación está instalada. El filtro en cuestión es e-status/src/java/uy/edu/ceip/estatus/filters/UpdateFromLocalhost.java y si el administrador así lo quisiera puede desactivarse, pero se debe considerar que esta URL no debe ser accedida por los usuarios de la aplicación.
La automatización funciona de la siguiente manera:
- Se obtienen todos los indicadores activos de la base de datos.
- Se filtran aquellos que no necesiten actualizarse según su update_interval y la última vez que fue actualizado (e-status guarda este dato).
- Se ejecuta la consulta del indicador contra la base remota.
- Se guarda el nuevo valor junto con la fecha y hora del momento en que se actualizó.
El período utilizado para la planificación de la tarea programada debe definirse considerando el indicador con menor update_interval. Si el menor update_interval es de 10 minutos, entonces la tarea deberá programarse al menos cada 10 minutos. A continuación se muestra un ejemplo usando cron y curl, un período de 15 minutos y una instalación de e-status usando el context path /estatus.
0,15,30,45 * * * * curl -3 -k https://localhost:8443/estatus/actualizar
Aclaración: este período de actualización es diferente al parámetro ajax_period descripto en Configuración de la aplicación. Este primero define cada cuánto tiempo el servidor de e-status deberá actualizar sus indicadores contra la base remota, mientras que el segundo define cada cuánto tiempo la página principal de e-status enviará una petición ajax al servidor de e-status (es decir, no implica interacción con la base remota) para mostrar los valores actualizados de los indicadores (si hubiese alguno).
La aplicación incluye un manual de uso completo para los usuarios finales, accesible desde la propia interfaz.
Más allá de que su funcionamiento es bastante genérico y puede servir a distintos casos de uso, e-status se entrega como una aplicación hecha por y para el CEIP. Esto implica que hay varias referencias al organismo pero todas son fácilmente modificables:
- El fondo de pantalla de la página principal ubicado en e-status/web/static/img/background1.jpg.
- El fondo de pantalla de las páginas de histórico y detalle, ubicado en e-status/web/static/img/background2.jpg.
- Los links a GURI y CEIP del footer, estando el código del footer ubicado en e-status/web/WEB-INF/jspf/footer.jsp y las imágenes correspondientes en e-status/web/static/img/logo_guri.png y e-status/web/static/img/CEIP_membrete.png.
- La página "Acerca de", la cual incluye una animación y varias imágenes. La página está ubicada en e-status/web/WEB-INF/jsp/about.jsp