Introducción
El Editor de Conectores de Bizagi le permite crear conectores desde cero. Usted puede crear dos tipos de conectores: conectores asistidos REST, que no requieren código (el enfoque preferido), y Conectores Personalizados, que le permiten incluir bibliotecas de terceros e implementar su propio código.
Este artículo describe cada sección de la interfaz utilizada para crear un Conector Personalizado.
Opciones de la interfaz de usuario explicadas
Ya sea que usted esté creando un conector nuevo o abriendo uno existente, el área de trabajo muestra las siguientes opciones:
1. Información general del Conector
Esta sección contiene información general sobre el conector: su nombre, versión, autor, URL del sitio web, descripción e ícono.
Usted puede modificar esta información en cualquier momento.
2. Acciones y área de trabajo
Esta sección muestra todas las acciones definidas para el conector junto con sus propiedades.
El panel izquierdo lista las acciones y le permite gestionarlas (crear nuevas acciones o eliminar acciones existentes). Usted puede editar el nombre de una acción haciendo clic en el ícono del lápiz, o eliminarla utilizando el ícono de la papelera.
Cuando usted selecciona una acción, el área de trabajo a la derecha muestra los detalles de implementación de esa acción.
La sección inferior muestra los detalles relacionados con las entradas y salidas.
Esta sección define las entradas y salidas de una acción. Ambas se definen de la misma manera.
Usted debe definir una estructura jerárquica (compatible con JSON o XML) con los tipos de datos requeridos por su servicio, ya sean entradas consumidas por el servicio externo o salidas retornadas por este.
|
Los tipos de datos deben coincidir con aquellos esperados por el sistema externo o la API de la aplicación. Los tipos de datos simples disponibles incluyen: •Booleano •Byte •Fecha •Decimal •Doble •Entero •String
Los tipos de datos complejos deben definirse como Objeto, permitiéndole incluir elementos internos que pueden ser tipos simples u otros Objetos anidados. |
Por ejemplo, considere la siguiente estructura de entrada:
Vista JSON:
{
"Main_element": {
"Information1": "String",
"Information2": "String"
},
"Unbount_element": {
"Information3": "String"
}
}
Vista XML:
<?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>
Usted tiene dos opciones para definir esta estructura en el Editor de Conectores:
3.1. Opción Autogenerar
Haga clic en Autogenerar, seleccione un archivo JSON o XML, y el Editor de Conectores construye automáticamente la estructura.
|
Cuando usa Autogenerar, solo se soportan los tipos de datos Objeto y String. Si su estructura contiene otros tipos (por ejemplo, Doble), cargue primero el archivo y luego ajuste manualmente esos campos. |
3.2. Definición manual
Usted puede ingresar la estructura manualmente. Los elementos de tipo Objeto pueden contener elementos adicionales. Para agregar nuevos elementos, haga clic en el ícono 
. Para cada nuevo elemento, especifique:
•Nombre
•Tipo de dato
•Si es una lista (múltiple) o de ocurrencia única
Agregue los parámetros uno por uno hasta completar la estructura.
4. Librerías
Esta sección le permite gestionar las librerías utilizadas en el conector. Las librerías importadas, junto con sus dependencias internas, aparecen en la lista, junto con la librería incorporada de Bizagi (bz-util).
Aunque usted importe la librería aquí, aún debe referenciarla explícitamente en su código (similar a importar en Java o usar en C#).
Los parámetros globales le permiten especificar propiedades genéricas que pueden ser utilizadas por cualquier acción del conector.
Usted puede agregar, eliminar o editar estos parámetros. Cada parámetro incluye las propiedades nombre, valor predeterminado, requerido y Encriptación de campos.
Existen tres tipos de parámetros globales:
5.1. Parámetros del conector
Estos parámetros permanecen constantes durante la ejecución de una acción (por ejemplo, la URL del sistema externo).
También pueden variar por ambiente (Desarrollo, Prueba, Producción), permitiéndole configurar cada ambiente en Bizagi Studio sin afectar otros mapeos o configuraciones del conector.
Para acceder a estos parámetros, use:
globals.systemproperties.[PropertyName]
|
Los corchetes no hacen parte del código (ejemplo, globals.systemproperties.SERVER). |
Los parámetros tipo Conector también pueden definirse como una lista de valores. Para hacerlo, ingrese cada valor en el campo Valor(es) predeterminado(s) y presione Enter para agregar múltiples valores.
5.2. Parámetros de autenticación
Aquí usted define los parámetros relacionados con la seguridad utilizados por las acciones (usuario, contraseña, clientId, clientSecret, etc.).
Para acceder a ellos, use:
globals.authdata.[PropertyName]
|
Los corchetes no hacen parte del código (ejemplo, globals.authdata.USER) |
5.2.1. Token de impersonación
El Token de impersonación es un token de acceso basado en OAuth2 que permite que el conector actúe en nombre de un usuario autenticado al llamar servicios externos protegidos.
Al editar un Conector Personalizado, una variable llamada impersonationToken está disponible dentro de la acción GetService en la función invoke del Editor de Conectores.
Como muestra la imagen, el valor es:
globals.authdata.impersonationToken
Usted puede usar este token para solicitar un nuevo token de impersonación a un proveedor externo y luego acceder a recursos protegidos.
Ejemplo simplificado:
var bizagiUtil = require('bz-util');
var REQUIRED = bizagiUtil.REQUIRED;
var ERROR = bizagiUtil.error;
var RESPONSE = bizagiUtil.getResponse;
const axios = REQUIRED('axios');
/** Request impersonation token */
function login(globals, LOG) {
return new Promise(function (resolve, reject) {
var authData = globals.authdata;
var auth = "Basic " + new Buffer(authData.USERNAME + ":" + authData.PASSWORD).toString("base64");
var endPointUrl = 'https://<server>/oauth2/v2.1/token';
var requestArgs = {
method: 'POST',
url: endPointUrl,
json: true,
headers: {
'Accept': 'application/json',
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': auth
},
form: {
grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
assertion: authData.impersonationToken
}
};
axios.request(requestArgs)
.then((response) => {
resolve(response.data);
})
.catch((err) => {
reject(err);
});
});
}
/** Main function */
function invoke(globals, actionName, data, authenticationType, LOG, callback) {
login(globals, LOG).then(function (data1) {
var endPointUrl = 'https://<server>/customers/basic-info/raw';
var requestArgs = {
method: 'GET',
url: endPointUrl,
json: true,
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + data1.access_token
}
};
axios.request(requestArgs)
.then((response) => {
var result = response.data;
var success = RESPONSE(result, null, response.status);
callback(success);
})
.catch((err) => {
var e = RESPONSE(null, { status: err.status, message: err.message }, err.status);
callback(e);
});
}).catch(function (err) {
var e = RESPONSE(null, { status: err.status, message: err.message }, err.status);
callback(e);
});
}
exports.invoke = invoke;
Cuando configure el Conector Personalizado en Bizagi Studio, aparece una casilla de verificación Habilitar impersonación en la configuración de autenticación.
Cuando está habilitada, Bizagi envía automáticamente el token de impersonación al conector.
|
La casilla de verificación Habilitar impersonación también es visible en la Management Console, en las configuraciones de Conectores.
|
|
•la funcionalidad de impersonación está habilitada de forma predeterminada; sin embargo, puede deshabilitarse mediante un ticket a Soporte. •Para que la impersonación funcione correctamente, el proyecto debe usar autenticación OAuth2. Para más información, consulte Autenticación Bizagi.
|
5.3. Parámetros de error
Usted puede definir mensajes de error personalizados. Definir parámetros de error le permite mantener una lista de errores conocidos identificados por códigos únicos, mejorando el manejo de errores en la lógica del conector y la experiencia del usuario.
Cada parámetro de error incluye una llave (identificador único) y un valor (el mensaje que se mostrará).
Para acceder a estos parámetros, use:
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 parámetro y un arreglo de Strings que representan los parámetros a resolver. Ejemplo:
var bizagiUtil = require("bz-util");
var ERROR = bizagiUtil.error;
LOG.error(ERROR("MYCUSTOMERROR.REQUIRED", ["ID"]));
Bizagi ya proporciona un conjunto de códigos de error predefinidos.
NO reutilice los siguientes códigos, ya que ya están en uso:
•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
Uso de la configuración de proxy
Si su Conector Personalizado debe usar una configuración Proxy, Bizagi envía un objeto proxy dentro de los parámetros globales de la función invoke.
La estructura del objeto proxy es la siguiente:
 | Proxy object structure { "globals": { ... "proxy": { "isEnable": boolean, "password": string, "port": string, "url": string, "useAuthentication": boolean, "username": string, "allowedIps": [ string ] } } } |
Con este objeto es posible programar la solicitud HTTP usando el proxy, como en el siguiente ejemplo:
| Proxy example 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 Test en el Editor de Conectores le permite probar acciones sin descargar el conector ni ejecutarlo en el Portal de Trabajo.
Para probar la acción de su conector:
1. Configure la acción. Dependiendo de lo que desee probar, puede necesitar configurar parámetros globales, entradas o salidas.
2. Si la acción usa un parámetro global (por ejemplo, un token), asigne un valor de prueba a ese parámetro.
3. Haga clic en Test.
Si el conector está definido correctamente, la pestaña TEST OUTPUTS se abre y muestra la salida que el conector retornaría durante la ejecución.
Last Updated 11/18/2025 11:56:42 PM