DIRECTOR Multiempresas - Manual de Integración 2.0 - SMB
Manual de Integración Director Server – Agent
1. Introducción
1.1 Acerca de este documento
En el presente documento se explicará cómo integrarse a Director así como las distintas maneras de hacerlo.
1.2 ¿Qué es Director?
Napse Director es una solución de Napse que permite gestionar, administrar, distribuir y monitorear de manera centralizada y eficiente nuevas versiones de productos Napse en la red de tiendas de un retailer.
Además permite monitoreo los recursos de una terminal de forma centralizada, eficiente y proactiva.
1.3 Arquitectura de Director
Napse Director está compuesto por un servidor y N agentes.
Los agentes corren en las terminales de la red del retail y son los encargados en enviar información a servidor.
A su vez, el servidor es el encargado de enviar comandos a los agentes quienes lo ejecutan: descargar, actualizar, etc.
1.4 Alcance
Napse Director tiene el siguiente alcance:
- Gestionar las soluciones STS que se permitirán actualizar
- Gestionar las versiones completas de soluciones STS
- Centralizar las versiones de soluciones STS en un servidor del retailer
- Descargar de forma remota las versiones de soluciones STS en terminales de tiendas
- Actualizar versiones de soluciones STS en terminales de tiendas
- Monitorear de forma centralizada las versiones que posee una terminal
- Monitorear de forma centralizada el detalle del sistema de una terminal
2. Manejo de versiones
2.1 Introducción
Las versiones pertenecen a cada Producto o Solución Napse. Se importan a Napse Director en un archivo comprimido. Cada producto manejará varias versiones, las cuales las terminales actualizarán sus soluciones a la versión deseada.
2.2 Empaquetado de soluciones
Las versiones a ser deployadas en Director Server deben ser archivo ZIP con la siguiente estructura de directorios:
Directorio | Usado por | Descripción |
app | Aplicación | dentro de app deben ir los binarios y archivos de configuración de la solución. |
meta-data | Agente | de uso futuro |
conf | Agente | Incluye configuración usada por el agente, por ejemplo el "ignore.txt" |
scripts | Agente | dentro de scripts se deben colocar los archivos de script de base de datos de la aplicación. En cada actualización/instalación, el agente ejecutará los scripts aún no ejecutados. Para mayor referencia dirigirse a la sección del agente. |
batch | Agente | de uso futuro |
legal/license | Director | de uso futuro |
legal/terms | Director | archivos de términos y condiciones de uso de la solución en formato texto con extensión txt. Al momento de deployar una nueva versión, el sistema Director Server mostrará el contenido de cada archivo para que el usuario lo acepte. |
docs | Aplicación | cualquier documentación que se quiera dejar disponible en las terminales. |
A continuación se muestra un ejemplo de estructura:
3. Integración de aplicación
Existen 2 forma de integrarse a Napse Director:
4. Integrando el componente agente a una solución.
4.1 Introducción
En este apartado se detallan el esquema propuesto para integrar el Agente a soluciones.
4.2 Estructura del Agente
El Agente se compone mínimamente de un paquete de binarios y un archivo de configuración advagent.properties.
La integración con la solución a manejar y monitorear se realiza a través de scripts del sistema operativo, en el caso de Windows serán .bat o .cmd, en Linux serán shell scripts por ejemplo bash scripts.
Las operaciones que realiza el agente con la solución son: inicar, detener, consultar estado de ejecución y opcionalmente consultar paramentos y estados adicionales.
Por lo tanto es necesario indicar en el archivo de configuración éstos scripts, además de los parámetros requeridos por la solución y los requeridos por el agente.
4.3 Operaciones que realiza el Agente
Las operaciones que realiza el agente son:
- Requerir status de la solución a comandar e informar a Director Server
- Descargar actualizaciones de la solución
- Efectuar la instalación de las actualizaciones
- Ejecutar los scripts de BBDD y actualizar su estado de ejecución en la misma.
- Monitoreo de indicadores de sistema operativo (memoria, disco)
- Recolectar información adicional y enviarlo al server.
- Requerir estado e Informar
Periódicamente el agente hace un envió de status a Director Server con datos de status recolectados de la solución, estado de actualización e instalación. En cuanto a informar el estado de ejecución de la solución, el agente ejecuta un script que se especifica en el parámetro de configuración application.command.status y el resultado del mismo se suma al mensaje del status, descripto en ésta sección
- Descargar actualizaciones
Cuando el agente recibe el comando update se conecta al repositorio especificado en el comando, y realiza la descarga de actualizaciones.
- Instalación de actualizaciones
Cuando el agente recibe el comando install, procede a realizar varias tareas:
- Detener la solución
- Backup de archivos de la version de solución que está instalada
- Backup de base de datos de la solución.
- Instalación de los nuevos archivos descargados del repositorio
- Ejecución de scrips de base de datos
- Iniciar la solución
A continuación de detallan estas tareas:
- Detener Solución
El agente ejecuta el shell script indicado en el parámetro application.command.stop
- Backup de archivos
Se copian los archivos de la solución indicados en application.base.path en el directorio de resguardo indicado en el parámetro application.backup.path, vaciando previamente su contenido.
- Backup de base de datos
Se efectúa un backup en la base de datos cuyos parámetros de conexión se indican en los parámetros sql.*
El backup de BD se puede obviar si en el comando de install se especifica backupdb=false.
En el caso de MS Sql Server, el backup es realizado a través de script con el comando sql "backup database ..." soportado en las versiones de Sql Server retail y express.
En el caso de BD Oracle, el backup se realiza con la herramienta de Oracle "rman", la cual sólo puede ser ejecutada en la misma máquina dónde está ejecutándose el motor de la BBDD, esta es una característica de esta BD en particular, por lo tanto requiere que el agente esté instalado y ejecutándose en la misma máquina que el motor BD para realizar el backup.
- Instalación de los nuevos archivos
Se copian los archivos descargados del repositorio, los correspondientes a la solución, en el directorio especificado en
application.base.path
Todos los archivos serán copiados respetando la estructura de directorios contenida en el paquete de actualización descargado de director (git) salvo los definidos en los archivos "ignore.txt" situados en:
- Directorio raíz del agente
- Tiene la intención de ser usado siempre con el fin de ignorar archivos que normalmente poseen una configuración particular por terminal/instalación y qué si son pisados, la aplicación deja de funcionar
- Directorio "conf" del paquete de actualización
- tiene la intención de ser usado eventualmente en una versión en particular
- Se ignorarán los archivos/directorios que se encuentren listados en el archivo "ignore.txt".
- Se admite "*" como comodín múltiple ó
- '?' como comodín simple.
Por ejemplo:
config*
run.bat
ejemplo.*
En este caso se ignorarán los archivos/directorios que comiencen con "config", los archivos "run.bat" y los archivos/directorios que se llamen "ejemplo" y posean cualquier extensión.
- Ejecución de scripts de base de datos
Los motores actualmente soportados con los siguientes:
- Microsoft SQL Server
- Oracle
- Hyper Sonic
En caso que existan scripts de base de datos, se sigue el siguiente proceso descripto en la siguiente ilustración:
Ilustración 1 - Proceso de ejecución de scripts
- En base a la propiedad script.subFolder del archivo de configuración; que indica a partir de que carpeta dentro de scripts se deben buscar los archivos (no recursivamente), se escanean los archivos que cumplen con el patrón *.sql.
2. Se retornan todos los identificadores de changeSetIDs encontrados en el archivo. Un ChangeSetID es un identificador único que representa un conjunto de script o cambios que posee una versión determinada, por ejemplo:
– Changeset src/db.changelog.create.xml::script-20160616-74::autor
Siendo:
- el nombre del archivo: db.changelog.create.xml
- el changeSetID: script-20160616-74
- el nombre del autor: autor
La/s línea/s siguiente/s hasta el final del archivo o hasta el próximo identificador de changeLog, compone/n el script SQL a ejecutar. En caso de encontrar duplicados, lo indica y detiene el proceso.
IP de la terminal donde se encuentra el Agente
3. Debe existir en la base de datos la tabla STS_DB_CHANGE_LOG descripta al final de este documento en la sección: DDL Tabla para actualización de scripts. Esta tabla contiene entradas por changeLogID que indican su status (0=OK, 1=ERROR) de ejecución, de este modo, se evita volver a ejecutar un script que ya fue ejecutado previamente, también, el propósito de esta tabla es tener una bitácora que indica el timestamp en que sucede la ejecución, el status, el orden de ejecución, el nombre del archivo del que provino el changeSetID, el resultado de la ejecución, etc.
4. En este paso se buscan los ya procesados descriptos en el punto anterior.
- Se conforman colecciones que indican de cada archivo, que changeSetID es candidato a ejecutar y su script.
- Se retorna el contenido del paso anterior.
- Por cada archivo, se toma cada changeSetID, se impacta en STS_DB_CHANGE_LOG que se está por ejecutar, se ejecuta el script, en caso de error toma ese retorno y termina el proceso de actualización, también refleja el error en STS_DB_CHANGE_LOG. En caso de no haber errores, por cada script se impacta la correcta ejecución también en STS_DB_CHANGE_LOG.
Notas:
- Para Microsoft SQL Server se usa como fin de comando la sentencia GO
- Para Oracle se usa como fin de comando el carácter ";" o bien el formato de Stored Procedure
- Para Hyper Sonic se usa como fin de comando el carácter ";"
- Todos los comandos SQL dentro de un ChangetSet se ejecutan dentro de una transacción SQL. Si una sentencia falla se hará Rollback. Se debe notar que las capacidades de Rollback serán dadas por el motor de base de datos utizado. Por ejemplo, no en todos los motores de BBDD funciona un rollback de un comando ALTER TABLE.
Se adjuntan ejemplos tanto para MSSQLServer, Oracle y Hyper Sonic:
- Iniciar la solución
El agente ejecuta el shell script indicado en el parámetro application.command.start
4.4 Estructura orientativa del Agente aplicado a una Solución
Como se mencionó anteriormente, el Agente se compone de binarios y configuración.
La solución que manejará el agente requerirá su propia estructura de directorios para sus binarios y configuración.
Adicionalmente, el agente utilizará directorios adicionales como por ejemplo para descargar las actualizaciones desde el repositorio y realizar backup de archivos
La estructura de directorios podría ser:
sdSolucion
│
├───sdAgent
│ ├───lib
│ └───logs
├───sdAgentCmds
├───bkp
├───localRepo
└───Solucion
├───app
├───batch
├───docs
├───legal
├───meta-data
└───scripts
- En el directorio sdAgent contendrá el archivo de configuración advAgent.properties y algunos archivos adicionales, como ser un batch script para iniciar el agente, un directorio lib donde residirán los binarios de agente, un directorio logs donde el agente dejará registro de la actividad.
- El directorio sdAgentCmds contendrá los shell scripts para iniciar/detener/consultar la solución.
- El directorio bkp es dónde se hará el backpup de los archivos de la solución durante la tarea de instalación.
- El directorio localrepo es dónde se descargarán las actualizaciones del repositorio remoto.
- El directorio Solucion corresponde a la estructura de archivos de la solución, que durante la instalación se genera a partir de lo descargado en localrepo
- Dentro del directorio Solucion, en app estará todo requerido por la solución para su funcionamiento. Los otros directorios batch, docs, legal, scripts, el de scripts es dónde la solución dejará los scripts de BD que el agente ejecutará durante una instalación
4.5 Configuración del Agente
Se realiza en el archivo advAgent.properties
Campo | Descripción |
company.id | Id de la compañía, configurada en Director Server. |
store.id | Id de la tienda, configurada en Director Server. |
terminal.id | Id de la terminal, configurada en Director Server. |
device.type | Categoría o tipo de la terminal, configurada en Director Server. |
advserver.url | Direccion URL base (de la forma https//ip:port/) del Director Server |
advserver.status.path | Path relativo al URL base de Director Server, donde el Agente informa status |
advserver.polling.seconds | Período en segundos en que el Agente informa estatus al Director Server |
product.code | Código del Producto STS, configurado en Director Server. |
product.description | Descripción del Producto STS, configurado en Director Server. |
product.version | Versión del Producto STS, configurado en Director Server. |
repository.local.path | Directorio local donde almacenar las actualizaciones descargadas del repositorio |
application.base.path | Directorio de la Solución STS |
application.backup.path | Directorio para resguasdar la Solución previo una acatualización |
application.command.start | Shell script con los comandos necesarios para iniciar la Solución |
application.command.status | Shell script con los comandos para solicitar estado a la Solución |
application.command.stop | Shell script con los comandos para detener la Solución |
application.status.running.text | Texto a buscar por Agente en el comand.status para tomar como app en ejecución |
application.extended.info.command | Shell script para que las aplicaciones informen datos adicionales |
application.extended.info.resultfile | Archivo de texto con informacion adicional a informar en el envió de status |
cancel.install.if.app.running | Flag que con valor 'true' cancela la instalación si la Solución está en ejecución |
application.start.on.agent.start | Flag que con valor 'true' indica iniciar la Solucíon al inicar el Agente |
application.start.after.install | Flag que con valor 'true' indica iniciar la Solucíon luego de instalaciónapplication.start.after.install |
sql.server | Direccion ip del servidor de BD Sql |
sql.port | Port del servidor de BD Sql |
sql.db | Nombre de la BD Sql |
sql.user | Usuario de la BD |
sql.pass | Contraseña de la BD (Base 64 del TDES generado con herramienta CipherUtil ) |
sql.bkp.dir | Directorio del backup de la BD (directorio local del server donde reside la BD) |
sql.db.type | Tipo de servidor Sql: 'oracle' o 'mssql' |
sql.oracle.bin.dir | Directorio de binarios de la instalacíon BD Oracle, donde reside la herramienta 'rman' |
sql.oracle.temp.dir | Directorio temporal requerido para la ejecución de la herramienta 'rman' |
scripts.subFolder | Es el path relativo a la carpeta scripts en donde van a estar los scripts a ejecutar. |
Backup BD
Verificar que el directorio creado para los Backus de la BD tenga permisos de escritura
- Repositorio
Los valores repository.remote.url, repository.user, repository.pass serán provistos por Director Server en el mensaje de update. En caso que Director Server no lo envíe, se utilizarán los configurados.
- Contraseñas
Para los valores de contraseña, se provee de una herramienta 'CipherUtil' para encriptar las mismas y codificar dicho encriptado en Base 64, de forma que pueda copiarse sin problemas de caracteres de control.
El CipherUtil es un archivo .jar y se ejecuta desde linea de comando:
java -cp cipherUtil.jar com.synthesis.advagent.CipherUtil
Solicita el ingreso del valor a encriptar y genera por pantalla el valor a copiar en la configuración, adicionalmente guarda el valor en un archivo cuyo nombre indica por pantalla.
- Información adicional
El valor application.extended.info.command indica un shell script, para que la Solución pueda suministrar información adicional para que el agente envíe al Director Server en el envío de status. Los datos que genere dicho script deberá guardarlo en un archivo (indicado en application.extended.info) para que el Agente lo tome.
El formato de este archivo deberá 'categoria.nombre=valor'. El Director Server agrupará la información en base a dicha categoría.
Ejemplo de un registro del archivo: user.language=en
- DDL Tabla para actualización de scripts.
Para tener un seguimiento de la ejecución de los scripts, se usa la siguiente tabla con la que el agente cuenta para mantener el orden y ejecución.
En Microsoft SQL Server:
CREATE TABLE STS_DB_CHANGE_LOG ( CHANGE_SET_ID VARCHAR(200) NOT NULL, PRODUCT_ID VARCHAR(100) NOT NULL, DATEEXECUTED DATETIME, FILENAME VARCHAR(200), ORDEREXECUTED INT, LOGEXECUTED TEXT, STATUS INT, CONSTRAINT STS_DB_CHANGE_LOG_CHANGE_SET_ID_PRODUCT_ID_pk PRIMARY KEY (CHANGE_SET_ID, PRODUCT_ID) )
En Oracle:
CREATE TABLE STS_DB_CHANGE_LOG ( CHANGE_SET_ID VARCHAR2(200) NOT NULL, PRODUCT_ID VARCHAR2(100) NOT NULL, DATEEXECUTED DATE, FILENAME VARCHAR2(200), ORDEREXECUTED NUMBER(10), LOGEXECUTED LONG, STATUS NUMBER(10), CONSTRAINT CHANGE_SET_ID_PRODUCT_ID_pk PRIMARY KEY (CHANGE_SET_ID, PRODUCT_ID) )
En Hyper Sonic
CREATE TABLE STS_DB_CHANGE_LOG( CHANGE_SET_ID varchar(200) NOT NULL, PRODUCT_ID varchar(100) NOT NULL, DATEEXECUTED datetime NULL, FILENAME varchar(200) NOT NULL, ORDEREXECUTED int NULL, LOGEXECUTED varchar(32768) NULL, STATUS varchar(200) NULL ); ALTER TABLE STS_DB_CHANGE_LOG ADD CONSTRAINT PK_STS_DB_CHANGE_LOGUNIQUE (CHANGE_SET_ID,PRODUCT_ID );
Las columnas de esta tabla tiene el siguiente propósito:
- CHANGE_SET_ID
- Tipo dato: VARCHAR(200)
- Uso: identificador de conjunto de cambios o CHANGE SET
- PRODUCT_ID
- Tipo dato: varchar(100)
- Uso: Identificador del producto, el mismo que está bajo la propiedad del agente "product.code"
- DATEEXECUTED
- Tipo dato: datetime
- Uso: fecha en que se ejecutó el change set
- FILENAME
- Tipo dato: VARCHAR(200)
- Uso: de que archivo se sacó el change set
- ORDEREXECUTED
- Tipo dato: Integer
- Uso: orden de ejecución. Número consecutivo, de uso principal para SAC
- LOGEXECUTED
- Tipo dato: BLOB
- Uso: resultado de ejecución del change set
- STATUS
- Tipo de dato: int
- Uso: indica si la ejecución fue o no exitosa (ERROR/OK)
4.6 Integración con Maven
El agente está publicado en Maven.
Por lo tanto se puede integrar el agente a la solución referenciando el siguiente artefacto:
<groupId>synthesis.vtol4.director</groupId> <artifactId>director-agent</artifactId> <version>VERSION</version> <classifier>dist</classifier> <type>zip</type>
Donde "VERSION" se le deberá solicitar al Product Manager de Director.
Al referenciar éste artefacto, se estará bajando del repositorio central un archivo con las siguientes características:
Nombre: director-agent-VERSION-dist.zip
Estructura:
Dentro de éste paquete, se está el archivo "advagent.properties" que tiene las siguientes propiedades a ser reemplazadas en tiempo de instalación:
#codigo identificador de compañia company.id=$(company) #codigo identificador de tienda store.id=$(store) #codigo identificador de terminal terminal.id=$(terminal) #tipo de dispositivo - uso futuro device.type=$(device) #URL (ej: http://ip:puerto) donde escucha director server advserver.url=$(url) advserver.status.path=director/agent/status #cada cuantos tiempo (en segundos) se envia un mensaje de status (minimo permitido 60) advserver.polling.seconds=360 #en caso de error al enviar status, reintenta en este porcentaje de tiempo (en porcentaje) advserver.polling.retrytime.percentage=20 #codigo de producto que gobierna este agente product.code=$(product) #descripcion del producto - solo a modo informativo product.description=$(product.description) #version del producto product.version=$(version) #directorio local donde se descargaran las actualizaciones de GIT repository.local.path=$(local.path) #directorio base de la aplicacion application.base.path=$(base.path) #directorio donde se realiza el backup application.backup.path=$(backup.path) #carpeta relativa en scripts. Sirve para manejar diferentes configuraciones para el mismo producto. scripts.subFolder=$(scripts.subFolder) #comando que inicia la aplicacion application.command.start=$(cmd.start) #comando que permite obtener el estado de la aplicacion. Este comando se ejecuta cada advserver.polling.seconds segundos application.command.status=$(cmd.status) #texto que se busca en la salida de la ejecucion del comando STATUS application.status.running.text=successful,running #comando que se ejecuta para obtener informacion extendida y enviarla al director server application.extended.info.command=$(cmd.info) #archivo de propiedades que se espera como salida de la ejecucion del comando indicado por 'application.extended.info.command' application.extended.info.resultfile=$(cmd.info.result) #comando que permite detener la aplicacion application.command.stop=$(cmd.stop) #indica si se debe cancelar la instalacion cuando la aplicacion esta corriendo cancel.install.if.app.running=$(cancelIfRunningApp) #indica si al iniciar el agente, se debe iniciar la aplicacion application.start.on.agent.start=$(appStartOnAgentStart) #indica si se debe iniciar la aplicacion luego de realizar una instalacion/actualizacion application.start.after.install=$(appStartAfterInstall)
Nota:
- las propiedades a reemplazar son las que están entre $(….)
En caso de que la aplicación utilice base de datos y sea requerido que el agente haga backup y/o realice actualización, se deberá adicionar la siguiente configuración:
#****************************************************************************************************************** # Datos de conexion a la BBDD # NOTA: La realizacion del backup es condicional a que el director-server envie el flag de backup #****************************************************************************************************************** #tipo de base de datos a utilizar. Valores soportados "mssql", "oracle" y "hsqldb". En caso de no utilizar BBDD dejar vacio sql.db.type=$(sql.db.type) #IP de BBDD. En HSQLDB dejar vacio sql.server=$(sql.server) #puerto de BBDD. En HSQLDB dejar vacio sql.port=$(sql.port) #nombre de BBDD. EN HSQLDB poner la ruta y nombre del archivo que la BBDD sql.db=$(sql.db) #nombre de la instancia de la BBDD. Dato opcional. Si está vacio no se usa sql.instance=$(sql.instance) #usuario de la BBDD sql.user=$(sql.user) #contraseña de la BBDD sql.pass=$(sql.pass) #directorio donde se realizará el backup de la BBDD. Solo se usara si el Director Server envía el flga activo de Backup (directorio local del server donde reside la BD) sql.bkp.dir=$(sql.bkp.dir) #El backup en oracle se hace a traves de una herramienta llamada "rman". Oracle no permite el backup a traves de un comando SQL, por lo que es requerido tener previamente #instalado dicha herramienta sql.oracle.bin.dir=$(sql.oracle.bin.dir) # C:\\oraclexe\\app\\oracle\\product\\11.2.0\\server\\bin sql.oracle.temp.dir=$(sql.oracle.temp.dir) # C:\\oraclexe sql.oracle.sid=$(sql.oracle.sid)
5. Comunicándose directamente con el server
5.1 Integración
La integración directa con Director Server consiste en enviar directamente los mensajes soportados por el servidor y saber interpretar los mensajes que éste último es capaz de enviar en forma de comandos.
5.1.1 Tipos de Operación
En este apartado se detallan los mensajes implementados en Napse Director.
5.1.1.1 Status
Este mensaje de estado es utilizado para que el Agente informe los detalles de la terminal y de la versión del Producto en la terminal.
Es un mensaje que va desde el Agente hacia el Server.
Sentido del mensaje
El mensaje de estado va desde el agente hacia el Director Server.
Agent → Server
Mensajería
El mensaje de estado se debe enviar a Director Server mediante el uso de un POST y bajo HTTPS a la siguiente URL:
https://IP:port/director/agent/status
En el BODY del requerimiento se debe enviar un mensaje en formato JSON con la siguiente información:
Colección | Campo | Descripción |
companyId | Id de la compañía del retail. Se carga por configuración | |
listeningPort | Puerto de la terminal donde se encuentra el Agente. Se carga por configuración | |
date | Fecha y hora de envío. Formato aaaammddHHmmssSUTC, donde S es el símbolo positivo o negativo y UTC es el huso horario en formato hhmm | |
deviceType | Categoría de la terminal. Se carga por configuración | |
terminalId | Terminal de la tienda de la compañía del retail. Se carga por configuración | |
storeId | Id de la tienda de la compañía del retail. Se carga por configuración | |
host | Nombre de la terminal donde se encuentra el Agente | |
ip | IP de la terminal donde se encuentra el Agente | |
agentVersion | Indica la versión de software del agente | |
token | Un token que luego Director Server usará para enviar los comandos hacia el agente. | |
tokenExp | Fecha y hora de expiración del token. Formato aaaammddHHmmssSUTC, donde S es el símbolo positivo o negativo y UTC es el huso horario en formato hhmm | |
product | status | Informa el estado de Agente. Ver tabla |
detail | Mensaje adicional y detallado de la tarea | |
appIsRunning | Informa si el Producto STS está en funcionamiento o está detenido. Valores posibles: true/false. El chequeo es según el Producto STS. Ejemplo, chequeo de puerto, control de proceso en ejecución, etc | |
taskUUID | Identificador de la tarea enviado por Director Server. | |
taskStatus | Informa el código del estado de la tarea. Ver tabla | |
task | Código de la tarea. Ver tabla | |
version | Versión del Producto STS. Si no se efectúo previamente una instalación se envía 0 | |
code | Código del Producto STS. Se carga por configuración | |
description | Descripción del Producto STS. Se carga por configuración | |
isAlivePort | Chequeo del puerto para POS. Se encuentra en desuso | |
lastInstall | Fecha y hora de la última instalación del Producto STS. Formato aaaammddHHmmssSUTC, donde S es el símbolo positivo o negativo y UTC es el huso horario en formato hhmm. En caso de que nunca se haya instalado una versión, se envía el formato estándar 19700101 | |
lastUpdate | Fecha y hora de la última sincronización del Producto STS. Formato aaaammddHHmmssSUTC, donde S es el símbolo positivo o negativo y UTC es el huso horario en formato hhmm. En caso de que nunca se haya sincronizado una versión, se envía el formato estándar 19700101 | |
synchronizedVersion | Informa la última versión sincronizada del Producto STS | |
free memory | Memoria libre (en Bytes) en la terminal, reportada por la JVM Oracle | |
info | measureunit | Unidad de medida que se informan los valores. Por defecto en Bytes |
free disk | Disco libre (en Bytes) en la terminal, de la unidad donde se ejecuta el agente | |
total memory | Capacidad total de memoria (en Bytes) en la terminal, reportada por la JVM Oracle | |
total disk | Capacidad total del disco (en Bytes) en la terminal, de la unidad donde se ejecuta el agente | |
java.version | Versión de Java RuntimeEnvironment | |
java.vendor | Proveedor de Java RuntimeEnvironment | |
java.arch | Tamaño de la plataforma | |
os.name | Nombre del sistema operativo | |
os.version | Versión del sistema operativo | |
os.arch | Arquitectura del sistema operativo | |
Otros valores del tipo "clave-valor" | Estos valores serán procesados por director server e incluidos como información adicional de la terminal. | |
Detalle del uso del “Status”
El “status” sirve para informar al Director Server sobre el estado del agente. Existen principalmente 2 casos en donde se debe informar dicho estado
- Periódicamente cada X cantidad de tiempo para informar el estado del agente, de la aplicación, etc. En este caso y a modo aclaratorio
- “status”, siempre enviar 00, indicando que el agente está disponible.
- “taskUUID”, en blanco porque no hay tarea
- “task”, en blanco porque no hay tarea
- “taskStatus”, en blanco porque no hay tarea
- “detail”, en blanco porque no hay tarea, o bien, una descripción que simplemente se podrá apreciar en el log de DirectorServer
- Cuando el DirectorServer solicitó realizar una acción (sincronizar o actualizar). Cada acción supone la ejecución de una serie de pasos o tareas. Entonces se espera que la ejecución de cada tarea implique enviar un mensaje al servidor para indicar el estado de ejecución de dicha a tarea. Los datos obligatorios en éste caso son:
- “status”, para indicar si está sincronización o actualizando
- “taskUUID”, para indicar el ID de la tarea. Este dato lo envió previamente el server.
- “task”, para indicar que tarea se está realizando. Ej: deteniendo app, haciendo backup, etc
- “taskStatus”, para indicar el estado de ejecución de la tarea antes idnicada.
- “detail”, para dar más detalle de la tarea. Ej: si dio error, entonces indicar una descripción del error. Si no hay error, por ejemplo info de un directorio, de una tarea, etc. En todos los caso, el mismo se mostrará en consola
Parte del mensaje de status
Error indicado por agente al instalar
Ejemplo
{ "product": { "taskUUID": "", "detail": "app not running", "appIsRunning": "false", "taskStatus": "", "status": "00", "version": "banana", "code": "demo", "description": "BridgePOS", "isAlivePort": "", "lastInstall": "19691231210000-0300", "task": "", "lastUpdate": "20170815115253-0300", "synchronizedVersion": "201706301807128-0300" }, "companyId": "CP1", "listeningPort": "8383", "token": "c90816fa-dde6-49a4-a975-5a959bde7adf", "date": "20170815181921-0300", "info": { "memory.free": "1785778176", "java.arch": "64", "bridgePOS.scanner": "NCR 1.0 ", "java.version": "1.8.0_91", "os.arch": "amd64", "user.language": "es", "user.name": "juanc", "memory.total": "8452411392", "disk.total": "501044211712", "measure.unit": "bytes", "bridgePOS.logged.user": "Demo ", "disk.free": "379280224256", "os.version": "6.3", "java.vendor": "Oracle Corporation", "file.encoding": "Cp1252", "os.name": "Windows 8.1", "user.country": "AR" }, "deviceType": "333", "terminalId": "12", "storeId": "1", "host": "NTK-JUANC", "tokenExp": "20170815201651-0300", "ip": "127.0.0.1" }
Códigos de respuesta
El server puede responder los siguientes valores:
Código | Descripción | Acción |
200 | El requerimiento fue procesado satisfactoriamente | Ninguna |
404 | La combinación compañía, tienda, terminal, producto no fue encontrada. | revisar la configuración del sistema |
500 | Error interno del sistema. | Reintentar esperando un lapso aproximado de 5 segundos. |
Acceso al código
Para no tener que implementar el mensaje de "status", se puede acceder a las clases que representan ésta estructura incluyendo la siguiente dependencia de MAVEN
<groupId>synthesis.vtol4.director</groupId> <artifactId>director-messaging</artifactId> <version>VERSION</version> <packaging>jar</packaging>
Donde "VERSION" se le deberá solicitar al Product Manager de Director.
Un vez que se tiene referencia al paquete la clase que representa la estructura es la siguiente:
com.synthesis.advagent.model.AdvAgentInfo
5.1.1.2 Update
Este mensaje se utiliza para efectuar la sincronización/descarga de una versión de software y es indicado/enviado por Director Server
Sentido del mensaje
El mensaje o comando "update" va desde Director Server al agente
Agent ← Server
Mensajería
Cuando en Director Server se haya definido la necesidad de que una terminal descargue una versión, ésta acción será notificada al agente en forma de respuesta al envío de un STATUS. En dicha respuesta, se recibirá un mensaje con el siguiente formato
Campo | Descripción |
companyId | Código de la compañía |
storeId | Código de la tienda |
terminalId | Código de la terminal |
taskUUID | Identificador de tarea (alfanumérico) que Director Server le asigno a la tarea y que luego el agente debe utilizar en los sucesivos status que informan el estado o progreso de la tarea. |
toVersion | Identificador de revisión a realizar el checkout del repositorio o id de versión a actualizar |
repoUrl | URL del repositorio. |
repoUser | Usuario del repositorio. |
repoPass | Password del usuario del repositorio. |
token | discontinuado |
command | Valor fijo "update" |
Ejemplo
{ "companyId": "CP1", "taskUUID": "192a0cf0-1bb4-4db2-9dd1-320184416aa", "token": "f1552a72-f980-4a7e-86eb-8883940ce64c", "repoPass": "nosotros", "command": "update", "repoUser": "root", "terminalId": "12", "storeId": "1", "toVersion": "201706301807128-0300", "repoUrl": "http://10.4.13.182/root/demo.git" }
Acceso al código
Para no tener que implementar el mensaje de "update", se puede acceder a las clases que representan ésta estructura incluyendo la siguiente dependencia de MAVEN
<groupId>synthesis.vtol4.director</groupId> <artifactId>director-messaging</artifactId> <version>VERSION</version> <packaging>jar</packaging>
Donde "VERSION" se le deberá solicitar al Product Manager de Director.
Un vez que se tiene referencia al paquete la clase que representa la estructura es la siguiente:
com.synthesis.advagent.model.AdvUpdateCommand
Acciones posteriores
Posterior a la recepción del comando de update, se deben enviar mensajes de status indicando el estado de ejecución de la tarea.
El mensaje de status tiene el mismo formato que un status regular pero adicionando los siguientes campos:
- taskUUID
- taskStatus
- task
5.1.1.3 Install
El mensaje/comando Install lo usa Director Server para indicarle al agente que debe instalar una versión de software.
Sentido del mensaje
El mensaje o comando "install" va desde Director Server al agente
Agent ← Server
Mensajería
Cuando en Director Server se haya definido la necesidad de que una terminal instale una versión, ésta acción será notificada al agente en forma de respuesta al envío de un STATUS. En dicha respuesta, se recibirá un mensaje con el siguiente formato
Campo | Descripción |
companyId | Código de la compañía |
storeId | Código de la tienda |
terminalId | Código de la terminal |
taskUUID | Identificador de tarea (alfanumérico) que Director Server le asigno a la tarea y que luego el agente debe utilizar en los sucesivos status que informan el estado o progreso de la tarea. |
token | discontinuado |
command | Valor fijo "install" |
dbbackup | Indica si se debe realizar backup de la base de datos |
Ejemplo
{ "companyId": "CP1", "taskUUID": "192a0cf0-1bb4-4db2-9dd1-320184416aa", "token": "f1552a72-f980-4a7e-86eb-8883940ce64c", "command": "install", "terminalId": "12", "storeId": "1", "dbbackup": "false" }
Acceso al código
Para no tener que implementar el mensaje de "install", se puede acceder a las clases que representan ésta estructura incluyendo la siguiente dependencia de MAVEN
<groupId>synthesis.vtol4.director</groupId> <artifactId>director-messaging</artifactId> <version>VERSION</version> <packaging>jar</packaging>
Donde "VERSION" se le deberá solicitar al Product Manager de Director.
Un vez que se tiene referencia al paquete la clase que representa la estructura es la siguiente:
com.synthesis.advagent.model.AdvInstallCommand
Acciones posteriores
Posterior a la recepción del comando de install, se deben enviar mensajes de status indicando el estado de ejecución de la tarea.
El mensaje de status tiene el mismo formato que un status regular pero adicionando los siguientes campos:
- taskUUID
- taskStatus
- task
6. Apartados
6.1 Código de estados
En la siguiente sección se detallan los códigos de estado que se manejan entre el Agente y Director Server, tanto para la notificación de estado periódica, como para el informe de estado de ejecución de cada comando (el progreso).
6.1.1 Códigos de Estado deL AgentE (campo "status")
Indica el estado del agente.
Código | Descripción | Detalle |
00 | agentStatusAvailable | Disponible |
01 | agentStatusUpdating | Descargando |
02 | agentStatusInstalling | Actualizando |
6.1.2 Códigos de Tarea (campo "task")
Indica que tipo de tarea se está ejecutando en el agente
Código | Descripción | Operación | Detalle |
01 | stoppingCode | Install | Finalización de la aplicación |
03 | backupFsCode | Install | Copia del sistema de archivos |
05 | backupBdCode | Install | Copia de la base de datos |
07 | installingFilesCode | Install | Instalación de archivos |
09 | runningScriptsCode | Install | Ejecución de scripts |
11 | startingAppCode | Install | Iniciación de la aplicación |
13 | updatingRepository | Update | Actualización del repositorio |
50 | skippingScriptCode | Install | Omisión de script |
51 | stopInstallAppRunningCode | Install | Cancelación de instalación por aplicación en proceso |
6.1.3 Códigos de Estado de Tarea (campo "taskStatus")
Indica el estado de la tarea en ejecución.
Código | Descripción | Detalle |
00 | statusOK | OK |
01 | statusInProgress | En curso |
98 | statusWarning | Advertencia |
99 | statusError | Error |
6.2 Descarga de versiones
6.2.1 Funcionamiento
Cuando el agente recibe el comando update se conecta al repositorio GIT especificado en el comando, y realiza la descarga de la actualización.
La descarga de la actualización no es ni más ni menos que una sincronización de GIT (usa los comandos Clone y Fetch que no tiene sentido explicar en éste apartado)
La sincronización de GIT se tiene 2 momentos
- el momento incial, cuando el cliente no tiene dato alguno, por lo que descarga todo el paquete. Si la versión del producto pesa 100MB, entonces descarga 100MB o menos ya que la transferencia se hace zipeada (dependerá del tipo de archivos, el nivel de compresión logrado). (CLONE)
- ya con todo descargado, solo sincroniza los cambios o delta.(FETCH)
El cliente GIT (que corre en el agente) hará una comparación entre la versión que se debe descargar y la versión que tiene actualmente la terminal. En base a esta comparación, realizará los deltas (diferencias) entre versiones para luego realizar la descarga de los mismos.
La comparación que realiza GIT se divide principalmente en 2 grupos:
- Archivos de texto, Binarios (ZIP, JARS, WARS).
- Binarios (videos, fotos, etc).
Cuando Git detecta algún cambio en un archivo del tipo 1, se bajará la diferencia (delta) entre el archivo nuevo y el actual en la terminal.
En el caso de los archivos del tipo 2, al realizar la comparación y detectar algún cambio, Git se descargará el archivo en cuestión en su totalidad, salvo que el cambio sea de nombre, en ese caso solo descarga pocos bytes en forma de una nueva referencia lógica.
Cuando se transfiere archivos del tipo no binarios, Git comprime los mismos, con lo cual los tamaños de transferencias se reducen significativamente.
Cuando una versión nueva es subida a Director Server, el mismo guardará en la base de datos los cambios detectados por GIT entre la versión nueva y la versión de la cual deriva dicha actualización. (Este registro se encuentra en la tabla DIR_RELEASE, en la columna Log).
6.2.2 Cálculo de tamaño de transferencia
Calcular de manera precisa el tamaño que se transfiere entre el agente y el servidor es complicado ya que se hace por delta y de manera comprimida, entonces hay varios factores que determinan el tamaño final. Además, puede ser que el agente esté en la versión 3 y se quiera ir a la 8, por lo que descargará todas las versiones intermedias.
Para calcular aproximadamente el tamaño de una transferencia, se debe buscar en el log del agente el tamaño inicial del repositorio local (carpeta TMP) y comparar con el tamaño final luego de la descarga
La línea inicial es la siguiente
[DownloadVersionThread] Local repository folder [c:\synthesis\pos\tmp]. Actual size [180511723] bytes
y la final es
[DownloadVersionThread] LocalPath [c:\synthesis\pos\tmp] size after update 210133224 bytes
En éste ejemplo se puede ver una diferencia de 28MB.
Tener en cuenta que el tamaño informado es la diferencia de las carpetas finales, ya descomprimidas, por lo que se pudo haber incluido en la versión un archivo de texto grande, pero que en realidad por la red se transfirió comprimido con un tamaño mucho más pequeño.