Exponiendo los servicios de nuestro Redmine Corporativo a través del WSO2 ESB

Como podemos leer en el título de la entrada puede ser muy común que en nuestra Empresa se

gestionen los proyectos de desarrollo mediante el uso del Redmine, que a mi juicio es una de las

mejores herramientas de gestión de proyecto Open Source que existe y una de las más usadas

actualmente. Redmine posee una capa de servicios REST que permiten realizar la mayoría de las

funcionalidades que usamos frecuentemente desde la interfaz web de la aplicación. Es muy probable

que nuestra Empresa no tenga intención de publicar de cara a internet el Redmine para que sus

desarrolladores actualicen y revisen sus tareas, sino que solo quiera dar acceso al mismo mediante su

API REST, ahí es donde entra a ocupar su papel protagónico el WSO2 ESB a través de sus servicios proxys

y conectores.

Por suerte para nosotros podemos encontrar el redmine-connector que se puede descargar desde

https://github.com/wso2-dev/esb-connectors para conectarnos a los servicios del API Rest del Redmine.

Una vez que hayamos descargado el conector debemos pasar a realizar una serie de configuraciones

para poder construirlo y después usarlo en el ESB.

Prerrequisitos para la construcción del mismo:

Tener configurado Maven 3.x

Java 1.6 o una versión superior

El proyecto org.wso2.esb.integration.integration-base es requerido para compilarlo y está

configurado para que lo descargue automáticamente, en caso que la descarga automática falle

se puede descargar el fuente desde https://github.com/wso2-dev/esb-

connectors/tree/master/integration-base y una vez descargado vamos hasta el directorio raíz y

ejecutamos el siguiente comando maven:

- mvn clean install

Con esto ya tenemos compilado e instalado en nuestro repositorio local de maven el

integration-base.

Una vez resueltos estos prerrequisitos pasamos a compilar y construir el redmine-connector siguiendo

los siguientes pasos que describo a continuación:

1. Descargamos el WSO2 ESB v4.8.1 desde la página oficial de WSO2.

2. Descomprimimos el WSO2 ESB y pasamos a configurar nuestro fichero axis2.xml en la siguiente

dirección “<ESB_HOME>/repository/conf/axis2/axis2.xml” agregando o des comentando las

siguientes líneas:

- <messageFormatter contentType="text/javascript"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

- <messageFormatter contentType="text/html"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

- <messageFormatter contentType="application/json"

class="org.apache.synapse.commons.json.JsonStreamFormatter"/>

- <messageBuilder contentType="text/javascript"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

- <messageBuilder contentType="text/html"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

- <messageBuilder contentType="application/json"

class="org.apache.synapse.commons.json.JsonStreamBuilder"/>

3. En dependencia del contenido que pudieran tener los adjuntos que vayan a ser subidos al

Redmine se deben agregar los formateadores y constructores de mensajes necesarios para los

mismos por ejemplo:

- <messageFormatter contentType="image/png"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

- <messageBuilder contentType="image/png"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

4. Una vez que hayamos hecho estos cambios volvemos a comprimir el directorio donde se

encuentra nuestro WSO2 ESB con el mismo nombre wso2esb-4.8.1.zip y lo copiamos en esta

dirección:"{REDMINE_CONNECTOR_HOME}/redmine-connector/redmine-connector-

1.0.0/org.wso2.carbon.connector/repository/"

Hasta este momento ya tenemos las configuraciones necesarias para poder construir nuestro conector,

si deseamos correr el test que trae configurado el redmine-connector debemos hacer lo siguiente:

1. Crearnos un demo de Redmine usando la siguiente URL http://m.redmine.org/

2. Nos logueamos con las credenciales que hayamos proporcionado.

3. Después vamos a la Administración-->Configuración-->Autenticación y habilitamos el checkbox

"Activar servicio web REST" para que nuestro Redmine permita poder acceder al API Rest del

mismo.

4. Vamos a “my/account” url del demo de Redmine y copiamos la “Clave de acceso de la API” y la

pegamos en el fichero redmine.properties en la propiedad que lleva por nombre apiKey .

5. Debes actualizar la URL que nos haya sido proporcionada por nuestro Redmine Demo en la

propiedad que lleva por nombre apiUrl en el redmine.properties.

6. Por último vamos a Administración y damos click en “Cargar la configuración por defecto” para

que sean cargadas algunas configuraciones a nuestra instancia demo de Redmine.

(OJO) Si no nos interesa correr el test que trae por defecto el redmine-connector obviamos estos

últimos 6 pasos y simplemente navegamos hasta "{REDMINE_CONNECTOR_HOME}/redmine-

connector/redmine-connector-1.0.0/org.wso2.carbon.connector/" y ejecutamos el siguiente comando

maven:

- mvn clean install

Si todo nos sale bien durante la compilación, construcción e instalación en nuestro repositorio local de

maven podremos encontrar en "{REDMINE_CONNECTOR_HOME}/redmine-connector/redmine-

connector-1.0.0/org.wso2.carbon.connector/target" el conector que tendrá el siguiente nombre:

redmine-connector-1.0.0.zip

Ya estamos listos para desplegar nuestro conector en el WSO2 ESB, para ello debemos iniciar el ESB

donde vayamos a instalar el conector ejecutando “ESB-HOME\bin\wso2server.bat” o “ESB-

HOME\bin\wso2server.sh” para Windows o Linux en función de su SO, cuando haya iniciado

accedemos por la consola de administración web en la siguiente dirección:

https://localhost:9443/carbon/ .

Nos autenticamos con admin/admin para el usuario y contraseña.

Navegamos en la sección Main hasta el menú Connectors y damos click en Add:

Nos debe aparecer la siguiente pantalla en la que vamos a cargar el fichero redmine-connector-1.0.0.zip

y presionamos el botón Upload:

Una vez concluido podremos ver que en el listado de conectores ya se encuentra disponible nuestro

conector :

Debemos activarlo para que pueda ser usado en nuestra PoC, para ello solo debemos presionar en la

columna Status el botón Disabled y ya estará listo para ser usado:

Ya nuestro WSO2 ESB está listo para poder usar el conector desde cualquier servicio proxy que necesite

invocarlo, para ello pasamos a crear nuestro proxy usando el Developer Studio (DS) que está disponible

en la siguiente URL http://wso2.com/products/developer-studio/ : Una vez que lo tengamos lo

ejecutamos y pasamos a crear nuestro proxy desde el Developer Studio Dashboard, creando un ESB

Config Project:

Debemos escoger en nuestro caso un New ESB Config Project y dar click en Next:

Escribimos el nombre que queramos para nuestro proyecto y damos click en Next:

Lo próximo sería especificar el grupo y el nombre el artefacto que se va a generar como se muestra

continuación y damos click en Finish:

Hasta el momento ya estamos listos para crear nuestro Servicio Proxy que su función en esta PoC será

listar una tarea dado su id, de ahí que lo llamaremos getIssueByIdProxy.

Para ello desde el Developer Studio Dashboard podemos seleccionar Proxy Service y escogemos la

opción de Crear un Nuevo Servicio Proxy y damos Next:

Escogemos un Custom Proxy y le ponemos el nombre y damos click en Finish:

Una vez terminado se nos mostrará una pantalla como la que sigue:

Lo próximo es importar el redmine-connector en nuestro proyecto para ello debemos dar click derecho

en nuestro proyecto y escoger la opción Import Conector que nos pedirá el mismo conector que

desplegamos anteriormente en nuestro WSO2 ESB, una vez realizado este paso podremos ver que ya

está disponible nuestro conector para la implementación del Servicio Proxy:

Ya estamos listos para comenzar con la implementación del Servicio Proxy pero antes se hace necesario

que visitemos la siguiente dirección

https://docs.wso2.com/display/ESBCONNECTORS/Redmine+Connector para obtener más información

acerca del funcionamiento del redmine-connector y sobre todo de la operación que vamos a consumir

que en nuestro caso es getIssue que nos permitirá obtener una Issue de nuestro Redmine Corporativo a

través del WSO2 ESB.

Antes de hacer el llamado a cualquiera de las operaciones que podemos realizar con este conector se

debe usar el elemento init que será el encargado de configurar los parámetros iniciales obligatorios para

poder acceder al API Rest del nuestro Redmine debido a que se necesita la autenticación previa en el

sistema.

Para ello es necesario que les sean proporcionadas 3 propiedades:

<redmine.init>

<apiUrl>{$ctx:apiUrl}</apiUrl>

<apiKey>{$ctx:apiKey}</apiKey>

<responseType>{$ctx:responseType}</responseType>

</redmine.init>

Propiedades:

apiUrl: URL de nuestro Redmine Corporativo para el consumo del API REST.

apiKey: Esta es la clave que se genera para cada usuario del sistema.

responseType: El tipo de respuesta que va a ser retornada por el Redmine que puede ser

(XML/JSON).

Y para poder acceder a la operación getIssue se hace necesario proporcionarle las siguientes

propiedades:

<redmine.getIssue> <id>{$ctx:id}</id> <include>{$ctx:include}</include> </redmine.getIssue>

Propiedades:

id: ID de la tarea que va a ser retornada.

include: Opcional – Para buscar los datos asociados , en este caso permite ser multievaluado

siempre que se separen por una coma

- Posibles valores:

1. children

2. attachments

3. relations

4. changesets

5. journals – Pueden ver Issue Journals para más información.

6. Watchers

Ya con esto tenemos la información necesaria para desarrollar nuestro proxy, lo primero que este va a

hacer es recoger toda la información necesaria para poder operar y será almacenado en distintas

propiedades del Servicio Proxy como se les mostrará a continuación:

Para ello podemos usar el drag and drop que posee el DS para poder completar la información de estas

5 propiedades necesarias para poder consultar nuestro Redmine Corporativo, si vamos al código fuente

que está generando nuestro Proxy Service podremos ver lo siguiente:

Como pudieron apreciar en la secuencia de entrada se extraen los parámetros necesarios para

completar nuestras propiedades para el posterior consumo de la operación getIssue usando la

expresión json-eval() para acceder a la información que vendrá en la petición REST :

<inSequence> <property name="apiUrl" expression="json-eval($.apiUrl)" scope="default" type="STRING" description="apiUrl"/> <property name="apiKey" expression="json-eval($.apiKey)" scope="default" type="STRING" description="apiKey"/> <property name="responseType" expression="json-eval($.responseType)" scope="default" type="STRING" description="responseType"/> <property name="id" expression="json-eval($.id)" scope="default" type="STRING" description="id"/> <property name="include" expression="json-eval($.include)" scope="default" type="STRING" description="include"/>

</inSequence>

Como dije anteriormente antes de hacer un llamado a cualquiera de las operaciones que tiene

implementada el redmine-connector es obligatorio llamar al redmine.init para ello vamos a la paleta

Redmine Connector arrastramos el init:

La configuración para el mismo será la siguiente accediendo a las propiedades definidas anteriormente

que por supuesto están dentro del contexto por lo que podemos acceder a ellas:

<redmine.init> <apiKey>{$ctx:apiKey}</apiKey> <apiUrl>{$ctx:apiUrl}</apiUrl> <responseType>{$ctx:responseType}</responseType> </redmine.init>

Una vez que hayamos inicializado los parámetros obligatorios pasamos a realizar la llamada a la

operación getIssue que igualmente debemos arrastrarla desde la paleta de Redmine Connector:

La configuración de la misma es la siguiente, en la que igual accedemos a las propiedades id e include

que son necesarias para la llamada de esta operación:

<redmine.getIssue> <id>{$ctx:id}</id> <include>{$ctx:include}</include> </redmine.getIssue>

Una vez llamada la operación simplemente lo que haremos es responder con lo que esta nos devuelva

usando el mediador Respond quedando nuestro Servicio Proxy de la siguiente manera:

A continuación les pongo el código fuente del Servicio Proxy para que puedan probarlo si así lo desean:

<?xml version="1.0" encoding="UTF-8"?> <proxy xmlns="http://ws.apache.org/ns/synapse" name="getIssueByIdProxy" transports="http https" startOnLoad="true" trace="disable"> <target> <inSequence> <property name="apiUrl" expression="json-eval($.apiUrl)" scope="default" type="STRING" description="apiUrl"/> <property name="apiKey" expression="json-eval($.apiKey)" scope="default" type="STRING" description="apiKey"/> <property name="responseType" expression="json-eval($.responseType)" scope="default" type="STRING" description="responseType"/> <property name="id" expression="json-eval($.id)" scope="default" type="STRING" description="id"/> <property name="include" expression="json-eval($.include)" scope="default" type="STRING" description="include"/> <redmine.init> <apiKey>{$ctx:apiKey}</apiKey> <apiUrl>{$ctx:apiUrl}</apiUrl>

<responseType>{$ctx:responseType}</responseType> </redmine.init> <redmine.getIssue> <id>{$ctx:id}</id> <include>{$ctx:include}</include> </redmine.getIssue> <respond/> </inSequence> <outSequence/> <faultSequence/> </target> </proxy>

Hasta aquí ya tenemos implementado nuestro Servicio Proxy solo nos falta desplegarlo en el WSO2 ESB

y finalmente probarlo desde cualquier cliente REST, para ello creamos desde el DS Dashboard un

Composite Application Project para en el usar nuestro Servicio Proxy y desplegarla en el WSO2 ESB, una

vez que hayamos especificado el nombre de la Aplicación escogemos el proyecto de Configuración para

el ESB que habíamos desarrollado antes en nuestro caso Redmine-Connector y le damos siguiente:

Nos aparece la siguiente pantalla en la que definimos el Group Id y el Artefact Id para la configuración

maven de nuestra aplicación:

Al dar click en el botón Finish automáticamente nos aparecerá la siguiente pantalla en la que nos

muestra la configuración general de esta aplicación y de las dependencias que este tiene, en nuestro

caso solo usaremos la configuración Redmine-Connector que es donde tenemos desarrollado nuestro

Servicio Proxy:

Ahora solo nos resta exportar esta aplicación para subirla a nuestro WSO2 ESB que lo haremos dando

click derecho sobre nuestra aplicación y seleccionando la opción Export Composite Application Project

en el menú contextual, ahí le especificamos el nombre que queremos que esta tenga, la versión y el

lugar donde la vamos a guardar y damos Next:

En el siguiente paso nos fijamos que esté seleccionada la configuración que tiene la implementación de

nuestro Servicio Proxy en nuestro caso con el nombre getIssueByIdProxy y le damos click al botón

Finish:

Nos dirigimos a la consola de administración del WSO2 ESB y en la sección Carbon Applications le

damos click al botón Add :

En la siguiente pantalla simplemente buscamos donde está la aplicación .car que exportamos y le damos

click al botón Upload:

Nos muestra una pantalla en la que el WSO2 ESB confirma que desplegó satisfactoriamente nuestra

aplicación y debemos dar click en el botón Ok:

Ya podemos ver nuestra aplicación desplegada en el WSO2 ESB:

Ya que nuestra aplicación fue desplegada automáticamente podemos ir a revisar si nuestro Servicio

Proxy está desplegado en la sección Services y podremos ver una pantalla como la que sigue a

continuación:

Nuestro servicio está listo para ser consumido desde un cliente REST para ello es necesario que vayamos

al Service Dashboard de nuestro servicio y busquemos cuales son los EndPoints que este nos creó para

poder ser consumido, en nuestro caso creó los siguientes:

1. http://localhost:8280/services/getIssueByIdProxy

2. https://localhost:8243/services/getIssueByIdProxy

Para la prueba que vamos a realizar estaremos usando el cliente RestClient del Mozilla Firefox y el

software SoapUI, utilizaremos el 1er EndPoint y el siguiente juego de datos:

{

"apiKey": "d61b11bf2d67c5d48175dfbdbccfe64bea22be02",

"apiUrl": "http://192.168.3.37/redmine",

"responseType": "json",

"id": "1453",

"include": "attachments,journals,children,relations,changesets,watchers"

}

Al consumir el servicio nos da una respuesta como la que les dejo a continuación por supuesto en

formato JSON porque así fue como se lo especificamos en el responseType:

{

"issue": {

"id": 1453,

"project": {

"id": 83,

"name": "Chakray Project"

},

"tracker": {

"id": 2,

"name": "Tareas"

},

"status": {

"id": 1,

"name": "Nueva"

},

"priority": {

"id": 2,

"name": "Normal"

},

"author": {

"id": 43,

"name": "Api Rest"

},

"assigned_to": {

"id": 43,

"name": "Api Rest"

},

"subject": "Prueba de consumo del API Rest del Redmine Corporativo de la

empresa",

"description": "Mediante esta prueba demostramos como podemos crear una

capa de servicios que permitan acceder al Redmine Corporativo de la empresa

Chakray mediante el uso del redmine-connector desde el WSO2 ESB",

"start_date": "2015-06-29",

"due_date": "2015-06-29",

"done_ratio": 0,

"spent_hours": 0,

"created_on": "2015-06-29T01:06:43Z",

"updated_on": "2015-06-29T01:06:43Z",

"attachments": [],

"changesets": [],

"journals": [],

"watchers": []

}

}

Si queremos que la respuesta sea en formato XML simplemente le cambiamos en la petición el

responseType a xml y obtendríamos una respuesta como esta:

<issue>

<id>1453</id> <project id="83" name="Chakray Project"/> <tracker id="2" name="Tareas"/> <status id="1" name="Nueva"/> <priority id="2" name="Normal"/> <author id="43" name="Api Rest"/> <assigned_to id="43" name="Api Rest"/> <subject> Prueba de consumo del API Rest del Redmine Corporativo de la empresa </subject> <description> Mediante esta prueba demostramos como podemos crear una capa de servicios que permitan acceder al Redmine Corporativo de la empresa Chakray mediante el uso del redmine-connector desde el WSO2 ESB </description> <start_date>2015-06-29</start_date> <due_date>2015-06-29</due_date> <done_ratio>0</done_ratio> <is_private>false</is_private> <estimated_hours/> <spent_hours>0.0</spent_hours> <created_on>2015-06-29T01:06:43Z</created_on> <updated_on>2015-06-29T01:06:43Z</updated_on> <closed_on/> <attachments type="array"/> <changesets type="array"/> <journals type="array"/> <watchers type="array"/>

</issue>

Aquí les dejo una captura de pantalla del uso del plugin RestClient de Mozilla Firefox:

Aquí les dejo una captura de pantalla del consumo desde SoapUI:

A modo de resumen durante el post estuvimos viendo a groso modo los siguientes tips:

Compilar y empaquetar el redmine-connector

Desplegar y activar un conector en el WSO2 ESB

Como importar un conector para el Developer Studio

Como implementar un Servicio Proxy en este caso usando el redmine-connector haciendo uso

del DS

Como construir y desplegar un Composite Application Project desde el DS en el WSO2 ESB

Como realizar un test de un servicio Rest en nuestro caso haciendo uso del plugins RestClient

del Mozilla Firefox y desde el SoapUI

En próximas entradas veremos cómo podemos realizar trasformaciones a la respuesta que nos devuelve

nuestro Redmine Corporativo mediante el uso de algunos mediadores de manera que solo obtengamos

la información necesaria de las Issues que tengamos asignadas.

Nos vemos pronto espero les haya gustado el post