Introducción
Un conector es un módulo que agrupa una lista de acciones que extienden la funcionalidad de sus procesos. Para saber más sobre conectores, diríjase a Conectores de Bizagi. Usted puede crear conectores a partir de APIs RESTful; para hacer esto, es necesario leer y entender el API del sistema externo. El nivel de dificultar para crear un conector manualmente depende del API del sistema externo. Sin embargo, el Connector Editor de Bizagi ofrece la opción de generar conectores automáticamente a partir de especificaciones descritas en OpenAPI o en RAML.
|
Sólo conectores REST pueden ser generados automáticamente desde especificaciones descritas en OpenAPI o RAML. |
RAML
Lenguaje de modelado API RESTFul (RAML por sus siglas en inglés) es un lenguaje que le permite administrar el ciclo de vida de un API desde el diseño hasta su uso. RAML permite traducir la descripción técnica de un API, en un lenguaje que pueda ser ententido por humanos y máquinas sin usar código. Está diseñado para brindar tanto al proveedor del API como a sus consumidores, un formato que se puede usar como un contrato mutuo. Para generar un conector a través del Connector Editor de Bizagi, su API debe estar definido en las versiones 0.8 o 1.0 de RAML.
Consideraciones
La siguiente tabla muestra las principales consideraciones y diferencias entre las dos versiones soportadas de RAML.
RAML v.0.8 |
RAML v.1.0 |
|
|---|---|---|
Tipos de dato soportados |
String, Integer, Boolean, Number, Array, Object |
|
Métodos http soportados |
GET, PUT, POST, DELETE |
|
Formatos de archivo soportados |
.raml, .zip |
.raml, .zip |
Tipos de MIME soportados en la solicitud |
application/json, application/x-www-form-urlencoded*, text/plain |
|
Tipos de MIME soportados en la respuesta |
application/json |
|
Métodos de seguridad |
Los métodos de seguridad no son mapeados durante la generación del conector. Sólo se tendrá en cuenta qué métodos requieren autenticación. Sin embargo, los métodos específicos (basic, oauth, etc.) no serán configurados. |
|
|
* En RAML v.0.8, para mapear la estructura de entrada al usar application/x-www-form-urlencoded, sólo se puede usar la propiedad formParameters. |
Usando el generador de conectores a partir de un descriptor RAML
Suponga que quiere integrarse con Salesforce para administrar e integrar su proceso de ventas a la nube. Para hacer esto, usted puede crear el conector manualmente y definir cada acción en el Connector Editor. Sin embargo, si la especificación del sistema externo está descrita en RAML, usted puede crear fácilmente su conector.
Para generar su conector, complete los siguientes pasos:
Diríjase al Hub de Integración de Bizagi Studio y seleccione Haga sus propios conectores.
Haga clic en la opción de RAML y escoja el archivo que desea importar.
Tenga en cuenta que con esta opción usted puede cargar un archivo .raml, o un proyecto completo que esté comprimido en una carpeta .zip.
Seleccione el archivo que desea cargar y haga clic en abrir.
Si usted tiene el proyecto en una carpeta comprimida (.zip), seleccione de la lista desplegable el archivo principal del proyecto y haga clic en Generar conector para continuar.
Una vez haya cargado el archivo o el proyecto, todas las acciones del conector se generarán automáticamente. Usted puede ver los detalles de cada acción así como la configuración general del conector. Note que podrá configurar el Base URI para su conector. 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
Una vez su conector esté listo, haga clic en Guardar.
Finalmente, puede instalar y configurar su conector. Para más información sobre cómo instalar un conector, haga clic aquí.
OpenAPI
La especificación de OpenAPI (OAS) es un formato de descripción para APIs RESTful, lo que permite tanto a humanos como a computadores entender las capacidades de un servicio sin tener que revisar su código fuente. La especificación puede ser escrita en un lenguaje de fácil lectura y entendimiento, en formatos como YAML o JSON. Para generar un conector a través del Connector Editor, su API debe estar definido en la versión 2.0 de OpenAPI (Swagger) o en su versión 3.0.
Consideraciones
La siguiente tabla muestra las principales consideraciones y diferencias entre las dos versiones soportadas de OpenAPI.
OpenAPI v.2.0 |
OpenAPI v.3.0 |
|
|---|---|---|
Tipos de dato soportados |
String, Integer, Boolean, Number, Array, Object |
|
Métodos http soportados |
GET, PUT, POST, DELETE |
|
Formatos de archivo soportados |
.json, .yaml, .yml, .zip |
.json, .yaml, .yml, .zip |
Tipos de MIME soportados en la solicitud |
application/json, application/x-www-form-urlencoded, text/plain |
|
Tipos de MIME soportados en la respuesta |
application/json |
|
Parámetros de operaciones por endpoint soportadas |
Path, Query, Body, Form |
Path, Query |
Métodos de seguridad |
Los métodos de seguridad no son mapeados durante la generación del conector. Sólo se tendrá en cuenta qué métodos requieren autenticación. Sin embargo, los métodos específicos (basic, oauth, etc.) no serán configurados. |
|
Base URI |
Para la construcción del Base URI, se toman en cuenta las propiedades host, basePath y schemes. De la lista de schemes, Bizagi buscará la primera URL que use https. Si ninguna URL usa este protocolo, Bizagi tomará la primera URL. |
Para la construcción del Base URI, Bizagi will buscará en la propiedad servers la primera URL que use https. Si ninguna URL usa este protocolo, Bizagi tomará la primera URL. |
Usando el generador de conectores a partir de un descriptor OpenAPI
Suponga que quiere integrarse con Uber para manejar un proceso de transporte de personas. Para hacer esto, usted puede crear el conector manualmente y definir cada acción en el Connector Editor. Sin embargo, si la especificación del sistema externo está descrita en OpenAPI, usted puede crear fácilmente su conector.
Para generar su conector, complete los siguientes pasos:
Diríjase al Hub de Integración de Bizagi Studio y seleccione Haga sus propios conectores.
Haga clic en la opción de OpenAPI y escoja el archivo que desea importar.
Tenga en cuenta que con esta opción usted puede cargar un archivo .yaml, .yml, .json, o un proyecto completo que esté comprimido en una carpeta .zip.
Seleccione el archivo que desea cargar y haga clic en abrir.
Si usted tiene el proyecto en una carpeta comprimida (.zip), seleccione de la lista desplegable el archivo principal del proyecto y haga clic en Generar conector para continuar.
Una vez haya cargado el archivo o el proyecto, todas las acciones del conector se generarán automáticamente. Usted puede ver los detalles de cada acción así como la configuración general del conector. Note que podrá configurar el Base URI para su conector. El Base URI es un parámetro personalizable que puede ser configurado en Bizagi Studio, donde puede establecer 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.uber.com/v1
•Ambiente de pruebas: https://test-api.uber.com/v1
•Ambiente de producción: https://prod-api.uber.com/v1
Una vez su conector esté listo, haga clic en Guardar.
Finalmente, puede instalar y configurar su conector. Para más información sobre cómo instalar un conector, haga clic aquí.