Introducción
Existen dos tipos de conectores: Asistidos REST y Personalizados, como se indica en Crear conectores.
Esta sección presenta una guía de pasos de alto nivel que se deben considerar cuando se desean crear conectores personalizados.
Antes de comenzar
Es muy importante que primero se tenga conocimiento del API del sistema o aplicación externa a la que desea conectarse.
Ponga especial cuidado al tipo de autenticación que el API de esa aplicación externa soporta.
Esto significa, que usted deberá consultar la documentación oficial de dicho aplicación externo antes de comenzar con el desarrollo de un conector.
La información acerca del tipo de autenticación soportada le proporcionará una indicación para determinar si puede crear un conector de tipo Asistido REST, o si por el contrario, es necesario un conector de tipo Personalizado.
Para mayor información sobre cuándo crear un conector Personalizado, consulte los Métodos de autenticación y conectores tipo REST.
Pasos para crear conectores Personalizados
Cuando se desea crear un conector Personalizado, los siguientes son los pasos generales que debe considerar:
1.Asegúrese de tener una cuenta válida con acceso autorizado a su aplicación externa desde otras aplicaciones (p.e, un nombre de usuario y contraseña válida, además de tokens de acceso u otras configuraciones en su aplicación externa).
2.Ubique una librería de conectividad en npm, para que sea reusable por su conector.
Asegúrese de encontrar una en www.npmjs.com que sea confiable (p.e analizando el número de descargas, inconvenientes reportados y documentación, etc) y que la pueda utilizar de acuerdo a su licencia (p.e. tipo MIT).
3.Empaquete la librería de conectividad.
Si ya cuenta con una librería que cumpla con sus requerimientos, asegúrese de descargarla y empaquetarla vía npm (el empaquetado final debe ser un .zip). De lo contrario, usted deberá implementar dicha funcionalidad de conectividad y empaquetarla como una librería reutilizable/portable.
Para descargar y empaquetar una librería, instale y utilice localmente npm (tal como se describe en Perfil requerido, conceptos y herramientas.
|
No descargue la librería directamente desde el navegador, dado que podrá no descargarse con todas sus dependencias (si esa librería usa a su vez, otras que no están empaquetadas en su interior). Esta práctica resultaría en una librería incompleta/no portable. |
Al empaquetar la librería utilice las opciones de consola con una cuenta de administrador, como se describe a continuación (a través del comando npm install <library-to-download> --greedy ).
Nótese que usted deberá ejecutar este comando desde la ruta donde desea descargar la librería; de lo contrario, ésta quedará en la ruta de los archivos de system32.
|
Tenga presente que el archivo comprimido final del empaquetado (el .zip), deberá ser compatible con la siguiente estructura: 1. Todas las dependencias y librerías deben estar en una estructura plana; que no sea recursiva ni jerárquica. 2. No debe existir una carpeta intermedia. El .zip deberá extraer las múltiples carpetas al mismo nivel (sean librerías o dependencias).
|
4.Utilice el Hub de Integración para crear un nuevo conector de tipo, e ingrese los detalles relevantes.
5.Importe esta librería de conectividad.
6.Configure los parámetros globales.
Tenga en cuenta que existen tres tipos de parámetros globales: Conector, Autenticación and Errores. Al configurar estos parámetros, no los defina todos en la misma pestaña. En su lugar, utilice cada una de las pestañas de acuerdo con la naturaleza del parámetro que se va a definir, como se describe en Parámetros globales.
Los parámetros obligatorios por definir son los de Autenticación:
Si la autenticación de por si debe ser personalizada, usted podrá editar el archivo auth.js
Presione el botón </> auth.js para abrir el archivo de auth.js.
Cuando se edita el archivo auth.js, usted puede incluir validaciones adicionales a la autenticación, configurar distintos tipos de protocolos a aquellos ofrecidos o enviar información directamente a Bizagi en la respuesta del método. También, cuando el archivo auth.js es modificado para personalizar la autenticación, este código se ejecutará cada vez que el conector sea invocado.
Tenga presente que este método siempre devolverá un objeto de tipo callback, el cual se concatenará con el globals.authdata. El siguiente ejemplo muestra cómo se obtiene un token de autenticación a través del archivo auth.js, y cómo es posteriormente usado en una acción específica.
Obtención de token a través del archivo auth.js:
var bizagiUtil = require('bz-util');
var log = bizagiUtil.isLoggerEnabled;
var RESPONSE = bizagiUtil.getResponse;
var request = REQUIRED("request");
function invoke(globals, LOG, callback){
var authData = globals.authdata;
var systemProperties = globals.systemproperties;
var projectName = globals.projectname;
var argsAuth = {
method: 'POST',
url: 'https://api.box.com/oauth2/token',
form:{
user: globals.authdata.user,
password: globals.authdata.password
}
}
request(argsAuth,function(err, response, body){
// ...
// some error handling
// ...
var reply = RESPONSE({
token: body.access_token
}, null, 200);
callback(reply);
});
}
exports.invoke = invoke;
Token de autenticación utilizado en una acción:
var bizagiUtil = require('bz-util');
var REQUIRED = bizagiUtil.REQUIRED;
var ERROR = bizagiUtil.error;
var RESPONSE = bizagiUtil.getResponse;
var request = REQUIRED("request");
/**
* @author Bizagi
*/
function invoke(globals, actionName, data, authenticationType, LOG, callback) {
let args = {
method: 'POST',
url: 'https://api.box.com/2.0/files',
headers: {
'Authorization': 'Bearer ' + globals.authdata.token, // token got from auth.js execution
}
}
request(args, function (err, response, body) {
// ...
// some functional code here
// ...
});
}
exports.invoke = invoke;
De manera opcional, defina los parámetros de Conector y de Errores.
7.Cree por lo menos una acción y especifique los detalles.
|
Le recomendamos que utilice la siguiente nomenclatura de código de estado para cuando codifique sus acciones, para los estados de error que defina en sus parámetros y para cuando utilice el botón Auth.js para personalizar la autenticación de su sistema externo.: Códigos de estado desde 400 a 500: Para declarar inconvenientes durante la autenticación. Códigos de estado negativos: Para declarar excepciones en la lógica de su invocación. Códigos de estado 200: Debería ser el que representa una invocación exitosa. |
8.Defina las entradas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa. Recuerde que puede hacer esto usando el botón de autogenerar, o manualmente, como se describe aquí.
9.Defina las salidas según sean necesarias para su conector y sean soportadas por el API de su sistema/aplicación externa. Recuerde que puede hacer esto usando el botón de Autogenerate, o de manera manual, como está descrito aquí.
10.Implemente la función llamada invoke.
Escriba su propio código para implementar cómo debe instanciarse ese método desde la librería que se importó (hacia el sistema/aplicación externa).
Ingrese su código dentro de la función predefinida invoke, haciendo uso del API de Bizagi para conectores.
|
Si la acción utiliza una de las librerías importadas en el paso 5, tenga en cuenta la siguiente consideraciones: •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('twit'); •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. |
11.Guarde el conector.
Una vez que lo haga, siga los pasos de su instalación para probarlo desde Bizagi Studio, como se describe en Instalar y configurar conectores.
|
De manera adicional y como directrices de mejores prácticas, considere estas recomendaciones:
1. Un conector ya descargado tendrá en su interior las librerías propietarias de Bizagi (bz-util), las cuáles proveen el API para los conectores así como otro métodos y el framework en general que les permite conectarse a servicios REST. Usted no deberá modificar esta librería y deberá tener en cuenta que Bizagi Ltd no soporta ni garantiza la compatibilidad en conectores que utilicen una librería modificada de bz-util. En cualquier momento, Bizagi Ltd podrá modificar o cambiar el contenido de la librería bz-util o adicionales, que se incluyan para la ejecución adecuada y segura de los conectores.
2. Usted será responsable de incluir información de licencia en los archivos read-me dentro de los conectores (o de manera alternativa, en la descripción del conector). Recuerde que algunas de las librerías que usted pueda utilizar dentro de sus conectores -según estén disponibles en www.npmjs.com- podrán exigir un enlace de referencia a ellas o algunas otras cláusulas de su licencia particular (aún cuando la mayoría son de licencia MIT). |
Last Updated 10/16/2024 11:38:56 AM