PROMO 7.3 - Manual de Instalación

Introducción

PROMO es una solución que permite separar el manejo de promociones del punto de venta.
Cuenta con dos grandes componentes: el "Motor de promociones", encargado de calcular las promociones participantes cuando se realiza una transacción en el punto de venta e informarlas al mismo una vez finalizado el cálculo; y la "Consola de administración", encargado de brindar una herramienta centralizada de administración.
El presente manual ilustra sobre cómo realizar la instalación de ambos componentes y las diferentes opciones que pueden ser configuradas para su funcionamiento.

Consola de Administración - PROMO

Introducción

La Consola de administración es el componente web de administración y creación de promociones, cupones, tarjetas de fidelidad y mapas que posee PROMO. Por medio de esta herramienta se podrá, entre otras cosas, crear promociones y definir sus condiciones, cupones, tarjetas, combos y beneficios. También se podrán crear los mapas que contienen las promociones para luego generar los archivos de configuración que se cargarán en el "Motor de promociones", para que puedan ser evaluados los tickets y calculadas las promociones en base a las definiciones generadas en la Consola.

Referencias Prácticas

>use promo
>db.createUser({user:"promousr", pwd:"thepassword", roles:[{role:"dbOwner", db:"promo"}]})

Pre-Requisitos del sistema

A continuación se detallan los requisitos mínimos para la instalación de la Consola de Administración de PROMO que operara con una (1) compañía.
Los requerimientos mínimos de hardware se proveen como una guía para el sizing de un ambiente no productivo. Para instalaciones en ambientes productivos con requerimientos específicos de performance y volumen de datos se requiere un sizing particular para estimar la configuración apropiada.

Considerar que la siguiente configuración sería la necesaria para utilizar un mapa no mayor a 1 MB y sin utilizar funciones de loyalty, de lo contrario debe analizar cuánta memoria debe utilizar.

Se describe la instalación de la base de datos y del JDK en Referencias Prácticas

Documentación relacionada

PROMO 7.3 - Guía Inicial de Integración

PROMO 7.3 - Manual de Integración - Colas de Mensajes

PROMO 7.3 - Manual de Integración - Motor

PROMO 7.3 - Manual de Integración - Servicios

PROMO 7.3 - Manual del Administrador

PROMO 7.3 - Manual de Lenguaje de Promociones

PROMO 7.3 - Manual de Usuario

PROMO 7.3 - Manual de Usuario Promo Lite

Ejecución del Instalador (Windows)

Deberá ejecutarse como administrador desde modo comando el Instalador "promo-console-installer-7.3.ORC1.jar" para proceder a la instalación y configuración de la consola y motor de simulación de PROMO. Para esto deberá ejecutarse el comando java –jar promo-console-installer-7.3.ORC1.jar
También se instalarán los siguientes componentes indispensables para el correcto funcionamiento de la aplicación:

• Wildfly 20

El servicio Wildfly, inicialmente vendrá configurado por defecto el directorio sugerido, ocupando el puerto 8080
Al finalizar el instalador se crearán todos los servicios y directorios correspondientes.

Instalación de la aplicación

Se deberá ejecutar como administrador, en modo comando el instalador de PROMO (promo-console-installer-x.x.x.jar)

Se presentara la siguiente pantalla donde se deberá presionar "Siguiente":

Luego se solicitará la aceptación de los términos y condiciones de uso de la aplicación.

Luego de aceptados los términos y condiciones, se solicitará que se identifique el nombre del usuario y el e-mail de quien (empresa o persona) está realizando la instalación.

A continuación se deberá indicar la ruta de acceso a Java (JDK) y el directorio donde se realizara la instalación de Promo. Por default se propone "c:\synthesis\Promo". También se deberá indicar el directorio donde se instalara la base de datos (MongoDb)

De no existir los directorios se solicitara autorización para la creación de los directorios necesarios para la instalación de PROMO.

Se solicitará indicar el directorio donde se instalará Wildfly, para que el motor se instale como servicio.

En caso de no existir el directorio, se solicitara autorización para la creación del mismo.

Ahora se instalará MongoDb, se debe colocar las credenciales del server de DB.

Se solicitara se informe si se desea instalar o solo activar los servicios que se instalan con PROMO.

Ya sea que haya instalado el motor como aplicación o como servicio continuará con los siguientes pasos:

En la siguiente pantalla que se presente, habrá que presionar el botón "Instalar" a fin de dar comienzo al proceso de instalación de PROMO y sus componentes.

Finalizada la instalación se mostrara la siguiente ventana donde se informara la correcta instalación de la consola de PROMO y se solicitara dar Clic en "OK" para terminar con el proceso.

Estructura de directorios

Luego de haber instalado la Consola de administración, quedará una estructura de directorios similar a la siguiente en el directorio de instalación (ej: "c:\synthesis\promo").
Los siguientes directorios y archivos son algunos de los que se deberán tener en cuenta:

• synthesis\promo\images: directorio de las imágenes
• \synthesis\promo\images\profile
• \synthesis\promo\images\barcode: contiene las imágenes de códigos de barras asociados a cupones emitidos.
• \synthesis\promo\images\promotion: contiene las imágenes que se asocien a las promociones
• \synthesis\promo\logs: información sobre las trazas de ejecución de la aplicación, incluyendo información técnica ante cualquier falla.
• \synthesis\promo\backup: backups de la base de datos MongoDB
• \synthesis\promo\import: directorio donde deberán alojarse los mapas para la importación de promociones.
• \synthesis\promo\mdb: aquí se encuentran las funciones utilizadas en la base de datos.
• \synthesis\promo\engine: el motor de promociones que utiliza la consola para la simulación de las mismas.
• \synthesis\promo\catalogs: directorio donde se alojaran los archivos de catálogo (.catalogs) que se importaran al iniciar la aplicación. Deberán generarse de manera manual las carpetas correspondientes a cada compañía, indicando en el nombre del directorio el ID de la compañía. (Ej.: \synthesis\promo\catalogs\22 donde 22 corresponde al ID de la nueva Ccia)
• \synthesis\promo\export: en este directorio se van a bajar los archivos que se exportan con el botón "Exportación Masiva" que se encuentra en los informes. Este directorio se crea automáticamente al realizar la instalación de Promo. Pero debe tenerse en cuenta que si se hace una actualización en lugar de una instalación desde cero, debe crear a mano este directorio.

Instalación Linux (CentOS 7)

Es requisito que antes de realizar la instalación de la consola estén instaladas los siguientes componentes:

• MongoDB 4.4
• JDK 1.8.0_25

Descriptos en Referencias Prácticas

Instalación de la aplicación (Consola de Promo)

Se deberá ejecutar como root el instalador entregado desde línea de comando de la siguiente forma:

[root@osboxes tmp]# java - jar promo-console-installer.X.X.X.jar

Donde X.X.X Corresponde al número de versión de PROMO que se está instalando.

Luego de ejecutado el instalador, comenzará a descomprimirse el archivo para dar comienzo a la instalación, que seguirá los mismos pasos que para Windows.

Una vez instalada la consola, será requerido iniciar Wildfly, lo cual podrá hacerse manualmente ejecutando "sudo ./standalone.sh", o bien podrá configurarse Wildfly como servicio en linux siguiendo los pasos indicados en la Web para tal fin.

Configurar Motor de Simulación como servicio en LINUX

Deberá generarse un archivo desde cualquier editor de texto, con el nombre "promo.service" y deberá contener las siguientes líneas:

Una vez generado el archivo, debera guardarse en  /etc/systemd/system y ejecutar el siguiente comando para notificar al sistema:

Luego habrá que habilitarlo para que ejecute al inicio con el siguiente comando:

De ser necesario accionar sobre el servicio podrán ejecutarse los siguientes comandos:

systemctl start promo →  iniciar el servicio
systemctl stop promo →  detener el servicio
systemctl restart promo →  reiniciar el servicio
systemctl status promo  →  ver estado del servicio1

Ejecución del sistema

Acceder a la Consola de administración

Una vez instalada la consola de PROMO podrá ser accedida desde algunos de los siguientes browsers soportados por Promo: Firefox o Google Chorme,

Ingresar la siguiente URL en la barra de direcciones del Browser:

http://IP-SERVIDOR:8080/promo

Donde IP-SERVIDOR es la dirección IP o DNS del computador donde se está ejecutando el servidor de aplicaciones.

Errores en la instalación de la consola

• 404 – ERROR de Inicialización en Instalador

  
  
  
  Este error pude se produce al no iniciarse la instalación de la consola desde una pantalla de comando ejecutada como administrador. Se deberá ejecutar como administrador, en modo comando el instalador de PROMO (promo-console-installer-7.3.x.x.jar)

Errores de inicialización de la consola

404 – ERROR (al iniciar la aplicación WEB)
Este error pude producirse porque no está levantado el servicio WildFly. Deberá revisarse en los servicios del sistema que el servicio WildFly este en ejecución. De no estarlo, iniciarlo y refrescar la página del navegado y volver a probar
Otro de los motivos por los cuales pueda darse este error es que no se haya descomprimido correctamente el aplicativo, para corroborarlo habrá que chequear en el directorio de instalación synthesis\promo\appserver\standalone\deployments si hay un archivo llamada "promo.war.failed". De encontrarse este archivo, indicara que se ha producido un error en la inicialización de la aplicación. Contactar al administrador del sistema para su solución.

Logs de Consola

Para aquellos logs que contengan code,barcode,identifier(customer, card, coupon),cuyo valor este registrado en la bbdd ,mostrará el id que genera mongodb para el registro, en los casos que no este el registro en la bbdd (por ej. el caso de las importaciones),el valor será reemplazado por asteriscos-

Cuando el valor sea menor a tres caracteres, mostrara todo con asteriscos; si el valor es mayor a 4 se dejaran los tres últimos caracteres visibles y los otros en asteriscos.

Esto se aplica en los siguientes procesos:

-Alta masiva de cupones

-Alta masiva de tarjetas

-Api rest /importaciones por catálogos ,de tarjetas, cupones, clientes

Ej. de log:

Motor de Promociones

Introducción

Como se mencionó en el punto anterior, el motor de promociones es el componente de PROMO encargado de recibir tickets directamente desde el punto de venta, luego procesarlos, y, finalmente, informar las promociones que participaron y los artículos afectados.
La instalación del motor de promociones se realiza conjuntamente con la instalación de la consola de Promo, al ejecutarse el instalador de la aplicación. La comunicación se establece a través de mensajes XML enviados mediante TCP/IP, REST.

Pre-Requisitos del sistema

En el siguiente cuadro se detallan los requisitos mínimos y recomendados para la instalación del motor de promociones:

Instalación (Linux/Windows)

Instalación del Motor de PROMO desde el Instalador

Se provee un archivo promo-gengine-installer-X.X.X.jar donde X.X.X es la versión del motor que se está instalando (7.3.X).
Se deberá ejecutar como administrador, en modo comando el instalador del Motor de PROMO (java –jar promo-gengine-installer-7.3.x.jar)

Al ejecutarse el instalador aparecerá la siguiente ventana:

Presionar "Siguiente" para continuar.

Se deberán aceptar los términos y condiciones para continuar con la instalación del motor de PROMO.

Presionar en "Aceptar" para continuar.

Luego de aceptados los términos y condiciones, se solicitara que se identifique el nombre del usuario y el e-mail de quien (empresa o persona) está realizando la instalación.

Presionar "Siguiente" para continuar.

A continuación se deberá indicar la ruta de acceso a Java (JDK) y el directorio donde se realizara la instalación del motor de PROMO. Por default se propone "c:\napse\gengine". 

Se podrá indicar aquí, por medio del check "Instalar Servidor REST (Default TCP/IP)", para que se instale el motor como SERVIDOR REST sino se instalara por default en modo TCP/IP.

Presionar "Siguiente" para continuar.

Si se desea instalar el motor como aplicación, se debe tildar el checkbox en la siguiente pantalla:

Luego de presionar "Siguiente", aparecerá el siguiente Pop-UP , donde se deberá indicar la URL de acceso a "Director" para futuras actualizaciones y el código de tienda que tomará el motor. 

Luego de presionar "Siguiente", debe completar los parámetros solicitados:

Presionar "Siguiente" para continuar.

En la siguiente pantalla que se presente, habrá que presionar el botón "Instalar" a fin de dar comienzo al proceso de instalación del motor de PROMO y sus componentes.

Finalizada la instalación se mostrará la siguiente ventana donde se informará la correcta instalación del motor de PROMO. Se solicitará dar Clic en "Aceptar" y luego en "Salir" para terminar con el proceso. 

 


Terminado el proceso de instalación del motor de promociones podrá chequearse en los servicios del sistema la existencia de dos nuevos servicios correspondientes al motor de promociones y al agente Director que ya estarán ejecutándose de manera atómica, hecho que marcará la correcta instalación y puesta en funcionamiento del nuevo motor de PROMO.

Instalación de Versiones Anteriores del Motor de PROMO

Se provee un archivo g-engine-x.x.x-installer.zip donde x.x.x es la versión del motor que se está instalando. Para instalar:

1. Crear una carpeta donde se ejecutará el motor (Cuidado de tener permisos de lectoescritura en la misma)
2. Descomprimir el contenido del zip en dicha carpeta.
3. Modificar el archivo conf/config.xml con los parámetros correctos de configuración acorde al entorno en que se estará ejecutando.
4. Ejecutar en modo comando como administrador "tcp.bat" en Windows o "sudo ./tcp.sh" en Linux.

Instalación del Motor de PROMO a través de la ventana de comandos (CMD)

A continuación, se indica con un ejemplo de  cómo llevar a cabo la instalación del motor de Promo a través de la ventana de comandos, en windows.

• Crear una carpeta donde se guardará el archivo de instalación.

• Guardar en dicha carpeta el archivo instalador del motor de la versión que se desea instalar.

• Abrir en modo Administrador una ventana de comandos

• Se abre la ventana cmd.

• Ir a la carpeta donde tenemos guardo el instalador, y copiar la ruta.

• Volver a la ventana de comando y escribir cd, dejar un espacio, y a continuación pegar la ruta que copiamos en al punto anterior.

• Presionar Enter y ya estaremos posicionados en la carpeta.

• A continuación, chequeamos la versión de jvm (Java Virtual Machine)

• Veremos la versión de Java:

Debe ser una versión Java 1.8

• Luego vamos a ejecutar el archivo de instalación del motor. Para forzarlo de que sea en modo texto, debemos tipear en la ventana cmd:

java -jar promo-gengine-installer-7.3.0RC3.jar text

Y a continuación presionamos Enter.

• Obtendremos la siguiente respuesta:

Y veremos esta imagen:

• Se ejecuta el instalador en modo texto. Veremos la siguiente pantalla, a continuación, presionar Enter.

• Luego se debe seleccionar Enter para ver la licencia.

• Se muestra la Licencia y se nos consulta si deseamos aceptar la licencia, como el valor por defecto es si (yes), presionamos Enter.

• Luego se presenta la siguiente pantalla donde se nos consulta si hemos leído y aceptado los Términos y Condiciones de Uso. El valor por default es false, por lo tanto, debemos tipear true y presionar Enter.

• La siguiente pantalla nos pide que ingresemos nombre completo. Escribimos el nombre y presionamos Enter.

• Luego nos pide ingresar el mail. Ingresamos el mail y presionamos Enter.

• A continuación, nos pide indicar la ruta donde se encuentra instalado el jdk.

Buscamos la carpeta donde tenemos instalado java, seleccionamos la ruta y la copiamos.

Luego pegamos esa ruta en la ventana cmd.

• Paso siguiente, nos pide que ingresemos el directorio donde queremos hacer la instalación.

Para ello primero creamos una carpeta para la versión 7.X  y dentro de ella una carpeta engine para el motor.

Luego seleccionamos y copiamos la ruta a la carpeta engine. Por último, pegamos esa ruta en la ventana cmd y presionamos Enter.

• En el siguiente paso nos pregunta si deseamos instalar el servicio REST. Como el valor por defecto es false, debemos tipear true y luego presionar Enter.

• Luego nos pregunta si instalamos TomEE, como el valor por default es false, presionamos Enter.

• A continuación, nos pregunta si instalamos Director, no lo vamos a instalar entonces debemos tipear false y presionamos Enter. Luego pregunta la ruta para Director, presionamos Enter.

• Luego debemos indicar id del motor y presionar Enter.

• También debemos ingresar un nombre para el motor y luego presionar Enter.

• En el siguiente paso debemos ingresar el puerto SOCKET, como vamos a dejar el valor por defecto de 3000, presionamos Enter.

• Luego nos pide ingresar el puerto REST, como vamos a dejar el valor por defecto 8888 presionamos Enter.

• A continuación, debemos completar la url de la consola. Si vamos a dejar el valor por defecto, presionamos Enter.

• Paso siguiente pregunta por las tiendas asociadas al motor, en este caso presionamos Enter.

• Allí comienza la instalación y nos va mostrando información de progreso. Hasta que nos indica que la instalación fue exitosa y que ha terminado.

Luego de un tiempo, vuelve a estar disponible la ventana cmd (si esto no ocurre se puede presionar CTRL+C).

Consideraciones a tener en cuenta

1. Al haber hecho ya la instalación, se generaron dos archivos en la carpeta donde se guarda el archivo instalador del motor

En el archivo ant.istall.properties quedó grabado todo lo que escribimos durante la instalación.

Por ello, si tenemos que hacer la misma instalación, llevamos el instalador con ese archivo ant.install.properties y nos vamos a encontrar todos los valores cargados, teniendo que presionar Enter solamente.

2. Si quiero hacer una instalación desde 0, borro esas dos carpetas y ya no tendrá los valores pre cargados, debiendo hacer todo el proceso devuelta.

3. Tener presente que java debe estar instalado previamente y que la versión debe ser 1.8.

Configuraciones Generales del Motor:

El motor de Promociones posee dentro de la carpeta ./conf archivos para parametrizar su funcionamiento.  Dichos archivos se detallan a continuación.

Archivos de Configuración

CONFIG.XML
Es un archivo en formato XML con la siguiente estructura.

<?xml version="1.0" encoding="ISO-8859-1"?>
<configuration>
    <general>
        <simulation>false</simulation>
        <compatibilityMode>false</compatibilityMode>
        <mapIdentifiers></mapIdentifiers>
        <ticketIdentifiers>store,terminal</ticketIdentifiers>
        <disableLoyalty>false</disableLoyalty>
        <disablePrices>false</disablePrices>
        <!--identificar unico por cada instancia del motor.-->
        <!--<engineId>1</engineId>-->
        <!--Nombre unico por cada instancia del motor.-->
        <!-- <engineName>ENGINE_NAME</engineName>-->
        <!-- Tiendas a las que esta asociado el motor -->
        <!-- <stores></stores> -->
        <!-- Otorgamiento de beneficio con límites: true otorga el saldo(default), false no otorga beneficio si el apply supera el saldo -->
        <useExactLimitValue>true</useExactLimitValue>
        <!-- Permite descuentos negativos true default por compatibilidad -->
        <negativeDiscount>true</negativeDiscount>
        <!-- Limita (cuando esta en true) dentro de un mismo paso que un cupon no de mas del 100% de un producto, (descuentosMonetarios + valor del cupon > xprice) recorta el valor del cupon para que no supere el 100%-->
        <adjustCalculatedCoupon>false</adjustCalculatedCoupon>
        <!-- Obtener de consola los limites de forma sincrona, default true -->
        <!--<fetchLimitsSync>true</fetchLimitsSync>-->
     </general>
    <offline>
        <!--Directorio donde se guardarán los tickets offline-->
        <directory>offline</directory>
        <!--Cantidad de segundos en los que chequea offline-->
        <check>60</check>
    </offline>
    <map>
        <!--Directorio desde donde el motor lee los mapas-->
        <directory>sales</directory>
        <!--Cantidad de segundos en los que chequea nuevo mapa-->
        <check>600</check>
        <!--Cantidad de dias hasta remover el archivo del mapa-->
        <daysUntilRemoval>100</daysUntilRemoval>
        <!-- remover mapas simulados -->
        <removeSimulatedMaps>true</removeSimulatedMaps>
        <!-- maximo numero de mapas simulados a mantener  -->
        <simulatedMapsMax>10</simulatedMapsMax>
        <!-- maximo numero de mapas simulados para iniciar el proceso de remocion  -->
        <simulatedMapsThreshold>30</simulatedMapsThreshold>
        <!-- remover mapas que sobrepasen el maximo simulatedMapsMax -->
        <removeNonSimMaps>false</removeNonSimMaps>
        <!--En true se almacena los mapas compilados para optimizar el tiempo de carga de mapas en caso de reinicio del motor -->
        <!--compiled>false</compiled-->
        <!--Directorio para almacenar los mapas compilados, solo se iutiliza si compiled es true-->
        <!--compiledDirectory>compiled</compiledDirectory-->
    </map>
    <response>
        <!--Decimales de redondeo de la respuesta-->
        <roundDecimals>2</roundDecimals>
        <roundCountables>3</roundCountables>
        <roundPoints>2</roundPoints>
        <!-- Metodo de redondeo de puntos:  roundDown/roundMath (default: roundDown) -->
        <roundPointsMethod>roundMath</roundPointsMethod>
        <!-- Solo redondear el summary del beneficio (default: false) -->
        <roundPointsTotalOnly>false</roundPointsTotalOnly>
        <!-- Cuando redondeo final, cantidad de decimales en el computo intermedio(default: roundDecimals) -->
        <roundPointsTotalCalcDecimals>2</roundPointsTotalCalcDecimals>
    </response>
    <server>
        <!--Con valor true se disponibiliza el uso de https-->
        <useHttps>false</useHttps>
        <!--El nombre del archivo que contiene el almacén de claves, especificando su ruta absoluta.-->
        <keyStore>./conf/keystore</keyStore>
        <!--Contraseña requerida por https correspondiente a la clave del almacén de claves-->
        <keyStorePassword>nosotros</keyStorePassword>
        <!--Con valor true se disponibiliza la restricción de recursos a determinados roles-->
        <useRoleAccessRestrictions>false</useRoleAccessRestrictions>
        <!--Ruta donde se encuentra el archivo de definición de usuarios y roles-->
        <usersDefinition>./conf/engineUsers.properties</usersDefinition>
        <!--Ruta donde se encuentra la carpeta que contiene al archivo de asignación de roles a recursos web.xml-->
        <configurationDirectory>./conf</configurationDirectory>
        <!--Puerto del servidor rest-->
        <rest>8888</rest>
        <!--Puerto del servidor socket-->
        <socket>3000</socket>
    </server>
    <promoCentral>
        <url>http://localhost:8080/promo</url>
        <user>sender</user>
        <password>mate</password>
        <!--
        Define el timeout en segundos de comunicacion con la consola central
        si se especifica este aplica en general y anula a los otros dos.
        -->
        <!-- timeout></timeout -->
        <!--
        Define el timeout en segundos de conneccion con la consola Central.
        -->
        <!-- connectionTimeout></connectionTimeout -->
        <!--
        Define el timeout en segundos de comunicacion con la consola Central.
        -->
        <!-- communicationTimeout></communicationTimeout -->
        <!--
        Descomentar en el caso que la mensajeria no lo
        implemente y se requiere el envio de un valor fijo
        -->
        <!-- companyId></companyId -->
    </promoCentral>
    <!--Directorio donde el motor busca el archivo entities.xml donde se configuran las extensiones para las entidades -->
    <!-- extensions>
        <directory>extensions</directory>
    </extensions -->
    <!--Directorio de trabajo del cache de datos interno utilizado por el motor, en caso de no especificarse el motor usa "./data" -->
    <!-- cachedata>
        <directory>data</directory>
    </cachedata -->
</configuration>

A partir de 7.2.3, para optimizar la carga de mapas se agregaron las siguientes configuraciones al config.xml:

<!-- remover mapas que sobrepasen el maximo simulatedMapsMax -->
        <removeNonSimMaps>true</removeNonSimMaps>
        <enablePosControl>true</enablePosControl>
        <pauseMapLoadOnStart>true</pauseMapLoadOnStart>
        <resumeMapLoadTime>21:00:00</resumeMapLoadTime>
    </map>

Esas configuraciones permiten ingresar el horario para la carga de los mapas, evitando afectar la performance del motor y la ralentización del sistema.

El Motor enviará un mensaje indicando hasta que hora estará pausada la carga de mapas. Como se muestra en la siguiente pantalla (en este ejemplo hasta las 21hs.):

En caso que se haga una venta antes de ese horario, el motor enviará un ack 2002:

Los parámetros de configuración de la sección General son:

stores

Los parámetros de configuración de la sección Offline son:

Los parámetros de configuración de la sección Map son:

Los parámetros de configuración de la sección Response afectan a la respuesta y cálculos internos del motor.  Estos son:

Los parámetros de configuración de la sección Server, afectan la comunicación del motor como servidor.  Estos parámetros son:

keyStore

./conf/keystore

Los parámetros de configuración de la sección promoCentral afectan la comunicación motor con la consola de promo.  Estos son:

Los parámetros de configuración de la sección Extensions afectan la definición e entidades que manejará el motor.  Los parámetros son:

Los parámetros de configuración de la sección cacjeData son:

Descarga de logs  del motor centralizada en la consola 

A partir de esta versión un usuario con rol administrador desde la consola de Promo puede bajar los logs de los motores.

Para ello se debe configurar en el config.xml del motor se debe agregar la información del FTP:

</ftp>

      <url>[SERVER]</url>

      <port>[PORT]</port]

      <usr>[USUARIO]</usr>

      <password>[PASS]</password>

      <sftp>false</sftp>

</ftp>

de la misma manera que el logging.properties

Optimización de carga de mapas en motor

Esta mejora consiste en habilitar la utilización de mapas pre-compilados, significa que el motor, luego de procesar un mapa xml generado por consola, guardará archivos compilados de mapas, promociones e índices en el directorio indicado, para que en caso de reiniciar el motor, cargar los mapas compilados en vez de cargarlos desde el xml, lográndose con esto un mejora de tiempo sustancial en mapas grandes.

En config.xml del motor se agregó dentro del tag <map>, dos entradas para configurar:
<compiled> es un flag que en 'true' habilita la utilización de mapas pre-compilados,
<compiledDirectory> indica el directorio donde se almacenaran esos mapas compilados. De no indicarse el motor usará el directorio 'compiled' .

Ejemplo de la configuración:

<configuration>
 ...
 <map>
   ...
   <!--En true se almacena los mapas compilados para optimizar el tiempo de carga de mapas en caso de reinicio del motor -->
   <compiled>true</compiled>
   <!--Directorio para almacenar los mapas compilados, solo se utiliza si compiled es true-->
   <compiledDirectory>compiled</compiledDirectory>
 </map>

En modo simulación esta funcionalidad no se utiliza ( el motor no la toma en cuenta en caso que haya sido configurada ) ya que lo esperado es que los mapas sean renovados frecuentemente para las simulaciones.

Para liberar  recursos en motor corriendo en 4690 al momento de carga de mapas en motores de backup, a partir de esta versión se agregaron los parámetros opcionales loaderDelay, loaderStartDelay  y  map ThreadPriority:

• loaderDelay: pausa en milisegundos durante la carga de cada mapa.

• loaderStartDelay: cantidad de milisegundos de espera para iniciar la carga de mapas luego del inicio del motor

• map ThreadPriority: prioridad del hilo de carga de mapas, valores: entre 1 (mínima prioridad) y 10 (máxima prioridad) siendo 5 prioridad normal.

<configuration>
        
        <map>
        
        <loaderStartDelay>60000</loaderStartDelay>
        <loaderDelay>500<loaderDelay>
        <map ThreadPriority>1</map ThreadPriority>

        </map>

 </configuration>       

LOGGING.PROPERTIES

En este archivo podrán configurarse los niveles de logueo de la consola, siendo el nivel SEVERE el nivel por default y ALL el nivel de logueo para debug.

Para más información sobre los diferentes niveles de logueo en Consola consultar el siguiente link: https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html

Para más información sobre los diferentes niveles de logueo en Motor consltar el siguiente link: https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/Level.html

# Agregar -Djava.util.logging.config.file=logging.properties como parametro a la JVM 
 _# http://www.javapractices.com/topic/TopicAction.do?Id=143_
handlers = java.util.logging.ConsoleHandler java.util.logging.FileHandler 
 
 .level = SEVERE 
 # File Logging 
 java.util.logging.FileHandler.pattern = ./logs/gengine.log 
 java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter 
 java.util.logging.FileHandler.level = SEVERE 
 #java.util.logging.FileHandler.limit = 10000000
 #java.util.logging.FileHandler.count = 10

 # Console Logging 
 java.util.logging.ConsoleHandler.level = SEVERE

Motor Multitienda

El Motor de promociones cuenta con la posibilidad de que levante y lea mapas de diferentes directorios. Cada directorio se corresponderá con una tienda distinta y en cada directorio podrá listar un conjunto de mapas.
El modo Multitienda se activa por configuración, encontrándose desactivado por default. La mensajería asociada al motor no se verá alterada por la activación del modo Multitienda.

Configuración de Multitienda

Para que el motor de promociones funcione en modo Multitienda, deberá de editarse el archivo "…\conf\Config.xml" y editar el siguiente tag:

 <general> 
 …… 
 <mapIdentifiers></mapIdentifiers> 
 <ticketIdentifiers>store,terminal</ticketIdentifiers> 
 …… 
 </general>

Donde en <mapIdentifiers></ mapIdentifiers> se identificaran las carpetas por las cuales el motor irá en búsqueda del mapa para evaluar la promoción. Deberán definirse en una lista separada por comas.
En caso de tener elementos, en <ticketIdentifiers></ticketIdentifiers> deberá quedar solamente definido "terminal" ya que al ticket lo va a identificar siempre por la concatenación de <mapIdentifiers> y <ticketIdentifiers>
Para que los cambios sean tomados correctamente se deberán guardar los cambios y reiniciar el motor de promociones.

Seguridad

Configuracion https

El motor de Promo puede ser configurado para trabajar en modo HTTPS.

Para una comprensión general de este modo de trabajo puede referirse a  (http://en.tldp.org/HOWTO/SSL-Certificates-HOWTO/x64.html)  pero en definitiva un resumen del mismo es:

     1.- El cliente hace un pedido al servidor usando el protocolo https://

     2.- El servidor le envía su certificado y clave pública.

     3.- El cliente verifica que el certificado sea emitido por una entidad de confianza, que esté vigente, y que corresponda al servidor contactado.

     4.- Si todo es correcto, el cliente usa la clave pública obtenida del servidor para encriptar una clave simétrica aleatoria y el mensaje http cifrado con esta misma clave aleatoria para luego enviarla al servidor.

     5.- El servidor desencripta la clave simétrica usando su clave privada (porque fue cifrada por el cliente con su clave pública) y utiliza esta clave para desencriptar la url y los datos http.

     6.- El servidor genera la respuesta http response, y luego encripta todo con la clave simétrica que obtuvo anteriormente.

     7.- El cliente desencripta los datos http usando la misma clave simétrica y continúa operando con http como siempre.

De la misma forma que para la consola, el motor necesita un almacén de claves (keystore) que contiene las claves pública y privada del servidor, en conjunto con un certificado).

Para configurar esto se poseen 3 nuevos parámetros en el archivo config.xml:

Un ejemplo de configuración sería:

<server>
        <useHttps>true</useHttps>
        <keyStore>c:\promo\keystore.dat</keyStore>
        <keyStorePassword>Promo2020</keyStorePassword>
        <rest>8888</rest>
        <socket>3000</socket>
</server>

Para generar el almacén de claves que incluye el par de claves y el certificado se deben seguir los siguientes pasos:

1. En este ejemplo vamos a generar un almacén de claves de nombre keystore para un alias de nombre Jettycon validez del certificado de 365 días y los algoritmos detallados.  Pedirá información que llevará el certificado, al final darle si para terminar. La clave que pide al inicio es una nueva clave y debe tenerse en cuenta ya que se configurará la misma en el motor.  Según la página esto funciona sólo para pruebas porque el certificado no es de confianza para el cliente (navegador por ej.).

   keytool -keystore keystore.dat -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA -validity 365   
   
   

2. Se puede revisar el almacén de claves con;

   
   

   keytool -list -keystore keystore.dat -storetype jks -storepass THEPASSWORD -v
   
   

3. Se genera el archivo csr (solicitud de firma del certificado / certificate signing request - CSR).

   
   

   
   

   keytool -certreq -alias jetty -keystore keystore -file jetty.csr
   
   

4. En el config.xml del motor ingresar los siguientes valores:
   

    <useHttps>true</useHttps>

    <keyStore>C:\keystore.dat</keyStore>

    <keyStorePassword>THEPASSWORD</keyStorePassword>

Autenticación por usuarios y roles

El motor de Promo en modo REST, acepta autenticación de conexiones por medio de Usuarios y claves. Para habilitar la autenticación en el motor por medio de usuario y password, se debe activar la siguiente configuración en el archivo config.xml:

Para configurar esto se poseen nuevos parámetros en el archivo config.xml:

Un ejemplo de configuración sería:

<server>
	<useRoleAccessRestrictions>false</useRoleAccessRestrictions>
	<usersDefinition>./conf/engineUsers.properties</usersDefinition>
	<configurationDirectory>./conf</configurationDirectory>
</server>

Archivo  de Usuarios (engineUsers.properties)

El formato del archivo de usuarios cumple el siguiente patrón:

<nombre de usuario>:<espacio>MD5:<clave como hash md5>,<rol1>,<rol2>,<rol n>

Entonces imaginemos configurar 3 usuarios: admin, sender y user.  La clave codificada de los mismos (MD5) se puede obtener desde: http://www.md5.cz/

El archivo de usuarios quedaría conformado como:

admin: MD5:4f4ea4182f8cbb5730694fb4866804ae,role-admin,role-sender
sender: MD5:4f4ea4182f8cbb5730694fb4866804ae,role-sender
user: MD5:4f4ea4182f8cbb5730694fb4866804ae,role-user,role-min

Tomemos el usuario admin, con clave promo2020 y roles admin y sender.

Roles  de Usuarios (engineUsers.properties)

Los roles son declarados en el archivo web.xml y siguen la siguiente estructura:

<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0">
 <display-name>Promo engine</display-name>
 <login-config>
 <auth-method>BASIC</auth-method> 
 <realm-name>promoEngine</realm-name> 
 </login-config>
 <security-role> 
 <role-name>role-admin</role-name>
 </security-role>
 <security-role>
 <role-name>role-sender</role-name>
 </security-role>
 <security-role>
 <role-name>role-user</role-name>
 </security-role>
 <security-constraint>
 <web-resource-collection>
 <web-resource-name>Engine</web-resource-name>
 <url-pattern>/engine/*</url-pattern>
 </web-resource-collection>
 <auth-constraint>
 <role-name>role-admin</role-name>
 <role-name>role-sender</role-name>
 </auth-constraint>
 </security-constraint>
</web-app>

Seguridad OAuth2

El motor de Promo en modo REST, acepta autenticación de conexiones por medio de OAuth2. Para ello se debe configurar en el archivo config.xml del motor:

Ejemplo:

<server>
    <securityType>oauth2</securityType>
    <oauth2Expiration>60</oauth2Expiration>
    <oauth2ClientId>engineClient</oauth2ClientId>
</server>

El archivo de usuario quedaría conformado como: 

sender: MD5:7c13aea47d6e6ddefd62d2c00653b2a4,role-sender
user:MD5:hashMd5DelPassword,role

Ejemplo curl de pedido de token, con clientId = engineClient, usuario = sender, contraseña = mate

curl -X POST "http://localhost:8888/engine/oauth/token" -u engineClient: -d "grant_type=password" -d "username=sender" -d "password=mate" -d scope=read

Ejemplo curl  de pedido de token, si se dispone del clientId en base64 (en este caso engineClient: es ZW5naW5lQ2xpZW50Og==) se puede utilizar la forma:

curl -X POST "http://localhost:8888/engine/oauth/token" -H "Authorization: Basic ZW5naW5lQ2xpZW50Og==" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password" -d "username=sender" -d "password=mate" -d "scope=read"

en ambos casos la respuesta es similar a:

{
"access_token":"825e2d64-ccb9-4b06-8c69-33992a35480e","token_type":"bearer","expires_in":60,"scope":"read"
}

En caso que clientId, username, password no sean los correctos, la solicitud de token retorna status 401 Unauthorized
En caso que grant_type sea distinto de 'password' la solicitud de token retorna status 400 Bad Request.

La evaluación vía GET es similar a sin autenticación, pero con el agregado del header Authorization, con valor "Bearer ${access_token}"

Ej:

GET http://localhost:8888/engine/evaluate?request=<message.....</message>
Authorization: Bearer 825e2d64-ccb9-4b06-8c69-33992a35480e

La evaluación vía POST tiene la siguiente forma:
header Authorization, con valor "Bearer ${access_token}" y header Content-Type: application/x-www-form-urlencoded, y request=mensaje en el body

Ejemplo:

POST http://localhost:8888/engine/evaluate
Authorization: Bearer 825e2d64-ccb9-4b06-8c69-33992a35480e
Content-Type: application/x-www-form-urlencoded
body, url encoded : request=<message.....</message>

En caso que el token sea incorrecto o vencido, la solicitud de evaluación devuelve status 401 Unauthorized.

Mantenimiento - Motor

Depuración de archivos de log

Como se mencionó anteriormente, los archivos donde se registran los eventos que suceden en el motor de promociones son almacenados en uno o varios archivos de log. Estos archivos pueden crecer en tamaño dentro del disco rígido, quitando espacio que el usuario puede utilizar para otros fines. Por lo tanto es posible que se requiera eliminar algunos de estos archivos para liberar espacio.
Para eliminar los archivos de log será necesario consultar el archivo de configuración de log (../conf/logging.propertiesl). En él estarán especificadas las políticas de log, los archivos y los directorios destinados para este fin.

Errores de inicialización

Los siguientes son errores que pueden producirse al iniciar el motor de promociones:

• java.io.FileNotFoundException: \log\669comm.log (El sistema no puede hallar la ruta especificada)
  • Indica un error en la configuración del archivo de log. El error indica que no puede encontrar la ruta o el archivo '\log\669.comm.log'. Para solucionarlo, se recomienda revisar el archivo de configuración config/log4j.xml.

• Exception in thread "main" java.lang.NoClassDefFoundError: …
  • Este error ocurre cuando hay errores en el classpath.

• java.net.BindException: Address in use: JVM_Bind
  • Este error se produce cuando el puerto de comunicaciones que utilizará el Motor de promociones está reservado o siendo utilizado por otra aplicación. Sólo puede suceder en una comunicación TCP/IP. Para solucionarlo se recomienda determinar cuál es la aplicación que utiliza el puerto y cerrarla o configurarla para que utilice otro, o bien modificar la configuración del Motor de promociones para que establezca sus comunicaciones por un puerto diferente (a través del archivo de configuración, propiedad promoCommunication.port).

Errores de procesamiento

Durante su funcionamiento, el motor de promociones podrá informar errores similares a los enunciados a continuación:

• [promo.MIDDLEWARE] PROMOENGINE VALIDATION ERROR: [P01] combo-component: invalid use of order-criteria with this set
  Indica que se ha producido un error en la validación de algún mapa que está intentando cargar. El valor que se encuentra entre corchetes indica en qué promoción se ha producido el error. De no existir los corchetes significa que el error se produjo en la definición de la convivencia de las promociones que se encuentra en el mapa. El texto que sigue a los corchetes describe el tipo de error producido. Asimismo, anterior a esta línea de log se encuentra que mapa se intentó cargar.

• [promo.MIDDLEWARE.MESSAGING] Message not accepted: Parser exception parsing input message: Content is not allowed in prolog.
  Indica que se recibió una petición o ticket que no respeta el formato definido para la mensajería. En estos casos el motor responderá a la terminal que envió el requerimiento un mensaje de respuesta con un código de error (ver "Manual de mensajería – Promo").

• [promo.MIDDLEWARE] There is no PromoEngine available to process this request.
  Este mensaje se emite cuando el Motor de promociones recibe una petición que indica la utilización de una versión de mapa inexistente. Al igual que en el caso anterior, al no poder resolver la petición, se responderá con un mensaje que especificará un código de error (ver "Manual de referencia técnica – API de Promo").

• [promo.MIDDLEWARE.MESSAGING]- WARNING: INVALID TICKET: cvc-datatype-valid.1.2.1: 's250.0' is not a valid value for 'double'.
  Indica que se ha recibido una petición o ticket que posee un valor o tipo de dato inválido. En este caso, el motor dará un mensaje de respuesta con un código de error (ver "Manual de mensajería – Promo").

Información de Configuración

Existen parámetros de configuración que pueden ser modificados para personalizar el comportamiento de PROMO.
Algunos de estos parámetros solo estarán disponibles en la consola de PROMO Principal y otros podrán ser editados desde la consola de PROMO de cada compañía.
Estos parámetros se encuentran en la Consola de PROMO, Menú "Administración" >> "Información de Configuración" y son:

Configuraciones disponibles para el Usuario Principal:

Configuraciones disponibles para el Usuario Admin de cada compañía:

Podrán existir cambios correspondientes a:

• actualización de la consola de administración (de existir alguna actualización se entregará la correspondiente documentación y la forma de instalarla),
• depuración de backups de BD.

Depuración de archivos de backup de Base de datos

La aplicación registra un backup automático diario de la base de datos MongoDB. Es por ello que es necesario realizar un cierto mantenimiento, consistente en la depuración de los mismos periódicamente a fin de que la carpeta de backup no ocupe demasiado en disco.

Enmascarar Contraseña de DB

La clave enmascarada de base de datos se genera mediante la promo-crypto-tool que será provista.

El programa toma como ingreso a la clave a encriptar y devuelve la clave encriptada que se debe situar en el archivo promoplus.properties en una entrada llamada grails.mongodb.encryptedPassword (por ej. grails.mongodb.encryptedPassword=lYYBAfxLR40=).

En caso de utilizar grails.mongodb.encryptedPassword se debe considerar comentar o eliminar la anterior grails.mongodb.password ya que en caso de existir ambas siempre utilizará grails.mongodb.password. En caso de que el archivo promoplus.properties no exista, se tomará, como valor por defecto, a v9vbhV.

Para encriptar una clave se debe utilizar promo-crypto-tool de la siguiente forma en una consola: 

java -jar <nombre del jar> <contraseña a encriptar>, por ej java -jar promo-crypto-tool-1.0.0.jar abcdefg

o bien

java -jar <nombre del jar> y al ejecutarlo, de modo interactivo, solicitará el ingreso de la contraseña.

En ambos casos la contraseña encriptada se obtendrá por pantalla.

Al momento de levantar el servidor, se hará uso de Datasource.groovy que mantiene el llamado a assignMongodbPassword() el cual a su vez llama al desencriptador para obtener la contraseña para asignársela a grails.mongodb.password.

Configuración de Redes Sociales

Para trabajar con redes sociales PROMO posee una serie de opciones de configuración que se describen a continuación. También es importante aclarar que los servicios de redes sociales están en constante evolución y cambio por lo cual aquí se hace referencia al sitio del servicio en cuestión para obtener la información actualizada al respecto.

Configurar Facebook

Desde la consola de cada compañía, accediendo con el usuario administrador, y accediendo a "Administración Información de configuración" se encontraran las siguientes configuraciones que serán necesarias completar para la correcta publicación en la red social.

• Generación de Aplicación en Facebook

Para poder utilizar la publicación en Facebook se deberá ingresar a https://developers.facebook.com/, darse de alta como desarrollador de Aplicaciones Facebook y agregar una nueva aplicación siguiendo los pasos indicados en la página.
Al crear una aplicación para Facebook, se comienza en estado de desarrollo y para poder realizar publicaciones hay que dar los permisos de "Administrador" al usuario de FB que realizara las publicaciones.

Por otra parte, si se quiere compartir o que otro usuario pueda realizar publicaciones, es necesario agregarlo al grupo de contactos (amigos) y darle permisos de "Administrador".

Al acceder a la URL indicada más arriba, se accederá a la sección de "Facebook for Developers" de Facebook.

Debe iniciar sesión, desde el botón correspondiente:

Al ingresar, se deberá dar clic en "Mis Apps".

Una vez allí, habrá que dar clic en el botón verde de "Crear app".

Se presentara el siguiente popUp donde se deberá seleccionar el tipo de app que se desea crear. En este caso, seleccionaremos "Negocio", y se deberá presionar "Continuar".

En el siguiente popUp se deberán ingresar los datos solicitados para dar nombre a la app que se esta creando y presionar el botón "Crear app"

Una vez creada la app se mostrara la siguiente pantalla, desde donde podrá accederse, desde la opción "Configuración" >> "Básica", a los datos de identificación de la aplicación recientemente creada.

Los datos a considerar y completar en esta sección serán:

• Identificador de la app: Sera requerido en Promo para poder configurar los datos de conexión a la app de Facebook (Los datos mostrados en las imágenes son de carácter ilustrativo y no son validos para la configuración de ninguna app)
• Clave secreta de la app: Sera requerido en Promo para poder configurar los datos de conexión a la app de Facebook. La clave se mostrará enmascarada y se solicitara la clave de usuario de FB para mostrarla.
• Nombre para mostrar: Sera el nombre de al app que se mostrara a los usuarios de FB.
• Dominio de la app: Deberá indicarse el dominio donde se encuentra Promo.
• Correo electrónico de contacto: Deberá indicarse el mail de contacto para la app.
• URL de la Política de privacidad: Deberá indicarse la política de privacidad de la compañía que desea publicar en FB desde Promo.

Sera necesario tener una pagina de Facebook dada de alta y asociada a la cuenta de usuario de Facebook para poder realizar las publicaciones en esta pagina.

Desde el perfil de usuario con el que se haya generado la app de Facebook, se deberá dar clic "Paginas" que se encuentra a la izquierda de la pagina.

Se presentara la siguiente pagina, donde se deberá dar clic en "Crear nueva pagina"

Al presionar en "Crear nueva pagina", se mostrará la siguiente pantalla, donde deberá de completarse la información solicitada en el margen izquierdo.

Una vez generada la pagina e ingresados los datos de configuracion aportados por la aplicación generada, se podrá proceder a la publicación de las promociones en la red social. (ver Manual de usuario Promo 7 - "Distribución">> "Redes Sociales")

IMPORTANTE

Https obligatorio para la publicacion en Facebbok

Facebook sólo se integra con sistemas que funcionen con https. Promo tendrá que tener configurado su wildfly con https

Para la cunfiguracion de wildfly con https será necesario editar el archivo "standalone.xml" ubicado en ...\synthesis\promo\appserver\standalone\configuration

Allí será requerido agregar los siguientes tags en:

<security-realm name="ApplicationRealm"/>

Para Promo sobre Wildfly 9

<security-realm name="ApplicationRealm">
   <server-identities>
      <ssl>
         <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="Promo2020" alias="jbossWildFly" key-password="Promo2020" />
      </ssl>
...
</server-identities>

Para Promo sobre Wildfly 12

<security-realm name="ApplicationRealm">
   <server-identities>
      <ssl>
         <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="Promo2020" alias="jbossWildFly" key-password="Promo2020" generate-self-signed-certificate-host="localhost"/>
      </ssl>
...
</server-identities>

<server name="default-server"/>

    
<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>

También será necesario generar y colocar el archivo "server.keystore" en el directorio ...\synthesis\promo\appserver\standalone\configuration. ( Como son claves de encriptación, tienen que ser generadas dentro del ambiente de instalación. Desde Napse se utilizó la herramienta de pruebas "keytool" de Java para la generación del mismo)

Una vez guardados los cambios en el standalone.xml y colocado el archivo "server.keystore.txt" en el directorio indicado, deberá de reiniciarse el wildfly para que los cambios sean tomados correctamente.

Configurar Twitter

Desde la consola de cada compañía, accediendo con el usuario administrador, y accediendo a Administración >> Información de configuración se encontraran las configuraciones que serán necesarias completar para la correcta publicación en la red social.

• Generación de perfil en Twitter
  
  

Deberá accederse a la URL https://developer.twitter.com/ y presentara la siguiente pantalla:

Deberá darse clic en el botón correspondiente al usuario logueado en Twitter,  se desplegara un menú y se dará clic en "Apps"

Se presentara la siguiente pantalla y debera darse clic en "Create an app"

Sera necesario completar los campos con los datos solicitados para poder crear la aplicación en base a las políticas de seguridad de Twitter.
Completos todos los campos, dar clic en "Create" y se mostraran las configuraciones disponibles para la nueva aplicación recientemente generada:

Para obtener los Ids y Tokens deberá darse clic en la solapa "Keys and Tokens" donde se visualizaran los datos necesarios para configurar correctamente los permisos de acceso desde Promo.

Una vez ingresados los datos de configuración aportados por la aplicación generada, se podrá proceder a la publicación de las promociones en la red social. (ver Manual de usuario Promo 7 - "Distribución">> "Redes Sociales")

Integración con Syslog/QRADAR

La implementación del envío de eventos a QRadar se apoya en el sistema de logueo log4j utilizado por Promo, agregando un appender específico para syslog "SysLogAppender" disponible en el paquete log4j, y el desarrollo de un clase que presta servicio a tal fin denominada "SysLogService" la cual formatea los mensages en otra clase "SysLogMessageFactory".

Para habilitar el envío a QRadar, se debe editar el archivo de configuración de logueo "log4j.xml" insertando las siguientes entradas antes del final:

<appender name="syslogappender" class="org.apache.log4j.net.SyslogAppender">
    <param name="syslogHost" value="myserver:myport"/>
    <param name="facilityPrinting" value="false"/>
    <param name="facility" value="AUTHPRIV"/>
    <param name="header" value="false"/>
    <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d{yyyy-MM-dd'T'HH:mm:ss.SXXX} %m%n"/>
    </layout>
 </appender>
 
 <logger name="sts.console.audit.SysLogService" additivity="false">
    <level value="info"/>
    <appender-ref ref="syslogappender"/>
 </logger>

</log4j:configuration>

Cambiar en el parámetro "syslogHost" , el valor "myserver:myport", por el correspondiente a la dirección ip y port del syslog server QRadar.  Ejemplo: localhost:514

Luego re-deployar la consola de Promo para que tome la configuración.

Tipos de eventos :

Los eventos que serán enviados a QRadar en una primera instancia son los correspondientes a usuario: login, logout, login failed, nuevo usuario, modificación de usuario.

Parámetros de Configuración de Ambiente

En esta sección se enumeran las opciones de configuración que afectan al funcionamiento del ambiente en su totalidad y se realiza desde el archivo promoplus.properties.

1. Validar CVV solo cuando se realiza un consumo en una Tarjeta de Fidelidad

Se disponibiliza la posibilidad de poder indicar por configuración que el CVV de una tarjeta de Fidelidad solo sea validado cuando se realiza un consumo de saldos en ella.

La tarjeta debe de tener activa la opción de CVV requerido en su tipo de tarjeta.

Para habilitar esta opción deberá definirse en el archivo "promoconfig.properties" el parametro promo.general.cvvOnlyForConsume = true

2. Configuración Atributos con espacios en Condiciones Simples

En Promo 7 por default no se puede ingresar en Condiciones Simples atributos con espacios, al ingresar el espacio toma como completo el nombre del atributo ingresado, como cuando se presiona la barra espaciadora:

Por configuración se puede cambiar y permitirá ingresar espacios en blanco en los atributos ingresados. Para eso debe editar el archivo promoplus.properties y agregar la siguiente línea:

promo.delimiters = no-space 

Con esta configuración para que interprete que se terminó de escribir el elemento debe presionar la tecla tab.

Si ingresa el parámetro: promo.delimiters = space funciona como viene por default, que no permite ingresar espacios dentro del texto ingresado en los atributos.

3. Alta de cliente durante la transacción

Para que el alta de clientes pueda efectuarse al momento de procesarse una transacción, deberá de habilitarse en el archivo de configuraciones de la Consola de Promo (“promoplus.properties”) el siguiente atributo:

Una vez actualizado, deberá de reiniciarse el Wildfly para que los cambios sean tomados correctamente.

Los clientes serán creados utilizando el estado "loyaltyValidation" en el caso de enviarse los datos mínimos y al mismo tiempo Promo detecte que el cliente no existe.  Los datos mínimos mencionados son (marcados en Rojo): 

<customer-add seq="1" id="10090504" identifier="10090504" type="test" name="pepe" lastName="rodrigues" identifierType="cpf" email="mimail@test.com" />

<?xml version="1.0" encoding="UTF-8"?>
<message companyId="napse" store="1" terminal="1" date-time="2020-11-03 11:11:22" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" map-version="2" tckpath="Y" suggest="true">
<customer-add seq="1" id="47001517" identifier="47001517" type="test" name="bruno" lastName="Lopez" identifierType="cpf" email="[email protected]" />
</message>

Nota: Para mas información ver "Manual de Integración 7.3 - Motor" - LoyaltyValidation.

Información de Director

Se debe utilizar la versión de Director 2.0 que no es compatible con la versión 1.

Resolución de problemas

Durante su funcionamiento, la Consola de administración podrá informar errores inesperados. Los errores que puedan a llegar a ocurrir utilizando la aplicación serán informados mediante un pop-up en rojo indicando la causa del mismo. Asimismo, el log de la aplicación que se encuentra en \synthesis\promo\log indicará más detalle acerca del mismo.
Si el error es por un tema de permisos o página no encontrada, se informará mediante una pantalla aclaratoria con el problema ocurrido.

Desinstalación

Para proceder con la des-instalación de la consola y motor de PROMO se deberá:

1- Bajar servicios

1. • PromoSImEngine
   • Wildfly
   • MongoDB
   • PromoEngine (si se instaló el motor)
   • PromoEngineDirector (si se instaló el motor)

2- Borrar directorio C:\Synthesis (ruta donde se instaló la consola)

3- Desinstalar MongoDB

4- Borrar los servicios de PromoSinEngine, Wilfly y MongoDB, y PromoEngine, PromoEngineDirector si se instaló el motor

Reverso de actualizaciones ante problemas en el proceso

Ante algún problema durante la actualización de una versión de consola o motor, deberá de bajarse los servicios involucrados y colocar el archivo .war o .jar anterior,  según se trate de una actualización de consola o motor respectivamente y volver a subir los servicios.

Luego de reestablecido el sistema contactar a Servicios de Atención al Cliente para poner en conocimiento de lo sucedido con el proceso de actualización

Apéndice A: Autenticación de Usuarios Externos (SAML2)

Por medio de la implementación en PROMO de SAML2 se lograra la integración de PROMO con un sistema de autenticación externos de usuarios de la consola de PROMO.

Se deberá tomar en cuenta que dentro de la consola existen roles de usuario que permiten ingresar a las diferentes funcionalidades que deberán mantenerse dentro de la consola. 

 Sera requerido siempre tener el usuario creado en la base para poder acceder a la consola y realizar la autenticación.

Para que promo utilice saml2, se deberá agregar, en el directorio \appserver\modules\system\layers\base\com\synthesis\configuration\main\ , los archivos properties correspondientes. Estos son:

1. saml.properties - Archivo principal de configuraciones.
2. saml-keymanager-passwords.properties
3. saml-metadata-providers.properties - Archivo correspondiente a la configuración del proveedor de identidad.
4. saml-metadata-sp-defaults.properties - Archivo correspondiente a la configuración que utilizará PROMO para generar su archivo xml de metadatos.

Consideraciones de las pruebas de Integración

1. Alta de usuarios en la consola de PROMO por medio del servicio rest correspondiente (createOrUpdateUsers). También podrán darse de alta manualmente desde la consola. En ambos casos deberá de tenerse en cuenta que los usuarios no deberán tener asignadas ninguna restricción en cuanto a políticas de seguridad propias de PROMO.

2. Obtener el xml de metadatos del sistema saml proveedor de identidad, del cliente. La ruta donde estará este archivo deberá tener especificada en la configuración properties. Para simplificar se puede renombrar como idp.xml.

3. Guardar el archivo idp.xml en C:\synthesis\promo\idp.xml

4. Editar el archivo saml-metadata-providers.properties especificando allí la ruta absoluta donde se colocó el archivo idp.xml
5. Iniciar PROMO (Wildfly) con los cuatro properties correspondientes a saml.
6. Generar el xml de PROMO accediendo a http://localhost:8080/promo/saml/metadata, guardarlo en un xml (preferiblemente sp.xml).

7. Guardar sp.xml en C:\synthesis\promo\sp.xml

8. Editar el archivo saml.properties especificando allí la ruta absoluta donde se colocó el archivo sp.xml

9. Editar el archivo saml-metadata-sp-defaults.properties especificando la ruta de promo (por ej. http://localhost:8080/promo).

10. Detener PROMO (wildfly)
11. Borrar los directorios \temp y \data que se encuentran en el directorio \standalone de la instalacion de PROMO.
12. Iniciar PROMO(wildfy).
13. Al acceder a la consola de PROMO en lugar de la pantalla de inicio de sesión aparecerá la pantalla de inicio de sesión del proveedor de identidad.

14. Luego de ingresar usuario y clave en el proveedor de identidad, se presentará la consola de PROMO, logueada con el usuario ingresado,                                                                                                                                         en la página de inicio correspondiente al rol que tiene asignado.

    
    
    

Si el usuario no corresponde a ningún usuario dado de alta en PROMO el login fallará, y se volverá a la pantalla del punto 13 para volver a intentar a ingresar un usuario valido y poder iniciar sesión en PROMO.

Si el usuario es uno existente iniciará sesión en PROMO sin problemas.

Properties:

• saml.properties, debe mantener la ruta absoluta al archivo de metadatos del proveedor de servicios.

  #
  # Configuraciones para la utilización de SAML2
  # Más info en https://sphoortia.github.io/grails-spring-security-saml/docs/guide/configuration.html
  #
  grails.plugin.springsecurity.saml.userGroupAttribute = memberOf
  grails.plugin.springsecurity.saml.metadata.sp.file = C:\\synthesis\\promo\\sp.xml
  grails.plugin.springsecurity.saml.metadata.sp.alias = promo_saml
  grails.plugin.springsecurity.saml.responseSkew = 60
  grails.plugin.springsecurity.saml.idpSelectionPath = /
  grails.plugin.springsecurity.saml.loginFormUrl = /saml/login

• saml-metadata-providers.properties, clave ping, debe mantener la ruta absoluta al archivo de metadatos del proveedor de identidad.

  ping=C:\\synthesis\\promo\\idp.xml

• saml-metadata-sp-defaults.properties, clave entityBaseURL, debe mantener la ruta de promo.
  

  local=true
  alias=promo_saml
  entityBaseURL=http://localhost:8080/promo
  securityProfile=metaiop
  signingKey=ping
  encryptionKey=ping
  tlsKey=ping
  requireArtifactResolveSigned=false
  requireLogoutRequestSigned=false
  requireLogoutResponseSigned=false
  idpDiscoveryEnabled=false

  
  
  

• saml-keymanager-passwords.properties

  #apollo = nalle123

Apéndice B: OS4690

Instalación de Motor en OS4690

Se deberán seguir los siguientes pasos para instalar correctamente el motor de PROMO en un OS4690:

• Envié el jar entregado a un controlador, al raíz del disco F con el nombre, por ejemplo: promo-gengine-installer-x.x.x.jar

• Ejecutar el instalador:  F:/instala> javaebin:java -jar promo-gengine-installer-x.x.x.jar

• Dependiendo si está disponible el modo gráfico, se podrá ejecutar en ese modo o en modo texto. Se recomienda el modo gráfico y ejecutar desde la carpeta F:/instala

• Cuando se solicite, indicar estos valores: 

Directorio java: /opt/java/tdk8
Directorio de instalación: /cdrive/f_drive/instala/promo

• Pueden presentarse errores al instalar servicios. Esto es debido a los permisos del Linux4690, ignorar.

• Se generan los archivos:

F:/instala/ant.install.log
F:/instala/ant.install.properties

• Se genera la carpeta F:/instala/promo

• Revisar y Copiar los siguientes archivos:   Modifcar el  config.xml (…promo/engine/conf) para especificar las rutas correctas:

    <offline>
        <!-Directorio donde se guardarán los tickets offline->
        <directory>/cdrive/f_drive/promo/engine/offline</directory>
        <!-Cantidad de segundos en los que chequea offline->
        <check>60</check>
    </offline>
    <map>
        <!-Directorio desde donde el motor lee los mapas->
        <directory>/cdrive/f_drive/promo/engine/sales</directory>

• Modificar logging.properties (…promo/engine/conf)    para especificar las rutas correctas:  java.util.logging.FileHandler.pattern = /cdrive/f_drive/promo/engine/logs/promo

• Configurar aplicación Background: 

Programa: shell
Parámetros: F:/promo/engine/tcp4690.bat  (o rest4690.bat para trabajar como servidor tcp ip o rest según sea el caso). 

•      Iniciar cuando es Maestro y cuando no es Maestro
•      Activar configuración y cargar Controlador 

Apéndice C: Variables de Entorno

Set PATH JAVA_HOME en Windows

Para que la aplicación se ejecute correctamente será necesario, setear la variable JAVA_HOME en Windows.  Para ello ingresar a Panel de Control > Sistemas y Seguridad > Sistemas y seleccionar "Configuración Avanzada del Sistema"
En la solapa de Opciones Avanzadas, dar clic en "Variables de Entorno". En Variables de Sistema, posicionarse en JAVA_HOME y dar clic en "Editar" y colocar la ruta donde se encuentre JAVA.

En Variables del sistema, buscar PATH, y hacer clic en "Editar", luego agregar % JAVA_HOME% \ bin

Dar clic en "Aceptar" para guardar los cambios y que la variable quede seteada correctamente.

Apéndice D: Actualizaciones de Consola

Actualización por nuevos Release

En caso de que un nuevo reléase de su versión de consola sea liberado, pudra realizar la actualización de la versión de PROMO siguiendo estos pasos:

1. Bajar el servicio de Wildfly (acceder a la sección de servicios del sistema y detener Wildfly)
2. Acceder al directorio donde este instalada la consola de PROMO (por default en C:\synthesis\promo)
3. Ingresar al directorio C:\synthesis\promo\appserver\standalone y eliminar los directorios "data" y "tmp"
4. Ingresar al directorio C:\synthesis\promo\appserver\standalone\deployments y reemplazar el archivo promo.war existente por el enviado por el personal de Synthesis.
5. Hecho esto, iniciar nuevamente el servicio wilfly.

En caso de terminar satisfactoriamente el proceso, este archivo será renombrado como promo.war.deployed.
De presentarse algún error durante la descompresión de la actualización, se generara un archivo llamado promo.war.failed el cual deberá ser enviado al personal de soporte para su análisis y posterior resolución del inconveniente a fin de iniciar correctamente la consola.