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