API de Bizagi para conectores

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Asistente de Procesos > Integrar > Integración con aplicaciones > Integrar APIs o código personalizado en Bizagi > Conectores de Bizagi > Crear conectores > Conectores Personalizados >

API de Bizagi para conectores

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:

 

Invoke fn

 

 

note_pin

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]

 

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

Manages use of the tracing log.

It provides a set of functions for you to write into the logged detail in different tracing levels (debug, info, error, warn or trace). For example:

LOG.info('detailed_stack');

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

 

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 TwitterService para poderla utilizar:

 

var TwitterService = 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: ""

}

This example validates the content in globals:

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: ""

}

This example validates the content en globals:

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()

 

 

Mejores prácticas

Considere las siguientes prácticas recomendadas:

 

1. Importar librerías

Siempre utilice REQUIRED() en vez de require() para importar sus librerías.

La única librería (a manera de excepción) que se importa usando require() es precisamente el API de Bizagi API, tarea que se realiza en la primera línea de código visible:

var bizagiUtil = require('bz-util');

A partir de ese punto ya se cuenta con el método REQUIRED() de la librería bz-util, que le permitirá importar las otras librerías de la mejor manera (haciendo que Bizagi se asegure de validar dependencias que puedan estar usando sus librerías).

Por ejemplo se debe usar:

var TwitterService = bizagiUtil.REQUIRED('twitter_library');

 

2. Trazas y detalle en bitácoras

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.

 

3. Nomenclatura del código de estatus

Recomendamos utilizar los siguientes rangos de códigos para proveer unos status de manera estándar.

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

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

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

 

4. Bz-util sin cambios

Recomendamos enfáticamente evitar modificar la librería bz-util (nótese que esta librería se provee as-is).

Las modificaciones realizadas a esta librería no se soportan por Bizagi.