Introducción

Al crear sus propios conectores y específicamente al ser de tipo Personalizado, usted deberá escribir el código de la implementación, como se describe en Conectores Personalizados.

Para hacerlo, es importante que se apoye en lo posible, en el API que Bizagi provee para los conectores.

Punto de partida y objetos del API

El punto de partida al crear sus propios conectores es la implementación de la función invoke que incluye Bizagi para cada acción nueva:

CustomConnector24

Podrá incluir sus propias funciones adicionales de considerarlo necesario.

Sin embargo, tenga presente que siempre Bizagi invocará la función invoke como punto de partida cuando Bizagi ejecuta una acción de un conector.

Dentro de esta función podrá incluir el código que soporte Javascript y que provea el API de Bizagi.

Así mismo, en los parámetros de entrada de la función, usted cuenta con los siguientes objetos:

OBJETO	TIPO	DESCRIPCIÓN Y EJEMPLO
globals	Object	Contiene todos los parámetros definidos dentro de las pestañas en el panel de la derecha: de Conector, Autenticación y Errores. Estos parámetros se acceden de acuerdo a esas categorías anteriores, de esta manera: •Parámetros de tipo Conector : globals.systemproperties.[your_parameter] •Parámetros de tipo Autenticación: globals.authdata.[your_parameter] Para mayor información sobre parámetros globales, haga clic aquí. Adicionalmente, el nombre del proyecto se accede mediante globals.projectname
actionName	String	Contiene el nombre de la acción que se está invocando. Aunque no es comúnmente necesitada, el propósito de tener esta información es también ayudar al diagnóstico (trazas en la bitácora).
data	Object	Contiene todos los valores que hacen parte de los parámetros de entrada y de salida predefinidos. Se acceden como: •data.inputs.input.[structure_inside_input] (y según como se haya definido la estructura de entradas) •data.outputs.output.[structure_inside_output] (y según como se haya definido la estructura de salidas) o data.outputs.error.[structure_inside_error]
authenticationType	Object	Contiene los tipos de autenticación soportados en su implementación. Aunque no es comúnmente necesitada, el propósito de tener esta información es para revisar estos valores en caso de que en su acción desee utilizar más de un método de autenticación (basic, digest o oauth2). Ninguno (None) puede ser válido también.
LOG	Object	Habilita el uso de las trazas. Provee un conjunto de funciones para que usted pueda registrar detalle en diferentes niveles de trazas (para propósitos de depuraración, usando niveles "debug", "info", "error", "warn" o "trace"). Por ejemplo: LOG.info('detalle');
callback	Function	Hace referencia a la función llamada de vuelta (callback) que usted debe incluir para notificar a Bizagi que la invocación a finalizado. Recibe información obligatoria tipo JSON y su uso típicamente es: •callback(response_information); para una invocación exitosa •callback(error); si ocurre un error Para más información sobre la función callback, haga clic aquí.

API (bz-util)

El API de Bizagi que usted utilizar en los conectores Personalizados es introducido por la librería bz-util la cuál encontrará siempre importada en un conector nuevo (a partir de bizagiUtil, bajo la línea donde se visualiza: var bizagiUtil = require ('bz-util'); ).

Consulte la siguiente tabla para conocer los métodos.

MÉTODOS Y SUS ENTRADAS	DESCRIPCIÓN Y DATOS DE SALIDA	EJEMPLO
REQUIRED (string moduleName)	Importa un librería de node.js (especificada como moduleName). Retorna una instancia del objeto de esa librería.	El siguiente ejemplo importa una librería de node.js llamada twit, hacia una variable XService para poderla utilizar: var XService = bizagiUtil.REQUIRED('twit');
getResponse (JSON response, JSON error, integer statuscode, string errormsg)	Le permite formatear una respuesta exitosa de manera que se envie de vuelta a Bizagi. La respuesta exitosa debe ir en el parámetro response de tipo JSON, mientras que las excepciones requieren ser llenadas en el parámetro error de tipo JSON, y un mensaje de error legible debe ir en errormsg. Ya sea para una invocación exitosa o cuando se presentan errores, se recomienda definir sus propios códigos de estatus, dado en statuscode.	Este ejemplo considera una invocación exitosa: var success = bizagiUtil.getResponse({data: {key: ‘s22ssoj44sfj’}}, null, 200, null); Este ejemplo considera un error durante la invocación: var error = bizagiUtil.getResponse (null, {error: ‘invalid_request’}, 400, ‘The request is missing a required authentication parameter’);
validator.isValidDataJson (JSON json)	Valida si un JSON está bien formado, es decir, compatible al estándar JSON para el parámetro data. Retorna un objeto con elemento success en verdadero (true) si así sucede, o retorna falso (false) de lo contrario al enviar la salida JSON o estructura del error hacia data.outputs.output o data.outputs.error respectivamente. La estructura exacta del objeto retornado es: { response: { outputs: { output: {}, error: {} } }, success: true\|false, connectorstatuscode: 200\|?, errormessage: "" }	Este ejemplo valida el contenido en globales: var result = bizagiUtil.validator.isValidDataJson(data); if (result.success) { data = result.response.outputs.output; } else´{ callback(result); return; }
validator.isValidGlobalsJson (JSON globals)	Valida si un JSON está bien formado, es decir, compatible al estándar JSON para el parámetro globals. Retorna un objeto con elemento success en verdadero (true) si así sucede, o retorna falso (false) de lo contrario al enviar la salida JSON o estructura del error hacia response.outputs.error. La estructura exacta del objeto retornado es: { response: { outputs: { output: { globals {...} }, error: {} } }, success: true\|false, connectorstatuscode: 200\|?, errormessage: "" }	Este ejemplo valida el contenido en globales: var result = bizagiUtil.validator.isValidGlobalsJson(globals); if (result.success) { globals = result.response.outputs.output; } else´{ callback(result); return; }
error (string errorId, object[] detail)	Le permite formatear un error de manera que lo atrape y le de manejo. La información del error se estructura con un identificador principal (errorId) y adicionalmente con un código y mensaje detallado.	En este ejemplo se formatea un mensaje de error con código de estatus 500: var errormsg = bizagiUtil.error('OBJECT_REF', [500, 'Unsupported parameter value or unknown data']);
LOG.error (object[] detail)	Registra el detalle en la bitácora designada, con trazas a nivel de error. Nótese que podrá concatenar múltiples textos dentro de un arreglo.	Los siguientes son 2 ejemplos diferentes: •LOG.error (['Error 009']); •LOG.error ('[My connector] Error:', error, {'invalid request'} ]);
LOG.debug (object[] detail)	Registra el detalle en la bitácora designada, con trazas a nivel debug. Nótese que podrá concatenar múltiples textos dentro de un arreglo.	El mismo uso de LOG.error()
LOG.warn (object[] detail)	Registra el detalle en la bitácora designada, con trazas a nivel de alertas. Nótese que podrá concatenar múltiples textos dentro de un arreglo.	El mismo uso de LOG.error()
LOG.trace (object[] detail)	Registra el detalle en la bitácora designada, con trazas de nivel básico. Nótese que podrá concatenar múltiples textos dentro de un arreglo.	El mismo uso de LOG.error()
LOG.info (string[] message)	Registra el detalle en la bitácora designada, con trazas de nivel informativo. Nótese que podrá concatenar múltiples textos dentro de un arreglo.	El mismo uso de LOG.error()

Siempre utilice las bitácoras y capacidades de registrar trazas que ofrece el API de Bizagi, las cuales podrán ser prendidas y apagadas por medio de configuración en Bizagi.

Asegúrese de definir acertadamente tal información (la cantidad justa de trazas, y que sea útil y legible), y de no emplear otros destinos de bitácora adicionales.

Función Callback

La función callback se encarga de notificar a Bizagi cuando la invocación de una acción ha terminado. Dado que la comunicación entre el framework del conector y el conector es asíncrona, esta función se usa como puente de comunicación para cuando la acción termina su ejecución.

La función callback recibe como parámetro un objeto de tipo response, el cual tiene los siguientes parámetros:

•output: Objeto JSON con la misma estructura definida en las salidas de la acción. Usted debe incluir este parámetro únicamente para respuestas exitosas, de lo contrario, su valor es null.

•errorOutput: Objeto JSON con la misma estructura definida en las salidas de la acción. Usted debe incluir este parámetro únicamente para respuestas no exitosas, de lo contrario, su valor es null.

•CódigoDeEstado: Código que indica el estado de una respuesta. Le recomendamos utilizar la siguiente nomenclatura de códigos para las respuestas de sus acciones:

oCódigos de estatus desde 400 a 500: Para declarar inconvenientes durante la autenticación.

oCódigos de estatus negativos: Para declarar excepciones en la lógica de su invocación.

oCódigos de estatus 200: Debería ser el que representa una invocación exitosa.

•TítuloDeError: mensaje que se muestra cuando ocurre un error. Usted puede utilizar el mismo valor que se encuentra en errorOutput.error. Sólo debe incluir este parámetro para respuestas no exitosas.

Usando el objeto Response en la función callback

El siguiente código ilustra un ejemplo de cómo llamar la función callback definiendo una respuesta exitosa:

var output = {
id: 1,
name: "First name"
}
var success = RESPONSE(output, null, 200);
callback(success);

En este caso, los parámetros output, errorOutput y codigoDeEstado se incluyen en el objeto response.

Si ocurre un error en la ejecución de la acción, la definición del response no exitoso en la función callback iría de la siguiente manera:

var errorOutput = {
error: "Not Found",
message: "The specified user does not exist."
status: 404
}
var error = RESPONSE(null, errorOutput, 404, errorOutput.error);
callback(error);

En este caso, los parámetros output, errorOutput, codigoDeEstado y TítuloDeError se incluyen en el objeto response.

Tenga en cuenta que la función callback no termina la ejecución de una acción. Por lo tanto, debe ser llamada al final de la acción.

Implementación correcta	Implementación incorrecta
if (response.success) { var output = { id: 1, name: "First name" } var success = RESPONSE(output, null, 200); callback(success); } else { var errorOutput = { error: "Not Found", message: "The specified user does not exist." status: 404 } var error = RESPONSE(null, errorOutput, 404, errorOutput.error); callback(error); } En este escenario, la función callback se llama una vez. Si la respuesta es exitosa, o si ocurre algún error.	if (response.success) { var output = { id: 1, name: "First name" } var success = RESPONSE(output, null, 200); callback(success); } var errorOutput = { error: "Not Found", message: "The specified user does not exist." status: 404 } var error = RESPONSE(null, errorOutput, 404, errorOutput.error); callback(error); En este caso, la función de callback se llama dos veces. En su lugar, utilice una estructura if-else para evaluar si la respuesta es exitosa o no:

Implementación correcta

Implementación incorrecta

if (response.success) {
var output = {
id: 1,
name: "First name"
}
var success = RESPONSE(output, null, 200);
callback(success);
}

else {
var errorOutput = {
error: "Not Found",
message: "The specified user does not exist."
status: 404
}
var error = RESPONSE(null, errorOutput, 404, errorOutput.error);
callback(error);
}

En este escenario, la función callback se llama una vez. Si la respuesta es exitosa, o si ocurre algún error.

if (response.success) {
var output = {
id: 1,
name: "First name"
}
var success = RESPONSE(output, null, 200);
callback(success);
}
var errorOutput = {
error: "Not Found",
message: "The specified user does not exist."
status: 404
}
var error = RESPONSE(null, errorOutput, 404, errorOutput.error);
callback(error);

En este caso, la función de callback se llama dos veces. En su lugar, utilice una estructura if-else para evaluar si la respuesta es exitosa o no:

Manejo de errores

Cuando se define una acción en un conector, es importante detectar y manejar correctamente los errores que pueden ocurrir. Las siguientes secciones ilustran algunos escenarios para manejar errores correctamente.

Entradas requeridas

Cuando una entrada es marcada como requerida, usted puede verificar que efectivamente se envíe. Para hacer esto, bz-util ofrece el módulo de validator, el cual recibe un JSON con los parámetros requeridos y valida que se estén enviando como entradas a la acción. En caso que el validator encuentre una entrada vacía, indefinida o nula, genera un objeto response no exitoso con las entradas faltantes que se deben enviar.

El siguiente código ilustra cómo definir el objeto de validator y cómo utilizarlo cuando se llama una acción

Definición del Validator

{
"nombreParámetro1": "ruta al parámetro, por ejemplo: data.inputs.input.nombreParámetro1",
"nombreParámetro2": "ruta al parámetro, por ejemplo: data.inputs.input.nombreParámetro2"
}

Usando el validator en una acción:

var bizagiUtil = require('bz-util');
var error = bizagiUtil.validator.requiredParameters({
fileId: data.inputs.input.fileId,
destinationPath: data.inputs.input.destinationPath
});
if(error){
LOG.error(['[BOX.'+actionName+']', 'Error:', error]);
return callback(error);
}

Manejo de errores en Promesas

Una promesa es un objeto que representa la terminación de una operación asíncrona, la cual puede ser exitosa o no. El manejode errores en promesas es bastante simple. Sin embargo, tenga en cuenta que en este caso una estructura clásica de try-catch no funciona.

Para manejar los errores en promesas, tiene dos opciones:

1.Usar directamente la función catch que provee la promesa:

axios.get(url)
.then((response) => { /* code here */ })
.catch((error) => { /* some error handling */ });

2.implementar una estructura de try-catch haciendo uso de la función await:

try {
let response = await axios.get(url);
} catch (error) {
// some error handling
}

Para mayor información sobre cómo manejar errores en promesas, haga clic aquí.