• Creación de objetos de base de datos desde SQL Workshop.

• Creación de una aplicación básica, sin páginas iniciales, todo desde cero.

• Creación de las reglas de seguridad para autenticación y autorización.

• Creación de listas de valores.

• Modificación de las páginas para adecuarlas a nuestras necesidades.

Voy a asumir que tienen conocimientos suficientes sobre esquemas de base de datos, claves primarias y foráneas (PRIMARY KEYy FOREING KEY). Además, pueden utilizar cualquier instancia de APEX para desarrollar este ejercicio, ya sea su computador o en la versión gratuita de Oracle APEX.

Importante: esta aplicación es apenas una demostración así que seguramente me tomaré algunas libertades que tal vez no haría en una aplicación para desplegar en un ambiente productivo.

Requerimientos del usuario

Vamos a crear una aplicación muy básica pero que nos permitirá ver conceptos importantes en la creación de aplicaciones APEX. Crearemos una aplicación que servirá a un departamento de Gestión Humana para registrar a los empleados de la compañía. Los requerimientos que tiene la aplicación son:

• Registrar los datos básicos de los empleados: nombres, apellidos, fecha de nacimiento, estado civil, etc.

• Registrar los datos de relación del empleado con la empresa: cargo, gerencia o departamento, sucursal o filial en la que trabaja, supervisor, fecha de ingreso, código del empleado asignado por RRHH.

• Registrar los datos de contacto del empleado: correo electrónico, número de teléfono / extensión, dirección de la oficina o cubículo asignado.

• Los usuarios de la aplicación que pertenezcan al departamento de RRHH podrán ver y modificar los datos de todos los empleados.

• El resto de los usuarios podrá ver sus propios datos y los datos básicos de contacto del resto de los empleados.

• La aplicación debe por ser usada tanto desde un computador como desde dispositivos móviles. Debe ser visualmente agradable y capaz de adaptarse a múltiples tamaños de pantalla.

• Cada usuario ingresará con su dirección de correo electrónico y una contraseña.

Definición de objetos de base de datos

El primer paso antes de comenzar a desarrollar la aplicación es la definición de los objetos de base de datos que serán el repositorio de la información. Estos objetos deben ser modelados según los requerimientos que nos han dado los usuarios. Comenzaremos definiendo los objetos de manera básica y luego los convertiremos en objetos de base de datos Oracle

En primer lugar, sabemos que debemos registrar los datos de los colaboradores, al menos la siguiente información:

• Nombre y apellido

• Fecha de nacimiento

• Estado civil (soltero, casado, unión libre, etc.)

Sabemos que también hay cierta información que es exclusiva de un único empleado (código de empleado, fecha de ingreso, correo electrónico, etc.) así que lo podemos ver como una relación 1:1, podríamos agregar esos datos en el mismo objeto que usaremos para guardar los datos básicos. De esta forma, una tabla de EMPLEADOS podría quedar de la siguiente forma:

Veamos un par de puntos con esta tabla antes de continuar:

• La columna ESTADO_CIVILes de un tamaño de apenas un carácter porque solo vamos a guardar un valor que luego podremos obtener en una lista de valores (por ejemplo S para 'Soltero', C para 'Casado').

• Al momento de crear la tabla debemos agregar una columna para la clave primaria, lo cual haremos usando un IDENTITY COLUMN.

• Siguiendo la misma línea del punto anterior, es por eso que la columna ID_DEPARTAMENTO es un campo numérico, haremos referencia al PRIMARY KEYde la tabla de departamentos. Haremos lo mismo con el cargo, de esa forma nos aseguramos que todos los empleados que sean "Analistas contables" tengan el mismo nombre de cargo.

Ahora veamos la tabla de departamentos, será una tabla muy simple con apenas algunas columnas:

Sucede lo mismo con los cargos:

Veamos ahora el caso de los números de teléfono del empleado, podríamos agregar una columna de número de teléfono en la tabla EMPLEADOSpero nos limitaría la cantidad de números que podríamos agregar. Un empleado puede tener muchos números de teléfono (una relación 1:N) por lo que crearemos una tabla para registrar estos números

Lo mismo podría pasar con las direcciones, podríamos querer guardar la dirección de la casa del empleado y la dirección de la oficina.

Definición de la seguridad

La seguridad de la aplicación debería ser definida desde un principio, ya que luego sería mucho más complicado implementarla. Veamos nuevamente los requerimientos relacionados con la aplicación

• Los usuarios de la aplicación que pertenezcan al departamento de RRHH podrán ver y modificar los datos de todos los empleados.

• El resto de los usuarios podrá ver sus propios datos y los datos básicos de contacto del resto de los empleados.

• Cada usuario ingresará con su dirección de correo electrónico y una contraseña.

Para cumplir con estos requerimientos haremos uso de algunos componentes propios de APEX para manejar la seguridad: Authentication Schemes y Authorization Schemes.

Hay varias formas de resolver el requerimiento relacionado a la autorización:

• Usar la funcionalidad nativa de APEX para el control de acceso, es la más sencilla pero he encontrado un par de debilidades:

  • Es poco flexible, en caso de ser necesario agregar un nuevo rol o asignar un usuario a un rol debe hacerse desde APEX directamente, no lo podría hacer un usuario de la aplicación.

  • Al exportar una aplicación e importarla en otro workspace, los usuarios que están dentro de los roles no son importados, por lo que es necesario agregarlos nuevamente de manera manual.

• Crear tablas para el manejo de los roles, este enfoque permite que la seguridad pueda ser administrada desde la misma aplicación por los usuarios finales, y es fácil de replicar entre ambientes.

Para este caso vamos a usar la segunda opción y veremos cómo aun es posible construir la seguridad de manera declarativa.

Primero definimos una tabla donde guardaremos los nombres de los roles

Un empleado puede tener múltiples roles, por lo que crearemos una segunda tabla con dicha relación.

Ahora que ya hemos definido los objetos que vamos a necesitar, podemos crearlos en la base de datos. Para hacerlo más interesante, veamos cómo crearlos usando Quick SQL, una funcionalidad de SQL Workshop.

Para ingresar a Quick SQL ingresamos a APEX - SQL Workshop - Utilities

Con Quick SQL escribimos en texto plano los nombres de las tablas y las columnas y automáticamente se generará el código SQL necesario para crear dichos objetos.

Comencemos con la tabla departamentos:

Solo fue necesario ingresar el nombre de la tabla y los campos en las líneas siguientes con un par de espacios y Quick SQL generó todo el DDL de manera automática, incluyendo la columna de primary keyque no coloqué en el texto original.

Sobre los modificadores que utilicé:

• /auditcolspermite agregar columnas de auditoría a la tabla (cuándo fue creado el registro, por quién, cuándo fue modificado) y los triggers necesarios para llenar dichos campos de manera automática

• /uniquepermite agregar un constraint uniquesobre las columnas de la tabla, en este caso el código del departamento.

Agregaremos la tabla de cargos y la tabla de empleados y le indicaremos a Quick SQL que existe una relación entre todas ellas.

De manera automática se crean los foreing keynecesarios en la tabla empleados, así como los índices sobre dichas columnas (utilizando el modificado /fk)

Completemos la tarea con el resto de las tablas que definimos en el análisis del requerimiento. Una vez que estemos satisfechos con el resultado (que siempre podremos modificar según nuestras necesidades) hacemos clic en Review and Run, esto nos llevará al Script Editor y allí podremos hacer las modificaciones que necesitemos, finalmente hacemos clic en Run

Es este caso vemos que todas las sentencias se ejecutaron correctamente.

En la siguiente parte crearemos la aplicación y definiremos el esquema de seguridad.

Analizando la API

La primera tarea antes de hacer cualquier cosa en APEX es entender cómo la API nos devuelve la información que vamos a necesitar. Al revisar la documentación en su sitio web vemos que la API tiene de hecho dos componentes:

• Compendium API: Sirve la información sobre criaturas, equipos, materiales, monstruos y tesoros.

• Regions API: Provee información sobre las ocho regiones geográficas de Hyrule. El Compendium API tiene varios endpoints que devuelven diferentes tipos de datos. Veamos un par de ellos: Get all entries y Get Categories. Comencemos con Get all entries que parece ser el más sencillo dado que no utiliza ningún tipo de parámetro.

Get All Entries

El endpoint vendría siendo: /compendium/all y la forma de hacer la petición al API sería:

GET https://botw-compendium.herokuapp.com/api/v3/compendium/all

Hagamos una petición al endpoint para ver cómo sería la respuesta. En mi caso utilicé Insomnia pero pueden utilizar cualquier cliente para hacer la petición.

En este extracto podemos ver que la respuesta es un JSON que tiene un arreglo con el nombre data que tiene a su vez los objetos con diferentes categorías.

Get Categories

Este endpoint permite obtener la información de los objetos del juego según su categoría, la forma de hacer la petición al API sería la siguiente:

GET https://botw-compendium.herokuapp.com/api/v3/compendium/category/<category>

En este caso sí necesitamos enviar un parámetro en el URL que sería la categoría sobre la cual necesitamos la información. Para hacer una petición en Insomnia utilizaremos una variable que colocaremos en el URL.

Podemos ver que en este caso la respuesta también es un objeto que tiene un arreglo identificada como data que contiene los datos de los materiales para la categoría solicitada.

Veamos ahora como crear estas fuentes de datos REST en APEX.

Creando las fuentes de datos

Lo primero que haremos será crear una nueva aplicación, de momento solo la crearemos con la pantalla de Inicio ya que en un principio necesitamos acceso a los Shared Components. Este proceso lo pueden seguir desde cualquier instancia donde tenga APEX instalado. En mi caso utilizaré la que se encuentra en apex.oracle.com.

Desde la página inicial de APEX haremos clic en Create

Vamos a darle un nombre a la aplicación y hacemos clic en Create Application

Una vez en la aplicación ingresaremos a Shared Components

Un poco más abajo, en Data Sources seleccionaremos REST Data Sources

En esta sección lo que haremos será definir la forma en que APEX va a comunicarse con los servicios REST de los cuales queremos consumir la información. Luego sería posible utilizar estas fuentes para alimentar elementos como Interactive Reports o Interactive Grids.

Creando la fuente para Get All

Si no tenemos alguna otra fuente de datos veremos una pantalla similar a la siguiente:

Simplemente hagamos clic en Create para crear una nueva fuente de datos REST. Nos aparecerá la siguiente pantalla en la cual seleccionaremos From scratch (vamos a crear la fuente desde cero) y luego haremos clic en Next

En la siguiente pantalla veremos que nos solicita información básica sobre la fuente que vamos a crear, colocaremos la siguiente información:

• REST Data Source Type: Simple HTTP

• Name: Hyrule Compendium (o el nombre que ustedes quieran)

• URL Endpoint: https://botw-compendium.herokuapp.com/api/v3/compendium El resto de los campos podemos dejarlos en blanco, luego haremos clic en Next

En la siguiente pantalla se nos mostrará que APEX está creando un Remote Server que será la base desde la que crearemos el resto de las fuentes REST. Este es un paso que solo se realiza una vez. Dejaremos los datos tal como están y haremos clic en Next.

En la siguiente pantalla nos solicitará información sobre la paginación de la fuente, seleccionaremos No Pagination y haremos clic en Next

La siguiente pantalla nos solicitará que le indiquemos cómo se hará la autenticación con la fuente de datos, en este caso este servicio no requiere autenticación, por lo que lo dejamos tal como está y hacemos clic en Advanced.

Dado que el servicio devuelve un JSON que no está construido específicamente para ser leído por APEX, vamos a ayudarlo a entender su estructura mediante un archivo de respuesta de ejemplo. Desde la aplicación que estén utilizando para evaluar el API, exporten la respuesta luego de haber hecho la solicitud a All Entries y guárdenlo en un archivo de texto.

Volviendo a APEX, en la pantalla Parameters modificaremos dos opciones:

• Discovery Sample: Allí cargaremos el archivo que exportamos en el paso anterior

• Row Selector: Le indicaremos la clave dentro del archivo que identifica a la tabla de datos. Recuerden que toda la información está en un arreglo llamado data que a su vez es un arreglo de objetos.

Finalmente hagamos clic en Discover para verificar que puede leer correctamente el API.

En este caso vemos que leyó correctamente el API y fue capaz de identificar el arreglo en el cual se guarda la información. Para finalizar hacemos clic en Create REST Data Source.

Si hacemos clic en el nombre de la fuente podremos ver la información con la que fue creado, así como también tendremos la posibilidad de agregar otras instrucciones REST (como PUT o POST) si el API lo permitiese.

Creando la fuente para Get Category

Vamos ahora a crear la fuente REST para Get Category, este es un poco diferente ya que debemos pasar un parámetro en el URL en el cual le indicamos la categoría que deseamos consultar.

Volvemos a la pantalla donde tenemos la lista de fuentes REST y hacemos clic en Create para crear uno nuevo

En la siguiente pantalla seleccionaremos From scratch y luego hacemos clic en Next hasta llegar a la pantalla donde indicaremos el URL del servicio. Introducimos una descripción y el URL y hacemos clic en Next

Como el servidor remoto fue creado cuando registramos la primera fuente entonces APEX nos mostrará la información existente. Lo dejamos como está y hacemos clic en Next

En la siguiente página nos solicitará la información sobre paginación, hacemos clic en Next sin hacer cambios.

En la siguiente página nos solicitará información sobre el método de autenticación del servicio, lo dejamos desactivado ya que no requiere autenticación y hacemos clic en Advanced.

Esta solicitud es un poco diferente a la anterior ya que requiere que pasemos un parámetro en el URL el cual le indica cuál es la categoría que vamos a consultar. Así que vamos a colocar esa información en la pantalla de parámetros. Al igual que con el caso anterior, vamos a descargar un archivo de respuesta JSON de ejemplo para que APEX pueda crear fácilmente la fuente.

Finalmente hacemos clic en Discover para verificar que la fuente funciona correctamente. Si todo está bien deberíamos ver esta pantalla.

Finalmente hacemos clic en Create REST Data Source.

Ahora podemos utilizar estas fuentes de datos en nuestras aplicaciones en cualquier elemento que permita que la fuente de datos sea un REST Data Source, como por ejemplo un Reporte Interactivo

Recuerden de asegurarse que están pasando los parámetros correctos y obtendrán un reporte como este:

Espero que les sea de utilidad.

En este pequeño tutorial les voy a mostrar cómo configurar ORDS en una instancia APEX en Oracle Cloud Infrastructure (OCI); el proceso es similar si tienen una instancia gratuita de APEX en apex.oracle.com o si tienen su propia instalación de APEX usando ORDS.

Lo primero que haré será instalar una de las aplicación de ejemplo que trae APEX en su galería, en mi caso instalaré la aplicación Customers.

Una vez instalada la aplicación y luego de ingresar al menos una vez para ejecutar el proceso de configuración de la aplicación, verificaremos en SQL Workshop todas las tablas que se crearon. En mi caso le daré una mirada a la tabla EBA_CUST_PRODUCTS.

En esta demostración crearé un servicio web que me permitirá consultar la lista de productos y también haré uno que me muestra el detalle de un producto dado su número de ID.

Procedemos a ir al menú SQL Workshop y seleccionamos RESTful Services. La primera vez que ingresemos nos mostrará una pantalla similar a la siguiente.

Aquí se nos indica que el esquema seleccionado no está registrado en la metadata de ORDS, simplemente debemos hacer clic en Register Schema with ORDS para continuar.

En el cuadro que se nos presenta podemos dejar los valores por defecto ya que esto es solo una prueba, sin embargo en sus ambientes de producción:

• Oracle recomienda cambiar el nombre del alias del schema para disminuir la posiblidad de que un atacante pueda determinar el nombre del usuario en la base de datos.

• Todas las opciones que permitan activar métodos de autorización deberían estar encendidos.

Presionamos Save Schema Attributes para guardar los cambios, inmediatamente se nos mostrará una pantalla similar a la siguiente.

El siguiente paso es crear un module, que no es más que un contenedor utilizado para agrupar diferentes servicios RESTful y que ademas sirve para definir la ruta base en el URL para acceder al servicio web.

En la imagen anterior vemos los componentes del URL para invocar el servicio web, la ruta base vendría después del alias del schema.

Procedamos entonces a ubicarnos en el árbol de la izquierda sobre la rama Modules y nos mostrará la siguiente pantalla.

Hagamos clic en el botón Create Module y nos solicitará los datos para la creación del módulo.

En este caso llamaremos al módulo "clientes" y su ruta base también será "clientes". Dejamos el resto de los campos con sus valores por defect y presionamos el botón Create Module. Al finalizar nos mostrará una pantalla como la siguente.

Ya podemos ver cómo queda el URL, pero aun faltan un par de pasos más.

El siguiente paso es la creación de un template, el cual define un servicio individual que puede ser llamado. Cada uno de estos templates luego tendrá definido uno más handlers, que serán los que manejarán cada una de las peticiones según el verbo HTTP utilizado.

Un poco más abajo en la pantalla de definición del módulo encontraremos la sección para definir el template.

En esta sección haremos clic en Create Template y nos mostrará una pantalla como la siguiente.

Dado que mi servicio web accederá a la tabla de productos entonces así llamaré al URI del template (atención con la barra invertida al final). Terminamos la creación del template haciendo clic en el botón Create Template.

Finalmente tenemos el URL completo para obtener la lista de productos, solo falta indicar la sentencia SQL que se ejecutará cuando hagamos un GET al URL, para esto crearemos un handler. Un poco más abajo en la misma pantalla encontraremos otra sección llamada Resource Handlers y haremos clic en Create Handler.

Se nos mostrará una nueva pantalla donde indicaremos las características. Dejaremos todos los campos por defecto y escribiremos la siguiente sentencia de búsqueda en la sección Source:

SELECT * FROM EBA_CUST_PRODUCTS

En este caso dejaremos la opción Source Type en Collection Query, ya que queremos devolver un conjunto de filas en formato JSON. Finalizamos presionando el botón Create Handler.

Una vez creado el handler, ya podemos empezar a probar el servicio web. Podemos usar cualquier navegador o aplicaciones especializadas como Postman (lo cual es lo recomendado, ya que no podremos hacer POST con el navegador fácilmente en caso de requerirlo)

En este caso nos devuelve un JSON que tiene una lista llamada "items" con un objeto que representa cada fila de la tabla.

Vemos ahora cómo crear un template para obtener los datos de un solo producto, enviando el ID del producto como parte del URI.

Hacemos clic sobre el módulo clientes y luego hacemos clic en el botón Create Template.

En este caso el URI varía un poco, ya que agregamos una variable de acoplamiento (o bind variable) que será sustituida por el ID del producto. Hacemos clic en Create Template para guardar.

Vean como el URL es ligeramente diferente, agregando el ID al final (en este caso no fue necesaria la barra invertida). Ahora crearemos un handler para manejar las solicitudes GET a este URL. Más abajo en esta misma pantalla haremos clic en Create Handler.

En este caso sí cambiaremos Source Type a la opción Collection Query Item, ya que solo recuperaremos un registro, y en la sección Source escribiremos la siguiente sentencia SQL:

SELECT * FROM EBA_CUST_PRODUCTS WHERE ID = :id

Finalizaremos presionando el botón Create Handler y procederemos a probar nuestro servicio web.

En este caso el servicio nos devuelve solo un objeto con todos los detalles del mismo. Por supuesto las sentencias SQL utilizadas pueden ser tan complejas como sea necesario para extraer la información necesaria, además de que es posible crear sentecias SQL que hagan UPDATE (usando PUT), INSERT (usando POST) y DELETE (usando DELETE)

Jasper Reports Integration 2.7

Permite la integración de APEX con el motor de reportes Jasper. La versión más reciente de JRI se encuentra aquí y las instrucciones para la instalación están aquí

Como usuario root creamos un nuevo directorio para almacenar los binarions de las aplicacion

mkdir -p /u01/JasperReportsIntegration
chown tomcat:tomcat /u01/JasperReportsIntegration/

Usarmos el comando tar para extraer el contenido del archivo que descargamos y lo copiamos al directorio

tar xvf jri-2.7.0-jasper-6.16.0.tar
cp -R jri-2.7.0-jasper-6.16.0/* /u01/JasperReportsIntegration/

Agregramos al archivo .bash_profile del usuario tomcat

export OC_JASPER_CONFIG_HOME=/u01/JasperReportsIntegration

Cerramos sesión del usuario tomcat, volvemos a iniciarla y reiniciamos el servicio.

Modificamos el archivo /u01/JasperReportsIntegration/conf/application.properties para indicar los parámetros de conexión a la base de datos. Buscamos la sección [datasource:default] y modificamos los campos necesarios

[datasource:default]
type=jdbc
name=default
url=jdbc:oracle:thin:@//orcl-server:1521/XEPDB1
username=testing
password=Password01

Finalmente copiamos el archivo /u01/JasperReportsIntegration/webapps/jri.war en el directorio webapps de Tomcat

cp jri.war $CATALINA_BASE/webapps/.

El despliege de la aplicación debería hacerse de forma automática y a partir de este momento debería ser posible ingresar a la página de inicio en http://ip-servidor:8080/jri

El siguiente paso es instalar los objetos de base de datos, este proceso se divide en dos, una parte se ejecuta con el usuario SYS y el otro con el usuario dueño de la aplicación.

Descomprimimos el archivo que descargamos en algún sitio que sea accesible por el usuario oracle e ingresamos al directorio sql. Allí ingresamos a la base de datos usando SQL*Plus

sqlplus sys@localhost:1521/XEPDB1 as sysdba

Ejecutamos los siguientes comandos (en este caso testing es el esquema de base de datos dueño de la aplicación, deberá cambiarse por el nombre de esquema correcto en producción)

@sys_install testing
@sys_install_acl_12_and_above.sql testing orcl-server

Luego iniciamos una nueva conexión a la base de datos, esta vez con el usuario dueño de la aplicación.

sqlplus testing@localhost:1521/XEPDB1

Y ejecutamos

@user_install.sql

En una próxima publicación les mostraré cómo crear reportes PDF con JasperReports y APEX

Oracle XE 21c

La guía para realizar esta instalación se puede encontrar aquí. También sugiero la lectura de este artículo

La primera tarea es descargar el archivo RPM de instalación de XE desde aquí y colocar el archivo descargado en la carpeta home del usuario root. Allí procedemos a ejecutar el siguiente comando para realizar la instalación (este proceso se debe ejecutar como usuario root)

dnf -y localinstall oracle-database-xe-21c-1.0-1.ol8.x86_64.rpm

El proceso de instalación creará de manera automática el usuario y grupos así como hará las adecuaciones necesarias a los parámetros del kernel.

Una vez terminado el proceso de instalación y continuando como el usuario root ejecutamos el siguiente comando

/etc/init.d/oracle-xe-21c configure

Se solicitarán las contraseñas para los usuarios SYS, SYSTEM y PDBADMIN. Una vez completada la instalación es posible bajar/subir la base de datos y el listener con los siguientes comandos (como root):

/etc/init.d/oracle-xe-21c start
/etc/init.d/oracle-xe-21c stop

Oracle APEX 21.1

La guía oficial para la instalación de APEX se puede encontrar aquí sin embargo preferimos usar la versión resumida que se encuentra aquí.

Creamos un nuevo tablespace para almacenar los objetos de APEX

CREATE TABLESPACE apex DATAFILE '/opt/oracle/oradata/XE/XEPDB1/apex01.dbf' SIZE 100M AUTOEXTEND ON NEXT 1M;

Luego procedemos con la instalación, ingresamos al directorio en el servidor donde descargamos y descomprimimos el software de APEX. Iniciamos sesión con el usuario oracle que fue creado durante la instalación de XE.

Una vez allí nos conectamos a la base de datos usando SQL*Plus con el usuario SYS y ejecutamos el script de instalacion en el contenedor XEPDB1

cd /home/oracle/apex
sqlplus sys@localhost:1521/XEPDB1 as sysdba

(en este caso tuve que usar la sintaxis Easy Connect porque tengo otra BD en el servidor y SQL*Plus trataba de conectarse a esa, en otras circunstancias debería ser tan simple como ejecutar sqlplus / as sysdba)

ALTER SESSION SET CONTAINER=XEPDB1;
@apexins.sql APEX APEX TEMP /i/

Una vez completada la instalación cerramos la sesión de SQL*Plus y volvemos a ingresar con SYS para ejecutar unos comandos finales. Recomiendo cerrar SQL*Plus al ejecutar cada comando y volver a ingresar, ya que cada script hace cambios en la configuración de la aplicación que podrían afectar la ejecución de los scripts.

Cambiar la contraseña del usuario ADMIN de APEX (la contraseña debe tener caracteres especiales o fallará la creación)

ALTER SESSION SET CONTAINER=XEPDB1;
@apexchpwd.sql

Crear los usuarios APEX_LISTENER y APEX_REST_PUBLIC_USER

ALTER SESSION SET CONTAINER=XEPDB1;
@apex_rest_config.sql

ORDS

Para la instalación de ORDS tomaremos como base los pasos de esta guía. Descargaremos la última versión de ORDS desde este enlace.

Antes de iniciar la instalación nos conectaremos a base de datos para asegurar que los usuarios de conexión de ORDS están desbloqueados y que conocemos sus contraseñas.

ALTER SESSION SET CONTAINER = XEPDB1;
ALTER USER APEX_LISTENER IDENTIFIED BY Password01 ACCOUNT UNLOCK;
ALTER USER APEX_PUBLIC_USER IDENTIFIED BY Password01 ACCOUNT UNLOCK;
ALTER USER APEX_REST_PUBLIC_USER IDENTIFIED BY Password01 ACCOUNT UNLOCK;

Iniciamos sesión con el usuario tomcat y ejecutamos los siguientes comandos para crear el directorio y descomprimir el archivo que descargamos

mkdir /u01/ords
cd /u01/ords
unzip ords-latest.zip
mkdir -p /u01/ords/conf

Crearemos un directorio para almacenar la configuración de ORDS

mkdir -p /u01/ords/conf

Editaremos el archivo /u01/ords/params/ords_params.properties para indicar los parametros de la instalación

db.hostname=orcl-server.localdomain
db.port=1521
db.servicename=XEPDB1
db.sid=
db.username=APEX_PUBLIC_USER
db.password=Password1
migrate.apex.rest=false
plsql.gateway.add=true
rest.services.apex.add=true
rest.services.ords.add=true
schema.tablespace.default=APEX
schema.tablespace.temp=TEMP
standalone.mode=false
user.tablespace.default=APEX
user.tablespace.temp=TEMP
user.apex.listener.password=Password1
user.apex.restpublic.password=Password1
user.public.password=Password1
sys.user=SYS
sys.password=Password
restEnabledSql.active=true
feature.sdw=true
database.api.enabled=true

Indicamos la ubicación del directorio de configuración

$JAVA_HOME/bin/java -jar ords.war configdir /u01/ords/conf/

Iniciamos el proceso de instalación:

$JAVA_HOME/bin/java -jar ords.war

Realizamos el despliegue al servidor Tomcat

mkdir $CATALINA_BASE/webapps/i/
cp -R /tmp/apex/images/* $CATALINA_BASE/webapps/i/
cd /u01/ords
cp ords.war $CATALINA_BASE/webapps/

Iniciamos el servicio Tomcat en caso que este detenido. Si todo está bien deberíamos poder ingresar a APEX en http://ip-servidor:8080/ords.

En la próxima publicación culminaremos con la instalación de la integración con JasperReports.

Apache Tomcat 9

Tomcat será el servidor de aplicaciones sobre el que desplegaremos ORDS. Para la instalación de Tomcat usaremos como base los pasos indicados aquí

Debemos descargar dos componentes:

• OpenJDK 17
• Apache Tomcat 9

Como usuario root crearemos el usuario tomcat y el directorio donde se instalará el software.

useradd tomcat
mkdir -p /u01
chown tomcat:tomcat /u01

Instalaremos OpenJDK en el directorio /u01/java

su - tomcat
mkdir -p /u01/java
cd /u01/java
tar xzf openjdk-17_linux-x64_bin.tar.gz
ln -s jdk-17 latest

Procederemos a instalar Tomcat en el directorio /u01/tomcat

mkdir -p /u01/tomcat
cd /u01/tomcat
tar xzf apache-tomcat-9.0.54.tar.gz
ln -s apache-tomcat-9.0.54 latest

Siguiendo las recomendaciones del artículo, procederemos a separar los binarios de Tomcat de la configuración para que los futuros procesos de actualización sean más simples. Para esto crearemos un nuevo directorio que servirá como ubicación para CATALINA_BASE y en este copiaremos los archivos relevantes.

mkdir -p /u01/config/instance
cp -r /u01/tomcat/latest/conf /u01/config/instance
cp -r /u01/tomcat/latest/logs /u01/config/instance
cp -r /u01/tomcat/latest/temp /u01/config/instance
cp -r /u01/tomcat/latest/webapps /u01/config/instance
cp -r /u01/tomcat/latest/work /u01/config/instace

Agregaremos las siguientes líneas al archivo /home/tomcat/.bash_profile

export JAVA_HOME=/u01/java/latest
export CATALINA_HOME=/u01/tomcat/latest
export CATALINA_BASE=/u01/config/instance

Cerramos la sesión del usuario tomcat y la volvemos a iniciar para que tome los cambios en este archivo. Luego de esto ya podemos iniciar/detener Tomcat con los siguientes comandos (habiendo iniciado sesión con el usuario tomcat):

$CATALINA_HOME/bin/startup.sh
$CATALINA_HOME/bin/shutdown.sh

Si todo finalizó de manera correcta podemos ingresar al portal de Tomcat en http://ip-servidor:8080/.

En la próxima parte haremos la instalación de la base de datos.

En esta serie de publicaciones les mostraré mi experiencia instalando un servidor desde cero con las siguientes características:

• Oracle Linux 8
• Apache Tomcat 9
• Oracle XE 21c
• ORDS 21.3
• JasperReports Integration 2.7

Comencemos con la instalación del sistema operativo

Oracle Linux 8

La primera tarea es instalar el sistema operativo en el equipo. Para asegurar la máxima compatibilidad con la base de datos y el resto de los componentes procederemos a instalar Oracle Linux 8, el cual se puede descargar desde aquí. En esta página seleccionaremos la última versión disponible de Boot ISO (esta es una versión más pequeña, el resto de los paquetes se descargaran en el momento de la instalación).

Una vez que tengamos el archivo ISO procedemos a usar una herramienta como Rufus (si estamos en Windows) para crear un USB booteable. Ingresamos el USB en el computador donde instalaremos el sistema operativo y al momento de arrancar le indicaremos al computador que haga el arranque desde el USB, esto iniciará el proceso de instalación de Oracle Linux.

A partir de este momento podemos seguir la guía de instalación en modo gráfico para hacer la instalación. Hay que poner especial cuidado en la sección 3.1.3 donde se explica como configurar los repositorios desde los cuales se descargarán los paquetes del sistema operativo.

Sobre la configuración de red: Por defecto la interface de red está deshabilitada, se debe habilitar manualmente para que pueda conectarse a los repositorios.

Sobre la particiones del disco duro: Por defecto la instalación del sistema operativo crea un filesystem en root y un /home que puede ocupar todo el disco. Es importante revisar esta configuración para asegurar que /home no sea tan grande y que se deje suficiente espacio para /opt que es donde se instala XE y se crean por defecto sus archivos de datos. Aunque no es obligatorio, sugiero dejar /opt como un punto de montura fuera de root para que sea más fácil de manipular en caso de ser necesario. Por supuesto tota la instalación se debe hacer sobre LVM.

Sobre la selección de software: Sugiero que se seleccione la opción Server (sin GUI) ya que no se requiere una interface gráfica para la instalación y administración de la base de datos.

Sobre los usuarios iniciales: Es obligatorio asignar una contraseña al usuario root, se sugiere que sea una contraseña fuerte. Además se sugiere crear otro usuario diferente a root que tenga privilegios de administración (que pueda usar sudo)

Tareas posteriores a la instalación

Es necesario hacer algunas configuraciones a nivel de red para asegurar que las conexiones se realizan de manera correcta. Para esto utilizaremos la aplicación nmtui conectados con el usuario root.

Al ingresar a la aplicación realizaremos los siguientes pasos:

• Seleccionar la opción Edit a connection
• Seleccionar la interface asociada a la tarjeta de red (por lo general eth1 o eno1)
• En la sección IPv4 Configuration seleccionaremos la opción Manual y asignaremos una dirección IP fija dentro del rango de la red, recuerde que también debe indicar la máscara de red (por lo general es /24 en redes pequeñas), la colocaremos en el campo Addresses
• En el campo Gateway colocaremos la IP de la pueta de enlace, por lo general es la IP del modem/router dado por el proveedor de internet.
• En el campo DNS servers colocaremos las direcciones IP de los servidores DNS, por lo general son asignados por el proveedor de internet. También es posible utilizar servidores DNS externos como los de Google o Cloudflare.
• Dejamos el resto de los campos con sus valores por defecto y bajamos hasta el final de la pantalla y presionamos OK.
• Presionamos el botón Back para volver a la pantalla inicial.
• Seleccionamos la opción Set system hostname.
• Asignamos un nombre al servidor, sugiero algo como orcl-server.localdomain (en caso que la red del cliente no tenga un dominio creado).
• Presionamos el botón OK
• Presionamos el botón Quit
• Reiniciar el equipo para aplicar los cambios.

En la próxima publicación veremos cómo hacer la instalación de Tomcat 9

Ahora nos presenta tres opciones para descargar:

• Samples (Ejemplos): Nos muestran las funcionalidades más interesantes de APEX en aplicaciones específicas para cada una.
• Plug-ins: Nos permiten extender la funcionalidad de Oracle APEX.
• Apps: Son aplicaciones completamente funcionales para diferentes tipos de casos de uso (manejo de clientes, calendarios, encuestas, etc) y que podemos personalizar según nuestras necesidades.

En esta oportunidad vamos a instalar una aplicación de ejemplo, para ello haremos clic en Samples, lo que nos llevará a la página con el listado de aplicaciones de ejemplo.

Vamos a descargar la aplicación Sample Charts, que nos muestra algunos ejemplos de las gráficas que es posible construir en Oracle APEX. Haciendo clic en el enlace nos llevará a la página de GitHub donde se hospeda la aplicación.

Importante: Verifiquen que están en la rama apropiada del repositorio según la versión de Oracle APEX que tengan instalada, esta la encontarán en la esquina superior izquierda sobre la lista de archivos. Para descargar la aplicación hagan clic sobre el archivo con extensión zip y en la siguiente pantalla hagan clic en Download y finalmente seleccionen una carpeta en su equipo para guardar el archivo.

Ya con el archivo en nuestro equipo volveremos a la página principal de APEX, en la sección App Builder seleccionaremos Import

En la siguiente pantalla se nos pedirá que subamos el archivo de la aplicación. Podemos arrastrarla desde la carpeta o hacer clic sobre la sección Drag and Drop y luego seleccionar el archivo. Dejamos el resto de las opciones con sus valores por defecto y presionamos el botón Next.

En la siguiente pantalla se solicitará la confirmación de la tarea de importación. Hagan clic en Next

APEX les solicitará entonces la información sobre la aplicación que desean instalar, dejen los valores por defecto a menos que tengan una buena razón para cambiar alguno, y hagan clic en Install Application.

La siguiente pantalla les pedirá indicar si desean instalar los objetos de soporte, estos son los objetos de base de datos que tienen los datos que serán presentando por la aplicación. Mantengan las opciones por defecto y hagan clic en Next.

Finalmente verán una pantalla de confirmación, hagan clic en Install.

Importante: Si están haciendo uso de la versión Always Free de Oracle Cloud asegurense que el usuario de base de datos dueño del workspace tenga privilegios para usar el tablespace DATA.

Si todo está bien se mostará una nueva pantalla donde se indica que la instalación fue exitosa. Hagan clic en Run Application para ejecutar la aplicación.

Posiblemente les solicite el usuario y contraseña para acceder al workspace, luego de eso podrán ver la aplicación totalmente funcional.

Pueden repetir estos pasos para instalar las otras aplicaciones de ejemplo, las mismas quedarán instaladas en su workspace y podrán editarlas desde el App Builder

Oracle Application Express

O simplemente APEX, es una plataforma de desarrollo de código bajo (low-code) desarrollada por Oracle para interactuar directamente con la base de datos, y que además permite crear aplicaciones completas en muy poco tiempo. Es una plataforma donde casi todo el desarrollo se realiza de forma declarativa (cambiando propiedades a los elementos de la aplicación) con una interface muy intuitiva, y que a su vez permite hacer personalizaciones más avanzadas ya sea mediante PL/SQL o JavaScript.

Hay diversas formas de empezar a trabajar con APEX:

• Instalación de APEX en la base de datos de tu compañía (on-premise)
• Solicitar un espacio de trabajo gratuito en apex.oracle.com
• Crear una cuenta en la capa gratuita de Oracle Cloud
• Instalar una VM con todo lo necesario para trabajar de manera local

Cada una de estas opciones tiene sus ventajas y características. En este artículo veremos la última opción, trabajar de manera local.

Preparar los archivos

En esta oportunidad asumiré que ya tienen instalado Virtualbox y Vagrant en sus equipos y que ya descargaron o clonaron el repositorio de los scripts preparados por Oracle. Nuevamente el ejemplo lo haremos sobre un equipo anfitrión con Ubuntu 20.04, sin embargo estas instrucciones deberían funcionar igual en otros sistemas operativos.

Lo primero es conseguir desde la página web de Oracle los instaladores de cada uno de los componentes (esto deben hacerlo solo una vez):

• Archivo rpm para la instalación de Oracle XE: https://www.oracle.com/technetwork/database/database-technologies/express-edition/downloads/index.html
• Oracle APEX: https://www.oracle.com/tools/downloads/apex-downloads.html
• Oracle Rest Data Services (ORDS): https://www.oracle.com/database/technologies/appdev/rest-data-services-downloads.html

ORDS, por si no lo han visto antes, crea un puente entre HTTP y tu base de datos, te permite crear REST API endpoints sobre los que puedes crear solicitudes en tus aplicaciones y extraer o procesar información de la base de datos.

Al finalizar la descarga deben colocar todos los archivos en vagrant-projects/OracleAPEX.

Una vez que los archivos estén en su sitio, solo deben ejecutar el comando vagrant up.

El proceso de instalación puede tardar un buen rato dependiendo de su conexión a internet, la capacidad del equipo, etc.

Una vez terminado el proceso de instalación, tomen nota de la información de conexión, recuerden que las contraseñas son autogeneradas pero se pueden cambiar luego de terminar el proceso.

Abran su navegador de preferencia y vayan a la URL indicada en el instalador, por lo general será http://localhost:8080/ords

Si todo está bien, deberían ver la página inicial de APEX en su equipo. La primera vez, dado que aun no han creado un espacio de trabajo, deben ingresar la siguiente información:

• Workspace: internal
• Username: admin
• Password: la contraseña generada por el instalador

La primera vez que ingresen les pedirá que cambien la contraseña, asegúrense que sea una contraseña segura con al menos una mayúscula, números y un signo de puntuación. Una vez que hagan el cambio los llevará a la pantalla de bienvenida para crear su primer espacio de trabajo.

En APEX un espacio de trabajo es un compartimento lógico, una especie de base de datos privada que permite a los desarrolladores trabajar con una misma aplicación de APEX manteniendo privados sus propios objetos, datos y aplicaciones. El primer espacio de trabajo creado por defecto se llama internal, es un espacio de trabajo especial donde no se pueden crear aplicaciones ya que es el sitio de administración de APEX.

Pudieran crear un espacio de trabajo por usuario, o por proyecto, eso dependerá totalmente de sus necesidades.

Hagan clic en Create Workspace, esto los llevará a la pantalla donde deben indicar los datos básicos del espacio de trabajo.

En mi caso simplemente voy a crear un espacio de trabajo llamado testing. Presionen Next para continuar a la siguiente pantalla.

Un espacio de trabajo está asociado a un esquema de la base de datos. Pueden reutilizar un esquema ya existente (seleccionando Yes en Re-use existing schema?) o pueden crear un nuevo esquema y en esta pantalla colocaran los datos del mismo. En mi caso particular crearé un esquema con el mismo nombre del espacio de trabajo (recuerden que el nombre del esquema debe seguir las reglas de nombres de cualquier esquema/usuario que creen en la base de datos). Al introducir todos los datos presionen Next para continuar a la siguiente pantalla.

Luego deben dar los datos del administrador del espacio de trabajo. En el campo Username coloquen el nombre de usuario que usaran para conectarse como administrador (por lo general es admin pero pueden poner lo que quieran), una contraseña, nombre, apellido y dirección de correo electrónico.

La pantalla final les mostrará un resumen de los datos que colocaron para crear el espacio de trabajo, simplemente hagan clic en Create Workspace para finalizar.

Luego de un pequeño instante les mostrará la confirmación de la creación del espacio de trabajo, junto con la información sobre las estructuras de almacenamiento del usuario recién creado.

Al presionar el botón Done los llevará a la página de administración de los espacios de trabajo. Ya pueden cerrar esta sesión para ingresar al espacio de trabajo recién creado. Simplemente hagan clic en la parte superior derecha, donde aparece el nombre del usuario y en el menú emergente hagan clic en Sign out. Al salir, hagan clic en el botón verde para volver a la pantalla de inicio y ahora coloquen la información que usaron para crear su propio espacio de trabajo.

Es muy probable que la primera vez que ingresen les solicite que cambien la contraseña.

¡Y ya está! Finalmente están en un espacio de trabajo en blanco donde pueden empezar a crear aplicaciones desde cero. Si lo desean pueden ingresar a App Gallery para ver aplicaciones de demostración totalmente funcionales y que pueden servirles de base para sus propios proyectos.

He visto muchos blogs en español en los que explican cómo realizar la instalación de Oracle XE 18c en diversos sistemas operativos y todos ellos asumen que la instalación se realizará directamente sobre tu equipo de trabajo. Aunque esto no está mal, mi experiencia me ha enseñado que no es una buena idea instalar XE directamente en el sistema operativo de tu computador principal: las configuraciones del equipo pueden cambiar a medida que vas instalando nuevas aplicaciones y/o servicios, haciendo que tu instalación de XE se pueda volver inestable (o de hecho todo tu sistema operativo, sobre todo en las instalaciones en Windows).

El proceso que voy a explicarles es muy similar a usar virtualenv en Python para crear ambientes virtuales para las librerías que utilizarás en tus aplicaciones, o a la creación de contenedores con Docker para crear máquinas de desarrollo completas. De esta forma tienen un ambiente dedicado exclusivamente al servicio con el que desean trabajar.

Vagrant para aliviar el proceso

No es necesario reinventar la rueda. Por lo general los tutoriales en español nos guían por el proceso completo de configuración del sistema operativo donde instalaremos la base de datos, incluyendo la instalación de paquetes, apertura de puertos, etc. Sin embargo ya Oracle ha publicado scripts que pueden aliviar la tarea.

Vagrant es una herramienta para construir y administrar máquinas virtuales. Básicamente nos permite utilizar scripts con una configuración predefinida para la creación de una máquina virtual. La ventaja principal es que es posible usar estos scripts para crear tantas máquinas virtuales como necesites y todas ellas tendrán la misma configuración.

En este procedimiento utilizaremos VirtualBox para administrar la máquina virtual de Oracle XE, si aun no tienen instalado VirtualBox pueden seguir las instrucciones de instalación para su sistema operativo. Además, también debe instalar Vagrant siguiendo estas instrucciones.

Iniciar la instalación

Una vez que VirtualBox y Vagrant están instalados procederemos a descargar los scripts de Oracle que se encuentran en este repositorio en GitHub. Pueden clonarlo o descargarlo totalmente y luego descomprimir el archivo en un directorio local de su preferencia.

En este ejemplo usaré un equipo con Ubuntu 20.04 como anfitrión, aunque las instrucciones son las mismas para cualquier sistema operativo.

En mi caso hice una clonación del repositorio, en la imagen anterior se ve el contenido del directorio.

Antes de iniciar la creación de la máquina virtual, es importante hacer notar que si es la primera vez que estamos ejecutando Vagrant en nuestro equipo es recomendable tener una buena conexión a internet, ya que el script descargará tanto la imagen del sistema operativo (Oracle Linux 7) y el instalador de la base de datos XE.

Para iniciar la creación de la máquina virtual de Oracle XE 18c procederemos al directorio vagrant-projects/OracleDatabase/18.4.0-XE y ejecutaremos el comando vagrant up.

El proceso de instalación se encargará de:

• Descargar e instalar el sistema operativo (Oracle Linux 7)
• Descargar e instalar las dependencias necesarias para la instalación de Oracle XE 18c.
• Descargar e instalar Oracle XE 18c.
• Configurar el redireccionamiento IP necesario para poder comunicarse con la VM desde el equipo anfitrión.

El proceso de instalación puede tomar varios minutos dependiendo del ancho de banda de su conexión y/o de la potencia de su equipo; en la consola verán el progreso de la misma.

Al finalizar el proceso tomen nota del usuario y contraseña de los usuarios sys, system y pdbadmin que aparecerán en la consola. (Si no pudieron tomar nota tampoco hay que entrar en pánico, es muy sencillo cambiar estas contraseñas y lo explicaré un poco más abajo)

¡Y eso es todo! Ya tienen una base de datos Oracle XE 18c funcional en su equipo. Para configurar un cliente como SQL Developer utilicen los siguientes datos:

• Hostname: localhost
• Port: 1521
• SID: XE
• PDB: XEPDB1
• Usen las contraseñas generadas automáticamente

Si prefieren cambiar la contraseña pueden ingresar a la máquina usando el comando vagrant ssh estando en el mismo directorio desde el que ejecutaron vagrant up.

Una vez hayan ingresado a la máquina virtual ejecuten estos comandos:

sudo su - oracle

/home/oracle/setPassword.sh <nuevoPassword>

Donde <nuevoPassword> es la nueva contraseña que quieren utilizar. Recuerden que es posible que la base de datos exija que la contraseña cumpla con ciertos parámetros de complejidad.