API de BirtUM

Con el objetivo de mantener actualizada la herramienta de generación de informes BirtUM, se ha confeccionado una nueva implementación que ofrece endpoints REST y SOAP y una versión actualizada del motor de generación de informes.

Su documentación de OpenAPI/Swagger para la API REST se encuentra disponible desde este enlace: OpenAPI birtum-api.

Y el WSDL para la API SOAP (deprecada y se recomienda utilizar la versión REST) se encuentra en: WSDL birtum-api.

Cliente para la API REST

Para facilitar su uso y abstraernos de la capa REST, se ha implementado también un cliente que es totalmente compatible con aplicaciones FundeWeb 1, FundeWeb 2 y FundeWebJS.

Contenido de la librería

DTOs: SolicitudInformeBirtum y SolicitudInformeBirtumConLibreria

Son los DTOs que se utilizan para construir el mensaje de la petición a BirtUM. La clase SolicitudInformeBirtumConLibreria extiende de la clase SolicitudInformeBirtum, y los campos que contienen son:

• aplicacion (String): Nombre de la aplicación desde la que se está realizando la solicitud.
• formato (String): Formato del archivo del informe a generar ('pdf', 'xls', 'html' o 'doc').
• usuario (String): Correo electrónico o nombre del usuario que está realizando la solicitud.
• plantillaInforme (byte[]): Fichero de información en XML representado en bytes de la estructura del informe que se quiere generar. El cliente será el encargado de convertirlo a base64 para su correcta transmisión.
• datosInforme (byte[]): Fichero de datos en XML que se utilizaran para rellenar el informe. El cliente será el encargado de convertirlo a base64 para su correcta transmisión.
• parametros (Map<String, Object>) (opcional): Lista de parámetros del informe que se le pueden pasar a BirtUM.
• libreria (byte[]) (pertenece a la clase SolicitudInformeBirtumConLibreria): Fichero de la librería en XML con la que generar el informe. El cliente será el encargado de convertirlo a base64 para su correcta transmisión.

Se encuentran ubicados en el paquete: "es.um.atica.birtum.client.dtos".

ExcepcionClienteBirtum

Es la excepción lanzada por el cliente de BirtUM cuando se produce algún problema de petición mal formada o al comunicarse con la API .

Está ubicada en el paquete: "es.um.atica.birtum.client.exceptions".

ClienteBirtum

Es la clase que ofrece la lógica para comunicarse con la API de BirtUM. Para poder hacer uso de ella será necesario obtener una instancia mediante la clase builder ClienteBirtumBuilder. En ella se dispone de 3 funciones para atender a cada una de las posibles peticiones ofrecidas por la API.

• byte[] generaInformeDesdeXML( SolicitudInformeBirtum solicitudInforme ) throws ExcepcionClienteBirtum: Es la función principal con la que se mandará una petición a la API para generar un informe. Será necesario proporcionarle uno de los dos DTOs con los datos del informe para su generación, y devolverá el fichero como array de bytes.
• String generaInformeAsyncDesdeXML(  SolicitudInformeBirtum solicitudInforme ) throws ExcepcionClienteBirtum: Esta función está enfocada en la generación de informes de mayor complejidad o peso. Se registrará la solicitud de generación en la API y se devolverá un identificador de tipo String que luego podrá ser utilizado para solicitar el informe generado.
• byte[] obtenerInformePorID( String idRegistroInforme ) throws ExcepcionClienteBirtum: Con el identificador obtenido de la función generaInformeAsyncDesdeXML se podrá llamar a esta función y recuperar un informe solicitado de manera asíncrona. De la misma manera que con la función síncrona, se obtendrá el fichero generado como array de bytes.

El cliente se encuentra en el paquete: "es.um.atica.birtum.client.interfaces".

ClienteBirtumBuilder

Builder con el que obtener una instancia de ClienteBirtum.

El builder está ubicado en el paquete: "es.um.atica.birtum.client.impl".

Importación y uso

Para utilizar este cliente, tendremos que añadir en el pom.xml de nuestro proyecto la siguiente dependencia en el POM principal:

<dependency>
	<groupId>es.um.atica.birtum</groupId>
	<artifactId>birtum-client</artifactId>
	<version>1.0.0</version>
</dependency>

En el POM del modulo WEB (aplicaciones FundeWeb v2.0, usar el modulo EJB en aplicaciones FundeWeb v1.5) añadimos al final de las dependencias (</dependencies>):

<dependency>
	<groupId>es.um.atica.birtum</groupId>
	<artifactId>birtum-client</artifactId>
</dependency>

también añadimos el plugin

	<plugin>
		<groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-dependency-plugin</artifactId>
		<executions>
			<execution>
				<id>unpack</id>
				<phase>prepare-package</phase>
				<goals>
					<goal>unpack-dependencies</goal>
				</goals>
				<configuration>
					<includeGroupIds>es.um.atica.birtum</includeGroupIds>
					<includeArtifactIds>birtum-client</includeArtifactIds>
					<excludes>
						META-INF/**,
						META-INF/
					</excludes>
					<outputDirectory>${project.build.directory}/classes</outputDirectory>
				</configuration>
			</execution>
		</executions>
	</plugin>

También añadimos el perfil (sino esta ya añadido) :

<profiles> 


    <profile>
        <id>local</id>

        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>

        <properties>
            <mdep.skip>true</mdep.skip>
        </properties>
    </profile>

    ...

</profiles>  

Y en la parte del código en que queramos hacer uso de la librería haremos lo siguiente:

• Crearemos una nueva instancia de SolicitudInformeBirtum o SolicitudInformeBirtumConLibreria con los datos de nuestro informe.
• Obtendremos una instancia del cliente:
  

  ClienteBirtum clienteBirtum = ClienteBirtumBuilder.builder().host( [birtumHost] ).build();

  Donde [birtumHost] será un String que especificará el host dónde se encuentra alojada la API que queremos utilizar. En el próximo apartado lo parametrizaremos en función del entorno, y los posibles valores para este String son:

  • Entorno de desarrollo: "https://apidesa.um.es"
  • Entorno de test/preproducción: "https://apitest.um.es"
  • Entorno de producción: "https://api.um.es"
• Utilizaremos la función del cliente que requiramos. Principalmente será "generaInformeDesdeXML()".

Parametrización del host de la API

En función del tipo de aplicación sobre la que estemos trabajando y el entorno en que nos encontremos, será necesario utilizar un host u otro para hacer uso de la API de BirtUM.

FundeWeb 1 y FundeWeb 2

Se debe añadir en los filtros de los distintos entornos ubicados en el proyecto web (filtro-local.properties, filtro-desarrollo.properties, filtro-preproduccion.properties y filtro-produccion.properties), la variable "birtum_host". En local, para poder trabajar con ella, se debe indicar el host correspondiente (URL de desarrollo o test) tal y como se refleja en el apartado de "Importación y uso".

En los entornos de desarrollo, preproducción y producción, lo parametrizaremos desde GitLab con el objetivo de que se inyecte al lanzarse la pipeline. En la configuración de GitLab de CI/CD de nuestro proyecto añadiremos las variables birtum_host_DESA, birtum_host_TEST y birtum_host_PROD de la siguiente manera:

Si en desarrollo se quiere hacer uso de una versión más estable de BirtUM se indicará la URL de https://apitest.um.es, y si por el contrario se quiere probar la última funcionalidad (con posibles fallos) se indicará https://apidesa.um.es.

Para que la pipeline lo inyecte tendremos que añadir esta variable a la lista de variables LISTA_SECRETS. Es otra variable que puede estar ya creada para nuestro proyecto en GitLab o no. Las variables de esta lista se separarán con un espacio.

Este valor lo leeremos desde el fichero components.properties, lo que nos permitirá luego utilizarlo en los beans de nuestra aplicación. Lo haremos tal y como se muestra en la siguiente imagen:

En el bean en que queramos recuperar este valor, inyectaremos el "seamComponentsProperties", que es una Hashtable que contiene los valores del fichero components.properties, y haremos el get de "birtum_host" para obtener el valor. Así garantizamos que se utiliza la URL adecuada en cada entorno en que esté desplegada la aplicación.

@In( "seamComponentsProperties" )
private Hashtable<String, String> componentsProperties;
...
String birtumHost = componentsProperties.get( "birtum_host" );

FundeWebJS

Para aplicaciones FundeWebJS, en local se añadirá la variable birtum_host en el fichero application.properties y para los entornos se añadirá en los application.properties de Helm Charts de nuestra aplicación.

Para hacer uso de su valor se inyectará en el bean en que queramos utilizar el cliente de BirtUM de la siguiente forma:

@Value( "${birtum.host}" )
private String birtumHost;

Reemplazo del cliente RMI del ejb-interfaces por el cliente REST

Para facilitar la sustitución de las funciones del cliente RMI por las funciones del cliente REST, se ha simplificado la librería. Todas las funciones del cliente RMI de la siguiente lista ahora se resumen en la función "generaInformeDesdeXML()" del nuevo cliente.

• generaPDFdesdeXML() en sus distintas implementaciones.
• generaEXCELdesdeXML() en sus distintas implementaciones.
• generaWORDdesdeXML() en sus distintas implementaciones.

En el caso de las peticiones asíncronas que se hacen con las funciones de la siguiente lista, ahora se hacen directamente con la función "generaInformeAsyncDesdeXML()".

• generaPDFdesdeXMLAsincrono() en sus distintas implementaciones.
• generaEXCELdesdeXMLAsincrono() en sus distintas implementaciones.
• generaWORDdesdeXMLAsincrono() en sus distintas implementaciones.

Y finalmente, la función "obtieneInforme()" ha sido sustituida por la nueva función "obtenerInformePorID()".

Respecto a las funciones de la clase ServicioBirtReportUmu, estas se ven sustituidas por los getters y setters de los DTOs de SolicitudInformeBirtum y SolicitudInformeBirtumConLibreria.