Ejemplo: Conector de Imgur
Imgur es actualmente una de las mayores webs de contenido de imágenes de internet, donde en tiempo real son juzgadas por una comunidad de usuarios través de comentarios y votos. En esta sección haremos el desarrollo del conector de Imgur el cual puede subir una imagen dao un archivo .jpg o .png.
Lo primero es ir a nuestro editor de conectores y comenzar un nuevo proyecto. Para eso seleccionaremos empezar un nuevo conector personalizado y digitaremos su información.
name: imgur.author: SU_NOMBREversion: 1.0.0website: https://nativapps.codescripton: Imgur connector for Bizagi Studio
Hecho esto, estaremos viendo el área de trabajo de conectores.
SDK vs API HTTP?
Para poder conectarnos con la API necesitamos realizar peticiones HTTP desde nuestra acción del conector. Los servicios que usan los conectores usualmente proveen a los desarrolladores con algún SDK en sus sitios web, estos SDK simplifican el tiempo de desarrollo y el trabajo que se necesita hacer con su API por lo cual es recomendado no reinventar la rueda. En el caso que no exista un SDK, se aconseja utilizar alguna librería HTTP cómo axios, node-fetch, request.
En el caso del conector de imgur usaremos una libería que se encuentra en npm, llamado imgur(https://www.npmjs.com/package/imgur).
La librería ya tiene implementada la lógica que necesitamos que realice el conector, por ende nuestro trabajo solo será utilizarla. Para lo anterior necesitamos importarla en nuestro código y asignarle unclient_id para que podamos realizar uploads:
var imgur = require('imgur)';
// Setting the API Url
imgur.setAPIUrl('https://api.imgur.com/3/');
// Setting Credentials
imgur.setCredentials('[email protected]', 'password', 'aCs53GSs4tga0ikp');
// Uploading a base64 image
var imageInBase64 = 'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAmUlEQVQ4je2TsQ3CMBBFnxMa08WR2IQKJskIUNwMZAcYwWIQMs65JCUpEEIYW4pJy6v+6e6+/hVnnGsAzsCBMi7AsbbW/rIMsAU2xrnmkeruuzW7zgIw+JGbv6fGQpWzfy3HOsJlDQY/AlCv3jpF9oS5ZBOICKoB1YCIlCdQDR9127qyBHP5Gyw3CBXPr/qi709JHXE1S995AsqoJu8x78GsAAAAAElFTkSuQmCC';
imgur.uploadBase64(imageInBase64)
.then(function (json) {
console.log(json.data.link);
})
.catch(function (err) {
console.error(err.message);
});
Licencias
Cómo usualmente estamos dependiendo de código open source para apoyarnos, es importante considerar el tipo de licencia que poseen para aquellos que decidan usar dicha librería. Bizagi Studio al ser un software cerrado al público, necesita que los conectores que desarrollemos no usen librerías que pongan en riesgo el código propietario de la compañía. Es por esto que debemos revisar que los tipos de licencia sean parecidos a MIT u Apache y no como las de tipo GNU.
Usando la documentación de la API
Ususalmente, para usar la API de un servicio es necesario realizar el registro de una cuenta y crear una aplicación en su portal. Un client_id es un identificador que se le asigna a su aplicación, en este caso su aplicación de imgur y es recibido con un secreto, client_secret.
Si nos dirigimos a la documentación de la API de imgur (https://apidocs.imgur.com), encontramos una sección que lee "Register an Application(IMPORTANT)". Siguiendo los pasos de la documentación podremos obtener una nueva aplicación de imgur junto a sus credenciales que usaremos más adelante.
Parámetros globales
Según la documentación hará falta de un email, una password y client_id para poder hacer uso de la API desde node.js. Ya que estos parámetros no son inputs ordinarias sino inputs de autenticación, en el editor de conectores nos ubicamos en el panel de parámetros globales y agregamos estas 3 propiedades (las últimas dos deben estar encriptadas ya que son información sensible).
Mapeo de propiedades, entradas y salidas.
A continuación debemos llenar la información respectiva para Bizagi Studio. lo primero es proveer al usuario con la información de la acción que estamos implementando.
Como entrada, esperamos recibir una imagen (Nota: Bizagi transforma los archivos que se usen como input a base64)
y como salidas planeamos devolverle una url en un la propiedad objeto respuesta:
También se debe manejar los errores en caso que ocurra alguno, para esto mapeamos el objeto error, 
Elección de librerías adicionales
Siguiendo con nuestro concector, una vez elegida la manera de realizar las peticiones a la API de imgur, lo siguiente es decidir las librerías que necesitaremos para nuestro proyecto. Recuerde que todas las librerías deben ser compatibles con la node v.0.12.5.
Para el conector no se usará ninguna librería adicional, solo la librería de utilidad de bizagi, bz-util.
Importación de librerías
Para usar las librerías en nuestra implementación debemos importarlas usando el panel de librerías del editor. Para hacer esto necesitamos subir al editor nuestras librerías comprimidas en un archivo .zip:
- En su equipo abrir una terminal y navegar en una ubicación cualquiera.
- Ya una vez en esa ubicación, ejecutar el comando
npm install imgur. Esto causará que se instalen las dependencias y aparecerá una nueva carpeta llamdanode_modules. - En la carpeta llamada
node_modules, comprimir en un archivo .zip la carpeta con nombre de imgur. - Una vez termine el proceso de compresión, podemos seleccionar el signo "+" en nuestro editor de conectores y podemos realizar la subida de la librería. Esta será listada a continuación.
Implementación de la lógica
La primera acción a implementar será la de subir una imagen que se encuentre en una URL dada por el usuario, a continuación nos ubicamos en el panel de acciones y agregamos una nueva acción. Le daremos el nombre de uploadFromFile
// Importación de librerías
var bzutil = require('bz-util'),
imgur = require('imgur');
//Solamente tomaremos los helpers que necesitamos de bz-util
var BzError = bzutil.error,
BzResponse = bzutil.getResponse;
// Declaramos una función que se encargue de los detalles de las credenciales.
function setupCredentials(email, password, clientId) {
imgur.setCredentials(email, password, clientId);
imgur.setAPIUrl('https://api.imgur.com/3/');
}
// Bizagi espera un export nombrado "invoke". Aquí declaramos la función se ejecutará.
exports.invoke = function(globals, actionName, data, authenticationType, logger, done) {
// Los parámetros globales de autenticación que declaramos, se encuentran en
// el objeto de globals.authdata.
var email = globals.authdata.email;
var password = globals.authdata.password;
var clientId = globals.authdata.clientId;
// Los inputs los encontramos en el objeto globals.inputs.input
var url = data.inputs.input.url;
// Declaramos por último una variable para el mensaje de error, sin valor de momento.
var bzErrorMessage;
// Invokamos la función setupCredentials para que se encargue de configurarlas.
setupCredentials(email, password, clientId);
// Ejecutamos la función para subir desde una URL.
imgur.uploadUrl(url)
.then(function(res) {
// Si la promesa retorna, es porque ha sido exitoso y 'res'
// tiene la respuesta del servidor.
// Escribimos un log para dejar registro de la respuesta.
logger.info(JSON.stringify(res));
// Devolvemos una respuesta a Bizagi Studio, indicando con un código HTTP de 200
// que todo ha funcionado.
done(BzResponse(res, null, 200));
})
.catch(function(res) {
// Si la promesa atrapa un error, es debido a que un error ha ocurrido, esto
// puede darse si no hay conexión a internet o del lado de la API algo falló.
// Escribimos un log para dejar registro del error.
logger.error(JSON.stringify(res));
// Usando BzError podemos crear un error humanamente legible para que lea el usuario.
bzErrorMessage = res.code === "ENOTFOUND" ?
BzError('GLB.RESPONSE_ERROR', [res.message]) :
BzError('GLB.RESPONSE_ERROR', [res.status, res, res.data.error])
// Devolvemos una respuesta a Bizagi Studio, indicando que un error ocurrió.
done(BzResponse(null, res, res.status, bzErrorMessage));
});
};
Una vez escrito esto, podremos hacer click en el botón de _"Download Connector" _y se nos creará el archivo .bizc que guarda el conector. El siguiente paso es ejecutar Bizagi Studio y probrar nuestro nuevo conector.
Prueba del conector
Lo siguiente ne lal ista de pasos es ejecutar Bizagi Studio y crear nuestro nuevo proyecto de Bizagi. Le asignaremos un nombre cualquiera y seleccionaremos que pertenezca a una plataforma de .NET.
Para continuar es necesario digitar la información de la base de datos y del login de SQL Server. Usaremos la información que viene por defecto con la instalación de Bizagi: El usuario "sa" y su contraseña "bpmn123"
Cuando hagamos click en next, Bizagi Studio comenzará a crear el proyecto. (Esto puede tardar alrededor de 20 minutos).
Cuando el proyecto haya sido construido, seremos bienvenidos por la interfaz principal de Bizagi Studio.
Para probar nuestro conector tenemos que simular de la misma manera en que los usuarios finales lo usarán, esto significa que debemos crear un proceso simple que use de nuestro conector. Para crear un nuevo proceso, hacemos click en la sección que lee "New Proccess". A continuación se abrira una instancia del Bizagi Modeler para modelar nuestro proceso.
El Bizagi Modeler nos provee con los elementos variados, nuestro proceso hará lo siguiente:
- La primer tarea consiste en que el usuario enviará una imagen de su preferencia por la interfaz de usuario.
- La segunda tarea es automática y ejecuta la acción de subir la imagen a Imgur del conector.
Una vez hecho este diagrama, guardamos y cerramos la ventana para volver a la instancia de Bizagi Studio. El siguiente paso es acceder al siguiente menu para crear nuestro modelo de datos.
Seremos bievenidos con un diagrama vacío que contiene únicamente un elemento con el nombre de nuestro proceso. En este canvas crearemos nuestro modelo de datos referente al proceso.
Lo primero es hacer un click izquierdo en nuestro elemento y seleccionar "Edit attributes" para desplegar un nuevo cuadro de diálogo.
A continuación añadiremos los atributos necesarios para nuestro proceso, un atributo de tipo archivo para recibir el input del usuario y atributo de tipo un string para almacenar el link que nos devuelva la API.
Agregados estos nuevos atributos, hacemos click en el botón que lee "Next >>" y confirmamos.
Cuando confirmemos el cuadro de diálogo se cerrará y nuestra entidad tendrá ahora los dos atributos anteriores, solamente hace falta guardar el diagrama y cerrar la ventana para volver a la instancia de Bizagi Studio.
El próximo paso es la implementación de la interfaz de usuario que los clientes usarán para enviar su archivo. Para esto navegamos por el menu principal y seleccionamos el item que se llama "Define Forms".
Cambiaremos a una ventana donde está el proceso sobre el cual estamos trabajando y los procesos manuales estarán habilitados. Haga click sobre la tarea de "Save File" o la equivalente donde se guarde la imagen que se va a subir.
Pronto se abrira una nueva ventana conocida como "Bizagi Forms Designer", otra herramienta de la suite de Bizagi Studio para poder crear nuestro formulario simplemente arrastrando los inputs que necesitemos de la barra izquierda.
El formulario solo necesitará de la entrada del archivo, procedemos a guardar y cerrar la ventana del diseñador. Una vez de vuelta en la pantalla principal, debemos navegar a la pestaña de "Tools", en ella procederemos para importar el conector a Bizagi Studio.
Una vez en esta pestaña, navegamos usando la barra izquierda y seleccionaremos la categoría de "External Systems", en ella podremos ver una lista de conectores importados al sistema. Para importarlo debemos hacer click sobre el item de la lista de "Connectors" e importar el archivo descargado del editor de conectores.
Una vez importado el conector se listará junto con los demas conectores existentes.
por último, se necesita configurar el conector haciendo doble click sobre este. Una nueva ventana aparecerá y deberemos ingresar las credenciales que configuramos alguna vez en el editor de conectores.
Hecho esto damos click en el botón de "OK", y nuestro conector está listo para ser usado por nuestro proceso. Para continuar nos ubicaremos en la sección de "Business Rules" de la pantalla principal y haremos click en "Activity Actions ".
Para poder usar nuestro conector en nuestro proceso, debemos indicarle a este cómo debe usarse, para eso debemos crear una regla de negocio y establecer las entradas - salidas de nuestro conector. Comenzaremos haciendo click en la tarea automática que definimos anteriormente.
En el cuadro de diálogo que aparecerá haremos click en el botón para añadir una regla en la sección de "On Enter" y seleccionaremos el tipo de conector.
A continuación se nos listarán los conectores importados y configurados en una lista, haciendo click en ellos podremos ver todas las acciones que definimos en el editor de conectores. Seleccionaremos la única acción que realizamos y hacemos click en "Next >>"
Lo primero es configurar las entradas que recibe el conector, en este caso recibimos la data del archivo que el usuario sube al servidor y debe ser asignado a la entrada de fileContents.
y por último, asumiendo que la respuesta es éxitosa, debemos indicarle que la propiedad link de la respuesta debe ser asignado a nuestro atributo de imageUrl.
Cuando hagamos click en "Finish", habremos terminado de configurar nuestro conector y solo debemos hacer una prueba con el proceso de ejemplo.
Haga click en "Ok" y una vez el cuadro de diálogo desaparezca, ubique en la barra superior de Bizagi Studio el botón para hacer "Run" o ejecutar la aplicación, pasado unos minutos aparecerá una nueva ventana en su navegador predeterminado.
Esta es una interfaz donde podremos ejecutar nuestros procesos. Para eso crearemos umo nuevo caso con el proceso que definimos anteriormente y subiremos nuestro archivo al servidor.
Lo último para probar es hacer click en "Siguiente" y esperar a que la API responda de vuelta:
