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:
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.
2. Acciones y área de trabajo
En esta sección se despliegan las acciones definidas para el conector mientras se muestran sus propiedades.
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.
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.
|
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. |
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.
|
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 
al costado derecho. Para agregar nuevos elementos a una estructura particular, haga clic sobre el ícono . 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).
Agregue uno a uno los parámetros de entrada hasta obtener la estructura deseada.
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):
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.
Los parámetros globales le permiten definir propiedades genéricas para ser usadas en todas las acciones del conector.
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).
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)
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:
•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)
•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"]));
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.
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
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:
 | Estructura 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:
| Ejemplo 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.
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.
3. Haga clic en el botón de Test.
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.
Last Updated 1/9/2024 11:24:52 AM