Guía de Migración desde v5.x ó v6.x a v7.x.

Es un procedimiento manual que se aplica sin importar si partimos desde una versión 5.x ó 6.x. En caso de tener consideraciones especiales por la versión que estamos intentando migrar, la guía lo indicará.

Requisitos previos

Al planificar la migración se debe asegurar haber comprobado los siguientes puntos para que la misma pueda comenzar sin obstáculos:

Que el equipo donde se instalara cumple los requisitos de hardware y software recomendados.
Que se dispone de un usuario con privilegios de administrador en dicho equipo.
Que se disponga de las licencias necesarias (nuevas si se trata de un cambio de 5.x a 6.x o 7.x) o las vigentes para el nuevo equipo.
Que se disponga del instalador de la nueva versión en el equipo.
Que se evalúe la necesidad de disponer de replicas de Bases de Datos para la nueva instalación de:
1. RBAC: esta BD es la que tiene definición de usuarios, roles, asociaciones entre éstos y permisos sobre artefactos como reportes, etc. Tener en cuenta que puede tener roles solamente, por ejemplo cuando los usuarios se toman de un LDAP
  - En O3 BI v5.x se encuentra en \jboss\server\default\deploy\gserver\gserver-*-ds.xml, donde * es el nombre del motor utilizado, por ejemplo gserver-hsql-ds.xml (por default en O3, hypersonic), gserver-oracle-ds.xml, etc.
  - En O3 BI v6.x se encuentra en la misma ubicación que en O3BI v7
  - (En O3 BI v7 se encuentra en jboss/standalone/deployments/O3Server-ds.xml, datasource donde se encuentran definidos los parámetros de conexión a la base de RBAC)
2. Liferay: esta BD es la que tiene las definiciones de portales (ver <O3DIR>/liferay/tomcat/webapps/eportal/WEB-INF/classes).
  1. Si en la version anterior, Liferay estaba usando HSQL, se debe copiar la carpeta <O3DIR>/liferay/data/
    
    Si se viene de una versión de O3 anterior a 7.1.0, ver previamente y aplicar para continuar con el procedimiento de migración, el siguiente wiki : /wiki/spaces/ISPRDO3/pages/126752778

Procedimiento de Migración

El caso ejemplo asume instalación en producción al momento de la migración en /opt/ideasoft/VersionAnterior:

1. Instalacion y comprobacion inicial

Instalar la nueva versión de O3BI v7 en directorio de preferencia. Por ejemplo en /opt/ideasoft/o3bi-v7. Para tener detalles de como proceder se deben seguir los pasos del siguiente instructivo Guía de Instalación de O3 BI 7. Alli se indica, por ejemplo como instalar servicios en llinux,
La activación de licencias está explicitado en la guía anterior, pero en caso de versión 6.x alcanza con copiarlas desde /opt/ideasoft/VersionAnterior/license/*.lxml a /opt/ideasoft/o3bi-v7/license/.
Levantar las aplicaciones por linea de comando. En SO Windows se debe abrir una consola "ejecutando como Administrador". Estos son:
1. exist-db-start
2. jboss
3. liferay
Acceder a localhost:8080/o3web y localhost:8380/eportal. Verificar que el acceso al portal (cubos y vistas Demo) y a liferay (comunidad Demo) es correcto.
Bajar las aplicaciones iniciadas en el punto 1.2.

2. Configuracion de BD utilizadas

En caso que la versión anterior este almacenando información en BD, asegurar que existen respaldos al día y sino hacerlo en el momento y continuar:

1. Verificar si es necesario copiar de la versión anterior drivers que se utilicen y que no sean distribuidos por O3. Esto lo realiza comparando los contenidos de la siguiente carpeta en versión anterior y nueva:
  1. <O3BI_VersionAnterior>/classes/jdbc.
  2. <O3BI_VersionAnterior>/liferay/tomcat/lib/ext
2. Configurar archivos properties y datasource de la nueva versión para que haga referencia a las BD de la versión anterior.
  Analizar lo que ya este configurado en los siguientes archivos de la versión anterior y modificarlos en la nueva:
  1. RBAC: en O3 BI v7 se ubica en jboss/standalone/deployments/O3Server-ds.xml, en versiones anteriores en:
    - En O3 BI v5.x se encuentra en \jboss\server\default\deploy\gserver\gserver-*-ds.xml, donde * es el nombre del motor utilizado, por ejemplo gserver-hsql-ds.xml (por default en O3, hypersonic), gserver-oracle-ds.xml, etc.
    - En O3 BI v6.x se encuentra en la misma ubicación que en O3BI v7
    en caso de venir de bases de datos (embebida de O3) Derby o Hipersonic
    (Indicar procedimiento) - Utilizar alguna herramienta que haga el pasaje (Ej.: TALEND)
    
    Procedimiento para creación de tablas RBAC y sentencias SQL para insertar datos (para inicializar con algunos usuarios)
    Creación tablas para RBAC en Base de Datos
  2. o3server.cfg. Si aún se está utilizando este archivo no se requiere la ejecución de ningún paso previo. El migrador lo consulta y exporta la información que contiene hacia eXist.
  3. Liferay: Para configurar la DB de liferay se debe modificar el archivo portal-ext.properties, adecuando las properties " jdbc.default.* "
    1. Si estamos migrando desde / hacia una version mayor o igual a 7.1.0 el archivo se encuentra en <O3DIR>/liferay/
    2. SI estamos migrando desde / hasta una version 7, pero anterior a 7.0.9: el archivo se encuentra en <O3DIR>/liferay/tomcat/webapps/eportal/WEB-INF/classes.

3. Personalización de la nueva instalación y/o versión

Personalización de la instalación:
1. Copiar el archivo /opt/ideasoft/VersionAnterior/O3Server_custom.properties desde la versión anterior a la nueva versión. Tener en cuenta que en versión 5.x existían otras propiedades que no se mantienen en versiones posteriores, por lo que es MUY IMPORTANTE revisar la lista de propiedades existentes en caso de partir de una versión 5.x. En versión 5.x el nombre del archivo es GServer_custom.properties y se puede encontrar en ...
2. Ajustar los parámetros de memoria y otros, de JBoss, Liferay, O3Designer, O3Builder.
Se solicita seguir los siguientes instructivos en caso de querer cambiar nombre o ip, puertos, configurar apache o https en la nueva versión, modificar url de eportal, instalar servicios en Linux:
Verificar que los servicios de la versión anterior están bajos
Copiar la carpeta opt/ideasoft/VersionAnterior/server, pero sin copiar la carpeta opt/ideasoft/VersionAnterior/server/istore/rules ya que debe quedar vacía en la nueva versión.
Si se tienen reportes publicados, revisar directorios de drivers y copiarlos. Ver O3 Report - Ubicación de drivers
Levantar la base exist de de la versión nueva, ejecutando el bat o sh correspondiente dependiendo del servidor (por defecto levanta en el puerto 8088):
1. <o3v7/>/sh/exist-db-start.sh
2. <o3v7/>/bat/exist-db-start.bat
Para considerar las modificaciones que se solicitan en el punto número 8, es necesario acceder a la base exist levantada en el puerto 8088.
A continuación se especifican los pasos para poder acceder:
1. Acceder a <NuevaVersion>/exist-db/bin en la nueva instalación.
2. Ejecutar el client.bat o client.sh dependiendo del servidor.
3. Este último paso nos abre un cliente exist que tiene la siguiente apariencia:
4. Se debe modificar la url de la siguiente forma: xmldb:exist://localhost:8088/exist/xmlrpc y seleccionar "Connect".
5. Una vez conectados, se observa el acceso a la base de la siguiente forma:
Respecto a la migración de cubos, los mismos guardarán su definición en la base exist con un identificador numérico.
Es sugerencia para los cubos más importantes seguir los siguientes pasos, de forma tal que se identifiquen con un nombre más nemotecnico y no numérico como se realiza de forma automática.
1. Desde el cliente exist abierto en el punto anterior, se solicita abrir el archivo o3bi/domains/default/current/runtime/Administrator/initialMigrationMapping.xml.
  Se debe agregar un nodo <mapping> por cada cubo del cliente que se le quiera dar identificación manual.
  A continuación se ejemplifica el nodo a agregar, el mismo en key y oldValue debe conter el identificador anterior. Por ejemplo, en caso de versión 6.x es dato de su dublin core con la siguiente forma: <ns3:identifier>cube::o3bi/Wines::Wines</ns3:identifier>.
  En newValue es donde vamos a dar nuestro nombre identificatorio. La identificación newValue contiene varios componentes separados por ":", se debe asignar el nombre como último elemento, teniendo en cuenta que no puede contener mas de 20 caracteres, ni  espacios ni ningún otro carácter especial. En el ejemplo a continuación el nombre asignado es "Wines".
  Ejemplo de un <mapping>:
       <mapping>
          <key>cube::o3bi/Wines::Wines</key>
          <oldValue>cube::o3bi/Wines::Wines</oldValue>
          <newValue>urn:o3bi:default:r:cube:n:o3bi:Wines</newValue>
      </mapping>

4. Migracion de vistas, reglas, programaciones, portales, etc.

Si la migración corresponde a un escenario de cambio de equipo:
1. se debe copiar la instalación anterior en el nuevo equipo. Recordar eliminar logs para facilitar la copia
2. se deben copiar los cubos manteniendo la misma estructura que en la versión anterior.
Configurar lo siguiente:
La carpeta <NuevaVersión>/migration contiene los archivos que llevan a cabo la migración.
Según corresponda para el sistema operativo se utilizará o3bi-migration.sh para Linux y o3bi-migration.bat para Windows.
Realizar las siguientes modificaciones sobre al archivo a ejecutar, con cualquier editor de texto:
1. VERSION_MIGRACION="<número de la nueva versión donde se va a migrar>"
2. RUTA_ORIGEN ="<ruta desde la que se quiere migrar>"
```
Ejemplo:VERSION_MIGRACION="7.1.0-01" RUTA_ORIGEN ="/opt/ideasoft/VersionAnterior" 
```
Comprobar que se tiene el driver jdbc de la base de RBAC en <NuevaVersión>/migration/o3bi-migration/jdbc.
Abrir una consola y ejecutar el siguiente comando:
```
En Linux: <NuevaVersión>/migration/o3bi-migration.sh >> migration.log
```
```
En Windows: <NuevaVersión>/migration/o3bi-migration.bat >> migration.log
```
Como resultado del mismo se genera en <NuevaVersión>/migration/migration.log un archivo donde se especifica lo realizado por el migrador. Se debe inspeccionar para comprobar si existen errores.

5. Verificacion de la instalacion realizada

Finalmente levantar jboss y liferay de O3 BI v7
Ingresar con usuario administrador a localhost:8080/o3web
Observar que los cubos y vistas fueron migrados, así como en ePortal los dashlets apuntan a las nuevas vistas (esto último para el caso de migrar versión 6.x).
Revisar roles de licenciamiento y asignación de usuarios a los mismos.
1. En caso de migrar desde versión 5.x se deben reasignar a los nuevos roles de licenciamiento, pues estos cambian a partir de versión 6.x
Si la migración corresponde a un escenario de mantenerse en el mismo equipo: Modificar los servicios que levantaban la versión anterior para que ahora apunten a O3 BI v7.

6. Ajustes posteriores a la verificacion

Se recomienda analizar y realizar ajustes según corresponda a la nueva disponibilidad de recursos:

Configuración de memoria de la aplicaciones (JBoss, exist, Liferay, designer, builder)
Definición de propiedad de memoria total de cache del servidor
Definición de cache de los distintos cubos (en el admserver, para la navegación)
Definición de cache de cada modelo (en el designer, para la actualización)

Configuracion de mail

Se deben configurar el envío de mails para reglas.

Build Now

Se deben configurar las acciones para actualizar los cubos desde el cliente web

Helps de cubos

Se deben copiar las carpetas que contengan ayudas a los cubos desde la versión anterior a la nueva

Imagenes de Liferay

Se deben copiar las carpetas de imágenes utilizadas en Liferay desde la versión anterior a la nueva

Consideraciones a tener en cuenta

No se aplica la migración a perfiles/restricciones sobre cubos que no estén asociados a usuarios.
En versiones 5.x NO SE MIGRAN LOS PORTALES. En estos casos coordinar con nuestros consultores la realización de forma manual del nuevo portal en v7.

Como migrar un subconjunto de vistas

Si luego de realizar la migración se desea repetir la migración para un subconjunto de vistas, se puede seguir los pasos indicados en la siguiente guía Guia de migracion de vistas locales

El escenario que justifique esta actividad es que se hayan creado nuevas vistas en el periodo entre que se preparo la migración y efectivamente se puso en producción

Browser not supported