Interfaz del editor de conectores personalizados

<< Clic para mostrar Tabla de Contenidos >>

Navegación:  Bizagi Studio > Integrar aplicaciones externas desde Bizagi > Conectores de Bizagi > Hub de integración > Crear conectores > Interfaz del Editor de conectores en detalle > Conectores Personalizados >

Interfaz del editor de conectores personalizados

Introducción

El editor de conectores de Bizagi le da la posibilidad de crear conectores desde cero. Allí, usted puede crear dos tipos de conectores: los conectores asistidos REST, que no requieren de código, y los conectores personalizados, que le permiten incluir librerías de terceros y su propio código. En este artículo se explica en términos generales la interfaz de conectores personalizados.

 

Opciones de la interfaz del Editor en detalle

Sea al momento de crear un nuevo conector, o al abrir uno existente para realizar modificaciones, se abre la interfaz para conectores personalizados:

 

CustomConnector16

 

1. Información general del conector

Esta primera sección contiene la información general del conector, es decir su nombre, versión, autor, sitio web, descripción e ícono. Esta información la puede modificar en cualquier momento.

 

CustomConnector17

 

2. Acciones y área de trabajo

En esta sección se despliegan las acciones definidas para el conector mientras se muestran sus propiedades.

 

CustomConnector03

 

El panel de la mano izquierda lista las acciones y le permite administrarlas (crear nuevas o eliminarlas). Usted puede editar el nombre de una acción haciendo clic sobre el ícono del lapiz, o eliminar una haciendo clic sobre el ícono del bote de basura. Al seleccionar una acción, el área de trabajo hacia la derecha enseña los detalles de implementación para esa acción.

La parte baja de la derecha enseñará puntualmente las propiedades, entradas y salidas.

 

CustomConnector04

 

3. Entradas y salidas

Esta sección corresponden a las entradas y las salidas de la acción. La definición tanto para entradas como para salidas se realiza igual.

Esto significa que usted debe definir la estructura jerárquica (compatible a un formato JSON o XML) que sigue la información de entrada y de salida para ese sistema externo.

 

note_pin

Los tipos de datos definidos deben corresponder a los que utiliza su sistema externo, usualmente consultable desde la documentación del API de ese sistema.

Los posibles tipos de datos simples son:

Boolean

Byte

Date

Decimal

Double

Integer

String

 

Los tipos de datos complejos, deben ser definidos como Object, de forma que puedan contener a su vez a otros elementos que serán datos simples o complejos anidados.

 

CustomConnector05

 

Imagine que su acción debe recibir una estructura de entradas como la que se muestra a en la imagen anterior:

 

Esta, vista desde un JSON se ve así:

 

{

 "Main_element": {

   "Information1": "String",

   "Information2": "String"

 },

 "Unbount_element": {

   "Information3": "String"

 }

}

 

Por otro lado, vista desde un XML se ve así:

 

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <Main_element>
     <Information1>String</Information1>
     <Information2>String</Information2>
  </Main_element>
  <Unbount_element>
     <Information3>String</Information3>
  </Unbount_element>
</root>

 

Para definir esta estructura en el editor de conectores, usted tiene dos opciones. Puede usar el botónde Autogenerate, o puede introducir la estructura a mano.

 

El botón de Autogenerate le permite cargar un archivo de tipo JSON o XML con la definición de las entradas o de las salidas. Haga clic en este botón, seleccione el archivo que desea cargar y el editor de conectores automáticamente generará la estructura correspondiente.

 

CustomConnector06

 

note_pin

Cuando se usa la opción de Autogenerate sólo se soportan los tipos de dato Object y String. Si su estructura tiene un tipo de dato distinto (por ejemplo, Double), primero debe importar el archivo XML o JSON , y después cambiar las entradas o las salidas que tengan un tipo de dato distinto.  

 

La segunda opción es introduciendo las entradas a mano. Los objetos de tipo object, al ser datos complejos, pueden contener elementos adicionales. Es por esto que para este tipo de dato, aparecerá el ícono Easy05 al costado derecho. Para agregar nuevos elementos a una estructura particular, haga clic sobre el ícono Easy05. Con esto, un nuevo elemento aparecerá, sobre el que podrá especificar el nombre, el tipo de dato, y si su ocurrencia es única (tipo single) o múltiple (tipo list).

 

CustomConnector07

 

Agregue uno a uno los parámetros de entrada hasta obtener la estructura deseada.

 

CustomConnector05

 

4. Librerías

Aquí se administran las librerías importadas que usa del conector .Nótese que estas librerías, junto con otras dependencias internas que a su vez cada librería use, usted las podrá visualizar en la lista, incluyendo la librería por defecto que proporciona Bizagi para todos los conectores (bz-util):

 

CustomConnector08

 

Aunque esta opción importa una librería que será empaquetada dentro del conector, se debe incluir la linea de código donde se referencia esa librería, es decir, de manera análoga a un import o using de la programación en Java o C# respectivamente.

 

5. Parámetros globales

Los parámetros globales le permiten definir propiedades genéricas para ser usadas en todas las acciones del conector.

 

CustomConnector18

 

Administre estos parámetros adicionando nuevos, eliminándolos o editando su nombre, valor por defecto, si son requeridos o si se muestran protegidos en Bizagi Studio (name, default value, required y Field encryption).

 

CustomConnector09

 

Existen tres tipos de parámetros globales:

Conector: propiedades que no cambian durante la ejecución de las acciones (por ejemplo, la URL de un sistema externo). Asimismo, usted puede definir propiedades genéricas que cambien dependiendo del ambiente donde se ejecute la aplicación (desarrollo, pruebas, producción). De este modo, podrá hacer la configuración respectiva desde Bizagi Studio sin afectar mapeos o configuraciones adicionales en el conector. Para acceder a estas propiedades, puede utilizar la siguiente línea de código: globals.systemproperties.[nombrePropiedad]. Tenga en cuenta que los corchetes no hacen parte de la línea de código (por ejemplo: globals.systemproperties.SERVER)

 

CustomConnector10

 

Para los parámetros de tipo Connector, usted podrá definir una lista de valores. Para hacerlo, ingrese cada uno de los posibles valores en el campo de valor por defecto (default value) y presionando Enter después de cada uno:

 

CustomConnector11

 

Autenticación: en esta sección se definen los parámetros de seguridad que se van a usar dentro de las acciones, como por ejemplo, usuario, contraseña, clientId, clientSecret, etc. Para acceder a estas propiedades, puede utilizar la siguiente línea de código: globals.authdata.[nombrePropiedad]. Tenga en cuenta que los corchetes no hacen parte de la línea de código (por ejemplo: globals.authdata.USER)

 

CustomConnector12

 

Errores: en esta sección se definen mensajes de error personalizados. La definición de parámetros de error, le permite definir un listado conocido de errores para un mejor manejo de excepciones dentro de la lógica de su propio conector, mejorando así la experiencia de usuario. Para definir una propiedad de este tipo, se deben llenar los campos de Key, el cual es el identificador único del error, y Value, que corresponde al mensaje de error que se va a mostrar. Para acceder a estas propiedades, debe utilizar el siguiente código:

 

var bizagiUtil = require("bz-util");
var ERROR = bizagiUtil.error;
LOG.error(ERROR("<Key>", [Params]));

 

La función ERROR recibe dos parámetros: la llave definida en el error, y un arreglo de strings donde se envían los parámetros que se quieren resolver. En ese orden de ideas, el código anterior quedaría de la siguiente manera para este ejemplo:

 

var bizagiUtil = require("bz-util");
var ERROR = bizagiUtil.error;
LOG.error(ERROR("MYCUSTOMERROR.REQUIRED", ["ID"]));

 

CustomConnector13

 

Al definir un nuevo código único y mensaje de error (para poderlo utilizar dentro de su implementación posteriormente), tenga en cuenta que Bizagi ya provee por defecto una serie de códigos de errores comunes para su uso.

 

ConnectorErrors

 

No deberá nombrar nuevos errores con los códigos de errores ya existentes, que se listan a continuación:

GLB.EXCEPTION

GLB.IS_NOT_A

GLB.IS_NOT_AN

GLB.UNKNOW_ACTION

GLB.RESOURCE_REDIRECT

GLB.RESOURCE_NOT_FOUND

GLB.RESPONSE_ERROR

VAL.REQUIRED_PARAM

VAL.REQUIRED_ELEMENT

VAL.REQUIRED_PARAMS

VAL.PARAM_TYPE

 

Usando el Proxy global

Si su conector personalizado está diseñado para usar la configuración del Proxy es necesario que usted configure el conector para que funcione correctamente con el Proxy. Para hacerlo, el framework envia un objetivo Proxy dentro de los parámetros globales de la función invoke. La estructura del objeto Proxy es la siguiente:

 

tryEstructura del objeto Proxy
{
 "globals": {
   ...
   "proxy": {
     "isEnable": boolean,
     "password": string,
     "port": string,
     "url": string,
     "useAuthentication": boolean,
     "username": string,
     "allowedIps": [
       string
     ]
   }
 }
}

 

Con este objeto es posible programar la petición HTTP usando el Proxy, como en el siguiente ejemplo:

 

ejemplocodigoEjemplo Proxy
var bizagiUtil = require('bz-util');
var REQUIRED = bizagiUtil.REQUIRED;
var ERROR = bizagiUtil.error;
var RESPONSE = bizagiUtil.getResponse;
var request = REQUIRED("request");

function invoke(globals, actionName, data, authenticationType, LOG, callback) {
 ...
 const proxyUrl = globals.proxy ? globals.proxy.url : null;
 request({
   url: data.inputs.input.url,
   method: "POST",
   proxy: proxyUrl,
   ...
 }, () => {
   ...
 })
 ...
}

exports.invoke = invoke;

 

Cómo probar su conector

La opción de Test en el Editor de conectores le permite probar las acciones de un conector sin tener que descargarlo y ejecutarlo en el Portal de Trabajo.

Para probar la acción de su conector, complete los siguientes pasos:

 

1. Configure la acción del conector. Tenga en cuenta que dependiendo de la acción que usted vaya a probar, deberá configurar más parámetros, tales como parámetros globales, entradas o salidas.

 

CustomConnector32

 

2. Para este ejemplo, la acción recibe como parámetro un token como parámetro global. Para probar el conector, es necesario darle un valor a este parámetro.

 

CustomConnector33

 

CustomConnector34

 

3. Haga clic en el botón de Test.

 

CustomConnector35

 

Si la definición de la acción es correcta, la pestaña de test outputs mostrará la salida que recibiría del conector en ejecución.

 

CustomConnector36