Pasos recomendados para crear conectores

<< Clic para mostrar Tabla de Contenidos >>

Navegación:  Bizagi Studio > Integrar aplicaciones externas desde Bizagi > Conectores de Bizagi > Crear conectores > Conceptos y lineamientos para crear conectores >

Pasos recomendados para crear conectores

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-).

 

ConnectorEditor_REST00

 

3.Ingrese los detalles del nuevo conector, incluyendo el tipo de autenticación soportado.

 

REST_3

 

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á.

 

REST_11

 

note_pin

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.

 

REST_1

 

note_pin

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.

 

REST_7

 

7.Defina las salidas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa.

 

REST_8

 

note_pin

En este paso usted podrá definir la estructura de los mensajes de error también.

 

8.Descargue el conector.

 

REST_9

 

 

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).

 

Custom_1

 

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.

 

note_pin

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.

 

NODEJS_Npmcommand

 

note_pin

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).

 

Npm_forecastzip

 

4.Utilice el Connector Editor para crear un nuevo conector de tipo Personalizado (modo Experto -Expert-), e ingrese los detalles relevantes.

 

ConnectorEditor_Custom00

 

5.Importe esta librería de conectividad.

 

Custom_5

 

6.Configure los parámetros globales.

Los parámetros obligatorios por definir son los de autenticación (Authentication):

 

Custom_9

 

Si la autenticación de por si debe ser personalizada, usted podrá editar el archivo auth.js presionando el botón </> auth.js .

 

Custom_14

 

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.

 

note_pin

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).

 

Custom_7

 

7.Cree por lo menos una acción y especifique los detalles.

 

Custom_12

 

8.Defina las entradas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa.

 

REST_7

 

 

 

9.Defina las salidas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa.

 

Custom_13

 

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.

 

dashboard_patch_B_frame4

 

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.

 

note_pin

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).