Cómo crear un conector personalizado -tutorial

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > ¿Cómo hacer? .... > Temas de integración >

Cómo crear un conector personalizado -tutorial

Introducción

Este tutorial lo guía para llevarlo de la mano en los pasos necesarios para crear un conector Personalizado en Bizagi.

Este tipo de conectores son caracterizados por su capacidad de permitirle escribir su propio código.

Esta posibilidad le permite apoyarse en las siguientes funcionalidades:

Utilizar cualquier tipo de autenticación para conectarse a un sistema externo.

Incluir librerías de terceros (en tecnología de Node.js).

 

A través de este tutorial, usted podrá crear un conector Personalizado que contemple las 2 funcionalidades anteriores (incluye una librería de terceros, permitiéndole a usted realizar su propios llamados e implementación)

Este tutorial se enfoca en cómo construir el conector aunque también mencione brevemente cómo se podría usar desde un proceso de Bizagi (para esta última parte, usted ya debe tener conocimientos sobre cómo implementar procesos en Bizagi y ejecutarlos).

Este conector se construye por medio del Editor de Conectores, tal y como se ofrece por los servicios de www.Bizagi.com.

 

ConnectorEditor_Custom00

 

 

Perfil requerido

Para poder aprovechar al máximo este tutorial y poder crear un conector Personalizado pro su propia cuenta, usted requiere del siguiente perfil:

Conocimientos en programación, principalmente en lenguaje Javascript (desarrollos orientados a aplicaciones web).

Es ideal y óptimo si usted ya ha trabajado con prácticas de programación orientadas a eventos y comunicación asíncrona(p.e jQuery o AJAX).

Entendimiento básico de notaciones para estructuras de información como lo son XML o JSON.

Estar familiarizado con servicios basados en protocolos web, como lo son los servicios REST.

Estar famillarizado con administradores de paquetes (librerías) como lo es npm (https://www.npmjs.com/) -o incluso repositorios de código como GitHub.

Podrá necesitar instalar npm y utilizar sus opciones desde la consola de comandos para descargar y empaquetar alguna libería de código abierto (disponibles bajo la licencia MIT que se ejecutan en Node.js -https://nodejs.org/en/).

 

note_pin

Para mayor información sobre los conectores como concepto y funcionalidad, y sobre este tipo de conectores especialmente, consulte Conectores Personalizados.

Se recomienda enfáticamente que por lo menos tenga un idea clara sobre los Conectores Personalizados, incluyendo alguna referencia sobre el API que Bizagi ofrece para codificarlos.

 

Herramientas requeridas

Especialmente para los conectores Personalizaos y dado que éstos se apoyan en librerías de terceros, se debe instalar npm localmente.

Npm es el administrador de paquetes para librerías de Node.js (lo cuál significa que a través de él, podrá descargarlas desde https://www.npmjs.com/, como lo sugiere el significado de su acrónimo: Node Package Manager)

 

Descargue e instale npm desde https://nodejs.org/en/download/.

 

NodeJS_download

 

Al instalar npm, los componentes que se requieren obligatoriamente son: Node.js runtime, y npm package manager:

 

NodeJS_install

 

 

Ejemplo

El ejemplo que se trabaja en este tutorial considera la invocación de un servicio simple que retorna el pronóstico del clima, para un lugar específico que se especifica con coordenadas de latitud y longitud.

El servicio retorna datos muy completos que por defecto describen el pronóstico del clima para el día actual.

 

Forecast_mainsite

 

Esta información y servicio está disponible en forecast.io a manera de un servicio REST, que es ejecutable vía un navegador, ingresando: https://api.forecast.io/forecast/[API_KEY]/[LATITUDE],[LONGITUDE].

Por ejemplo, este servicio se puede invocar usando las siguientes coordenadas: (40.9048938,-74.9462152) que representan la ubicación de Nueva York en Estados Unidos.

 

La siguiente imagen ilustra la disponibilidad del servicio, y la respuesta que retorna con las coordenadas de Nueva York (nótese que la información del servicio corresponde a la visualizada desde el sitio web principal de forecast):

 

Forecast_teaser

 

Nótese que la respuesta contiene información muy completa de la cuál no necesariamente utilizaremos toda; y que esta respuesta viene en formato JSON.

Para obtener coordenadas exactas, usted podrá apoyarse en Google Maps y ubicar esta información en la URL (primero latitud y después longitud) al consultar cualquier lugar del mundo:

 

GMaps_coordinates

 

 

 

Pasos a seguir

La siguiente es una descripción a alto nivel de los pasos a seguir, que se realizan todos por fuera de Bizagi Studio:

1.Asegurarse de tener una cuenta válida y permisos de acceso  al servicio externo (varía de acuerdo a las políticas de cada servicio o aplicación externa).

2.Descargar una librería de Node.js para la conectividad con el sistema externo.

3.Empaquetar la librería de conectividad de manera que las dependencias queden estructuradas apropiadamente para el uso de Bizagi.

4.Utilizar el Editor de Conectores para crear un conector Personalizado. Esto involucra estos sub-pasos:

i.Configurar los parámetros globales (p.e. infraestructura de autenticación).

ii.Importar la librería de conectivdad empaquetada para Bizagi.

iii.Crear acciones y especificar los detalles de su implementación (p.e entradas, salidas y el código interior).

 

Manos a la obra

Siga estos pasos para completar el tutorial.

 

1. Asegurarse de tener una cuenta válida y permisos de acceso.

Como con la mayoría de sistemas externos disponibles en la nube, su uso requiere de una cuenta activa en el sitio del sistema externo, y permisos de acceso explícitos para invocar este tipo de servicios via el API del sitio (principalmente debido a medidas de seguridad).

Por lo tanto y para poder utilizar el servicio que ofrece forecast.io, como se sugiere en la sección anterior, necesitamos obtener una llave de acceso (API Key).

 

Obtenga el API Key directamente desde https://developer.forecast.io/, al momento de crear una cuenta gratuita (esta le permite invocar 1000 veces el servicio sin cargo alguno).

 

Forecast_APIKey

 

Nótese que una vez que cree la cuenta y tenga su API Key, el mismo sitio le sugerirá cómo realizar un llamado de ejemplo, como se enseña en el enlace que aparece en el recuadro azul de la parte superior.

Podrá usar este enlace y verificar que el servicio se encuentra operacional (el ejemplo usa las coordenadas de Alcatraz en Estados Unidos).

 

note_pin Recomendaciones

Siempre primero pruebe estos servicios desde un navegador (sea directamente en la URL o con un plug-in en él).

Es recomendable validar el servicio antes de hacerlo desde Bizagi para verificar que se encuentra operacional y también para planear acordemente conociendo de antemano lo que se espera del servicio.

 

Nótese que este sitio también provee un enlace a la documentación oficial de su API (https://developer.forecast.io/docs/v2), la cuál es necesaria para que usted conozca qué tipo de conector crear y que características especiales considerar.

 

2. Descargar una librería de Node.js para la conectividad.

Uno de los potenciales clave de los conectores, es poder apoyarse en la tecnología Node.js y poder contar con una gran cantidad de librerías que se encuentran listas para ser usadas en npm.

 

Por lo tanto y para obtener una librería que le sea útil para integrarse a un servicio en especial, vaya a https://www.npmjs.com/.

Para el ejemplo del pronóstico del clima, navegue forecast.io y ubique una librería para ese sitio (https://www.npmjs.com/package/forecast.io).

Identifique el nombre único de esa librería (forecast.io):

 

Forecast_npm

 

note_pin Recomendaciones

Usted querrá considerar las librerías que detecte sean de mayor confiabilidad.

Para evaluar esto, podrá tener en cuenta aspectos como: su fecha de última modificación, número de descargas y reputación general, completitud de la documentación, disponibilidad de la fuente en un repositorio tipo GitHub, número de inconvenientes reportados y resueltos, y la capacidad de ofrecer soporte oficial.

Si a usted le preocupa la confiabilidad de una librería aún después de evaluar múltiples aspectos, siempre podrá revisar e inspeccionar el código de la misma por su propia cuenta.

 

Proceda a descargar la librería utilizando una consola de comandos y ubicándose en la ruta de instalación del npm, para utilizar npm install [nombre_único_de_librería].

 

En este caso:

npm install forecast.io

 

Npm_forecastio

 

 

note_pin Recomendaciones

Se recomiend que navegue hacia la ruta donde desea instalar su librería (p.e una carpeta nueva).

Podrá utilizar una configuración donde cuente con una variable de entorno NODEJS_HOME para utilizar los comandos de npm desde otros directorios.

 

Nótese también que podrá usar la opción --greedy si detecta que la estructura de librerías descargadas no es completamente plana.

 

Nótese cómo un procedimiento de descarga exitoso lista las otras librerías que forecast.io en particular utiliza (p.e, debug, request, y todas las dependencias dentro de request).

Estas son librerías igualmente necesarias para la ejecución exitosa de la librería principal.

 

Una vez que finalice la descarga, encontrará dentro de la carpeta node_modules todas las librerías necesarias, incluida forecast.io:

 

Npm_forecastzip

 

 

3. Empaquetar la librería de conectividad.

Este paso es necesario si la librería de conectividad contiene dependencias de otras librerías (un escenario común).

El objetivo es empaquetar la librería de conectividad de manera que sea un archivo .zip que ya contiene las dependencias a un mismo nivel para que Bizagi las incluya a todas por igual.

 

Para hacerlo, navegue en la ruta de la librería descargada, dentro de la sub-carpeta node_modules.

Allí deberá ver las dependencias que se mostraron al momento de su descarga via la consola de comandos, y  cree un .zip que incluya todas las librerías (en este caso son un total de 69):

 

Npm_forecastall

 

Al final, usted deberá tener un único archivo forecast.io.zip auto-contenido con las librerías necesarias para ejecutarse sin depender de otras externas.

 

 

4. Utilizar el Editor de Conectores

Como un último paso general, navegue al editor de conectores en http://connector.bizagi.com para crear un conector Personalizado.

 

ConnectorEditor_Custom00

 

Seleccion el modo Experto (Expert) e ingrese los detalles básicos de su conector.

 

Editor_basic

 

En este punto y antes de entrar en detalles de implementación, usted podrá querer consultar todo lo que necesita saber sobre el servicio al que se conectará. En este caso, detalles de la especificación del servicio de pronóstico del clima.

Los detalles relevantes para comenzar a definir la infraestructura de datos y configuración que necesita para la autenticación incluye:

Qué tipo de autenticación utiliza.

Qué parámetros son necesarios para esta autenticación.

 

Parámetros globales

En el caso puntual del servicio del clima, recuerde que de por si no cuenta con un método de autenticación explícito si no que se apoya en el uso de un API Key para la conexión autorizada (sin embargo, esta llave de acceso puede considerarsa como un parámetro de autenticación).

Docs_APIKey

 

note_pinRecomendaciones

No existe un único repositorio donde se encuentre la totalidad de los detalles en documentación para consumir el API de un servicio externo o para su conector en general. Es muy posible que usted deba consultar la documentación oficial del API de ese servicio, junto con documentación sobre la librería de conectividad de npm, además de realizar pruebas sobre el servicio externo desde el navegador si se desea verificar la información de entrada y salida.

 

Lo anterior implica que en cuanto a parámetros globales, definimos uno para permitir el almacenamiento y configuración del API Key:

 

Editor_APIKey

 

Importar la librería

En el caso puntual del servicio del clima, se importa la librería de conectividad re-empaquetada en el paso anterior y que contiene todas las otras librerías de dependencia (deberá ver que se carguen una gran cantidad de ellas):

 

Editor_Library

 

note_pin

Este procedimiento puede tomar un par de minutos, lo cuál depende del tamaño de la librería.

 

Implementar las acciones

En este tutorial, se implementa únicamente el servicio principal que consulta el pronóstico del clima para el día actual.

Esto significa crear una acción, la cuál se puede nombrar como Obtener el clima actual (Obtain current weather), para lo cual se defininen sus propiedades -Properties-, el nombre -Name- y la descrpición -Description-):

 

Editor_Action

 

Para comenzar a definir sus entradas, salidas o código en general, navegue hacia la documentación del servicio o realice una prueba desde el navegador.

Acerca de las entradas, se conoce de antemano que recibe latitud -latitude- y longitud -longitude- como parámetros:

 

Editor_inputs

 

Nótese que se definen como cadenas y como elementos de máximo una ocurrencia.

Para las salidas, y sin necesidad de navegar la documentación completa, revelamos un ejemplo de respuesta de una invocación de prueba.

 

Recuerde que esta respuesta tiene un formato JSON y por lo tanto usted deberá entender la estructura jerárquica de la misma.

Para el tutorial, nos enfocaremos en el resumen escrito del pronóstico del día actual (p.e lluvioso -Rainy-, nublado -Outcast-, despejado -Clear-, soleado -Sunny-,

con vientos -Windy-, etc):

 

Forecast_summary

 

Nótese que la manera de acceder a este resumen escrito es via el elemento "currently" que contiene al campo "summary".

Para entender de mejor manera, por ej. visualmente, la respuesta tipo JSON, usted puede apoyarse en sitios en línea que formatean este tipo de texto, como por ejemplo http://www.freeformatter.com/json-formatter.html.

La imagen siguiente enseña la misma respuesta de ejemplo una vez que se ha organizado para producir un formato más estético y legible:

 

Docs_SampleJSON

 

note_pin

En caso de que usted no esté familiarizado con la notación y estructura de un JSON, podrá también apoyarse en sitios que convierten formato JSON a XML como por ejemplo http://www.freeformatter.com/json-to-xml-converter.html.

Si realiza esto, recuerde que a pesar de que posiblemente le permita entender de mejor manera la estructura, el elemento nombrado como "root" realmente no aparece como tal en un JSON (es implícito y sin dicho nombre):

 

Docs_SampleXML

 

Proceda a definir las salidas de acuerdo al análisis anterior.

es decir, considere que summary es un elemento dentro de currently, lo cuál sugiere que currently debe ser de tipo objeto -object-:

 

Editor_outputs

 

note_pin

Nótese que usted no necesita crear una estructura de datos de salida con absolutamente toda la información que retorna la respuesta. Podrá solamente considerar aquella que sea de valor para sus requerimientos y escenario de integración.

 

Finalmente, escriba el código que se apoya en la librería de conectividad que invoca a su vez al servicio de pronóstico de clima.

Para hacerlo, navegue a la página y documentación de dicha librería donde verá cómo debe utilizarla.

 

Forecast_libdoc

 

note_pin

Información adicional de esta librería puede consultarse desde https://developer.forecast.io/docs/v2, en donde se aprecia un historial de cambios u otra información más al detalle que para efectos de este tutorial, no presentaremos.

 

Nótese que existen 3 bloques relevantes de código que utilizaremos (y que se deben modificar ligeramente).

Copie y pegue estos bloques dentro del código de su conector, en la función nombrada invoke donde implementaremos los llamados (solamente el primer bloque es una excepción ya que va afuera de la función):

 

Editor_Code0

 

Modifique cada uno de los bloques como se enseña en las imágenes a continuación.

Los métodos específicos que se ilustran a continuación, así como los motivos para utilizarlos, se describen en la documentación del API de Bizagi para conectores.

 

Bloque 1:

El uso de REQUIRED() en vez de require() es una buena práctica que le permite apoyarse en los métodos que ofrece el framework de Bizagi para cargar de mejor manera las librerías.

 

Editor_Code1

 

Bloque 2:
Obtener el API_Key para el momento de ejecución se realiza accediendo los parámetros globales, específicamente aquellos clasificados como parámetros de autenticación.

Esto se realiza mediante el objeto globals.

Editor_Code2

note_pin

Considere:

El valor que toma API_Key será configurado y manejado directamente con Bizagi Studio (o posteriormente con el Management Console en producción).

Lo que viene después de global.authdata... debe concordar con el nombre exacto que usted asignó a ese parámetro (considerando mayúsculas y minúsculas).

En el ejemplo, API_Key fue nombrado exactamente así en pasos previos.

 

Bloque 3:

Se debe cambiar los parámetros latitude y longitude de manera que sus valores provengan del modelo de datos, para lo cuál se utiliza el objeto data.

De manera similar, apóyese en el objeto LOG de Bizagi para las opciones de trazas y troubleshooting en vez de otro tipo de logs (p.e en vez de el "log" del código inicial) que sean usadas por librerúa de terceros.

 

Finalmente, recuerde lo siguiente: deberá dar formato a la respuesta para asegurarse que sea compatible con una estructura JSON que espera Bizagi.

Esto lo puede hacer usando RESPONSE(), y de esta manera, utilizar la función callback() para notificar a Bizagi que la invocación ha finalizado (debido a la arquitectura basada en eventos/asíncrona que se emplea en esta integración)
 

Editor_Code3

 

note_pin

Considere:

Ya sea para una invocación errónea o exitosa, el uso de callback() es obligatorio para delegar a Bizagi la respuesta. Nunca se debe utilizar una cláusula de throw para el manejo de errores.

Lo que sigue después de data.inputs.input... deberá corresponder con el nombre exacto que usted asigna a la definición de entradas (considerando mayúsculas y minúsculas).

En el ejemplo, latitude y longitude fueron nombrados exactamente así en pasos previos.

 

Y eso es todo!

Utilice el botón de descarga (Download) para guardar el resultado en un archivo local .bizc que contiene la implementación completa.

En este punto, ya podrá utilizar Bizagi Studio para configurar el conector y usarlo dentro de sus procesos.

 

Editor_Download

 

note_pinRecomendaciones

Bizagi podrá usar en algún punto de la ejecución, información optimizada en el caché, lo cuál es diseñado especialmente para un ambiente de producción.

Sin embargo y para evitar inconvenientes de refresco en su ambiente de desarrollo, especialmente al hacer cambios en el conector, asegúrese de incrementar el número de versión cuando realice modificaciones.

De esta manera, forzará que Bizagi trate esos cambios como una versión totalmente diferente del conector y no utilice el caché en esa ocasión.

 

Podrá verificar si se registraron sus cambios, o probar modificaciones directamente con el archivo de implementación que se genera en

C:\Bizagi\Projects\[su_proyecto]\Tools\connectors\node\[su_conector]\[su_version_de_conector]\actions\[your_connectors_action].js

 

Configuración en Bizagi

Configure el conector importando primero el archivo .bizc desde el modo Experto (vista Expert):

 

Installing_2_short

 

Luego, asegúrese de configurar el API Key que se le otorgó a su cuenta desde https://developer.forecast.io/ (al momento de la creación de la misma, como se mencionó en pasos iniciales), dentro de la configuración de sistema de ese conector:

 

Forecast_config

 

Al finalizar, su conector estará listo para conectarse a cualquier proceso.

Esto significa que para poder probarlo en ejecución, solamente necesita un proceso simple a manera de dummy con 3 atributos de tipo cadena: latitude, longitude y response (y por su puesto, un modelo  de proceso donde por lo menos use 2 actividades para permitir en la primera una captura de información -latitude y longitude- y para mostrar el resultado en la segunda).

 

Forecast_datamodel

 

Configure su uso desde una acción de actividad en el On Exit de la primer actividad:

 

Forecast_onExit

 

Al configurar sus entradas, asegúrese de mapear latitude y longitude:

 

Forecast_intputs

 

Y asegúrese también de mapear response como dato de salida.

 

Forecast_output

 

note_pin Recomendaciones

Recuerde que podrá utilizar las opciones de Bizagi nativas para trazas y troubleshooting.

Para ello asegúrese de habilitar las trazas de manera temporal y revisar el detalle registrado en C:\Bizagi\Projects\[su_proyecto]\Temporary\Connectors\.

 

Al ejecutar el proceso que utilice este conector, obtendrá el pronóstico del clima con las coordenadas que usted ingrese (p.e, latitud 40.9048938, y longitud -74.9462152):

 

Forecast_execution

 

 

Descargue el conector de este tutorial

El conector para el pronóstico del clima construido en este ejemplo está disponible para descarga desde:

http://download.bizagi.com/connectors/forecast/forecast.io.bizc.