Introducción
Existen dos tipos de conectores: Asistidos REST y Personalizados, como se indica en Crear conectores.
Esta sección presenta una guía de pasos de alto nivel que se deben considerar cuando se desean crear conectores.
Antes de comenzar
Es muy importante que primero se tenga conocimiento del API del sistema o aplicación externa a la que desea conectarse.
Ponga especial cuidado al tipo de autenticación que el API de esa aplicación externa soporta.
Esto significa, que usted deberá consultar la documentación oficial de dicho aplicación externo antes de comenzar con el desarrollo de un conector.
La información acerca del tipo de autenticación soportada le proporcionará una indicación para determinar si puede crear un conector de tipo Asistido REST, o si por el contrario, es necesario un conector de tipo Personalizado.
Para mayor información sobre cuándo crear un conector Personalizado, consulte los Métodos de autenticación y conectores tipo REST.
Pasos recomendados
De acuerdo al tipo de conector, le recomendamos planear su trabajo de acuerdo a los siguientes pasos:
•Pasos para crear conectores Asistidos REST
•Pasos para crear conectores Personalizados
Pasos para crear conectores Asistidos REST
Al crear un conector de tipo Asistido REST, los siguientes son los pasos generales a considerar:
1.Asegúrese de tener una cuenta válida con acceso autorizado a su aplicación externa desde otras aplicaciones (p.e, un nombre de usuario y contraseña válida, además de tokens de acceso u otras configuraciones en su aplicación externa).
2.Utilice el Connector Editor para crear un nuevo conector de tipo REST (opción fácil -Easy-).
3.Ingrese los detalles del nuevo conector, incluyendo el tipo de autenticación soportado.
4.Usted puede configurar un base URI para todas las acciones. El Base URI es un parámetro personalizable que puede ser configurado en Bizagi Studio, donde puede personalizar la URL para cada ambiente. Por ejemplo, usted puede definir el Base URI de cada ambiente de la siguiente manera:
•Ambiente de desarrollo: https://dev-api.com/services/data
•Ambiente de pruebas: https://test-api.com/services/data
•Ambiente de producción: https://prod-api.com/services/data
Si quiere configurar un Base URI, habilite este campo y escriba el Base URI donde están los servicios que utilizará.
|
Si las acciones del conector se encuentran en URLs diferentes, no utilice esta opción |
5.Cree al menos una acción y especifique las propiedades de esa acción.
|
En este paso es fundamental que define la URL de servicio (con los parámetros query string que apliquen), el método HTTP de invocación (GET/POST/PUT/DELETE), su codificación (content type), y si la acción utiliza autenticación o no. |
6.Defina las entradas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa.
7.Defina las salidas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa.
|
En este paso usted podrá definir la estructura de los mensajes de error también. |
8.Descargue el conector.
Una vez que tenga el conector como archivo .bizc, siga los pasos de su instalación para probarlo desde Bizagi Studio, como se describe en Instalar y configurar conectores.
Pasos para crear conectores Personalizados
Cuando se desea crear un conector Personalizado, los siguientes son los pasos generales que debe considerar:
1.Asegúrese de tener una cuenta válida con acceso autorizado a su aplicación externa desde otras aplicaciones (p.e, un nombre de usuario y contraseña válida, además de tokens de acceso u otras configuraciones en su aplicación externa).
2.Ubique una librería de conectividad en npm, para que sea reusable por su conector.
Asegúrese de encontrar una en www.npmjs.com que sea confiable (p.e analizando el número de descargas, inconvenientes reportados y documentación, etc) y que la pueda utilizar de acuerdo a su licencia (p.e. tipo MIT).
3.Empaquete la librería de conectividad.
Si ya cuenta con una librería que cumpla con sus requerimientos, asegúrese de descargarla y empaquetarla vía npm (el empaquetado final debe ser un .zip). De lo contrario, usted deberá implementar dicha funcionalidad de conectividad y empaquetarla como una librería reutilizable/portable.
Para descargar y empaquetar una librería, instale y utilice localmente npm (tal como se describe en Perfil requerido, conceptos y herramientas.
|
No descargue la librería directamente desde el navegador, dado que podrá no descargarse con todas sus dependencias (si esa librería usa a su vez, otras que no están empaquetadas en su interior). Esta práctica resultaría en una librería incompleta/no portable. |
Al empaquetar la librería utilice las opciones de consola con una cuenta de administrador, como se describe a continuación (a través del comando npm install <library-to-download> --greedy ).
Nótese que usted deberá ejecutar este comando desde la ruta donde desea descargar la librería; de lo contrario, ésta quedará en la ruta de los archivos de system32.
|
Tenga presente que el archivo comprimido final del empaquetado (el .zip), deberá ser compatible con la siguiente estructura: 1. Todas las dependencias y librerías deben estar en una estructura plana; que no sea recursiva ni jerárquica. 2. No debe existir una carpeta intermedia. El .zip deberá extraer las múltiples carpetas al mismo nivel (sean librerías o dependencias).
|
4.Utilice el Connector Editor para crear un nuevo conector de tipo Personalizado (modo Experto -Expert-), e ingrese los detalles relevantes.
5.Importe esta librería de conectividad.
6.Configure los parámetros globales.
Los parámetros obligatorios por definir son los de autenticación (Authentication):
Si la autenticación de por si debe ser personalizada, usted podrá editar el archivo auth.js presionando el botón </> auth.js .
Cuando se edita el archivo auth.js, usted puede incluir validaciones adicionales a la autenticación, configurar distintos tipos de protocolos a aquellos ofrecidos o enviar información directamente a Bizagi en la respuesta del método.
|
Si el archivo auth.js es modificado para personalizar la autenticación, este código se ejecutará cada vez que el conector sea invocado. Tenga presente que este método siempre devolverá un objeto de tipo callback, el cual se concatenará con el globals.authdata. |
De manera opcional, defina los parámetros de conexión (Connector) y de errores (Errors).
7.Cree por lo menos una acción y especifique los detalles.
8.Defina las entradas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa.
9.Defina las salidas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa.
10.Implemente la función llamada invoke.
Escriba su propio código para implementar cómo debe instanciarse ese método desde la librería que se importó (hacia el sistema/aplicación externa).
Ingrese su código dentro de la función predefinida invoke, haciendo uso del API de Bizagi para conectores.
11.Descargue el conector.
Una vez que tenga el conector como archivo .bizc, siga los pasos de su instalación para probarlo desde Bizagi Studio, como se describe en Instalar y configurar conectores.
|
De manera adicional y como directrices de mejores prácticas, considere estas recomendaciones:
1. Un conector ya descargado tendrá en su interior las librerías propietarias de Bizagi (bz-util), las cuáles proveen el API para los conectores así como otro métodos y el framework en general que les permite conectarse a servicios REST. Usted no deberá modificar esta librería y deberá tener en cuenta que Bizagi Ltd no soporta ni garantiza la compatibilidad en conectores que utilicen una librería modificada de bz-util. En cualquier momento, Bizagi Ltd podrá modificar o cambiar el contenido de la librería bz-util o adicionales, que se incluyan para la ejecución adecuada y segura de los conectores.
2. Usted será responsable de incluir información de licencia en los archivos read-me dentro de los conectores (o de manera alternativa, en la descripción del conector). Recuerde que algunas de las librerías que usted pueda utilizar dentro de sus conectores -según estén disponibles en www.npmjs.com- podrán exigir un enlace de referencia a ellas o algunas otras cláusulas de su licencia particular (aún cuando la mayoría son de licencia MIT). |