Desarrollo de Scripts en Flokzu
Introducción
En Flokzu sabemos que muchas veces es necesario dotar de cierta inteligencia a los formularios, tanto para realizar cálculos complejos, como para realizar validaciones, detección de errores, definir lógica condicional para ocultar/mostrar campos, entre muchas otras posibilidades.
Con esto en mente, en Flokzu hemos desarrollado un motor de scripts Script Engine que provee varias funciones predefinidas a nivel de formulario para poder realizar todo tipo de validaciones, detección de errores y algoritmos utilizando un lenguaje ampliamente reconocido como JavaScript.
“En Flokzu, los scripts deben ser definidos utilizando JavaScript como lenguaje de programación y puede aprovecharse todo el potencial que el mismo ofrece. Las funciones y atajos definidos en esta guía son una ayuda para agilizar el desarrollo de algoritmos y funciones de lógica condicional.
Metodología de desarrollo
En Flokzu, hemos desarrollado una metodología de desarrollo para scripts que es fácil de seguir. La lógica debe definirse dentro de distintas funciones JavaScript y luego asociar esas funciones con distintos eventos (campo cambia su valor, se presionó un botón, etc) a través del uso de los "listeners" (ver más abajo).
Las funciones definidas pueden utilizar operaciones internas para manejar la visibilidad, errores y lectura/escritura de campos, la librería Moment.js o jQuery, entre otras funcionalidades.
Para hacer referencia a un campo en las funciones predefinidas siempre debe escribirse el nombre del mismo entre [[ y ]] respetando mayúsculas, minúsculas, espacios y caracteres especiales. Ejemplo: [[Nombre Completo]]
Por último es necesario aclarar que los "listeners" no deben incluirse cuando el script se coloca dentro de un campo de tipo autocalculado "script" ya que allí si se infieren los campos a "escuchar" a diferencia de lo que sucede con los Scripts de tarea.
Funciones disponibles
"Listeners"
IMPORTANTE: Estas funciones permiten "escuchar" cuando un campo cambia (o incluso cuando una columna de una tabla cambia) para en ese momento ejecutar una función que realice cierta lógica. Ejemplo: escuchar cuando el campo "Pasaporte" cambia su valor para verificar que el número sea válido.
"Escuchar" un campo
Cuando el campo escuchado cambie su valor, ejecuta la función.
Flokzu.onChange( [[campo]] , NombreFuncion );"Escuchar" una columna de un campo tabla
Cuando una celda de la columna del campo tabla mencionado cambie su valor, se ejecutará la función. Se debe escribir entre [[ y ]] el nombre del campo luego :: y luego el nombre de la columna.
Flokzu.onTableChange( [[campo::columna]], NombreFuncion );Acciones
Estas funciones se ejecutarán cuando el usuario presione uno de los botones que tiene disponibles para completar la tarea. La función a su vez puede definirse de tal manera de poder identificar cual botón fue presionado (ver ejemplos al final de este post).
Flokzu.onAction( NombreFuncion );Inicialización
Estas funciones se ejecutarán cuando el usuario abra la instancia de proceso. Sirven para definir que sucederá en el momento cero, es decir, antes de modificar ningún campo. Esto aplica tanto a cuando se está iniciando un proceso de cero, como para cuando un usuario abre una tarea en su bandeja.
Flokzu.onInit( NombreFuncion);Visibilidad
IMPORTANTE: Para poder modificar por script la visibilidad de un campo, el mismo debe estar editable a nivel de proceso. Esto es, en la tarea donde se define el script, el campo debe estar marcado como Editable en la pestaña de visibilidad.
Ocultar un campo
Flokzu.setHidden( [[campo]] );Hacer que un campo sea solo lectura
Flokzu.setReadOnly( [[campo]] );Hacer que un campo sea editable (no requerido)
Flokzu.setEditable( [[campo]] );Hacer que un campo sea requerido
Flokzu.setRequired( [[campo]] );Lectura/Escritura de campos
IMPORTANTE: Para poder modificar el valor de un campo usando setFieldValue el mismo debe estar al menos editable a nivel de proceso.
Modificar el valor de un campo (reemplaza el valor actual)
Esta función es válida para todos los tipos de campo salvo los tipos: "Titulo / Encabezado", "Tabla", "Archivo Adjunto", "Autocalculado", "Firma" y "Checklist" que no están soportados por el momento.
Flokzu.setFieldValue( [[campo]] , valor );Obtener el valor de un campo
Esta función es válida para todos los tipos de campo salvo los tipos: "Titulo / Encabezado" y "Tabla" que no están soportados por el momento.
Flokzu.getFieldValue( [[campo]] );Casos especiales de acuerdo al tipo de campo:
Si/No: retorna un boolean (true/false).
Número Entero: retorna un número entero o NaN si el valor del campo no es un número.
Número Decimal: retorna un número con 2 decimales o NaN si el valor del campo no es un número.
Autocalculado: retorna un número con 2 decimales si el valor del campo es un número, número sin decimales si es entero, o el valor del campo en formato String en caso contrario.
Adjunto: retorna el nombre del archivo adjunto o vacío si no hay archivo seleccionado.
Combo Multiselección: opciones seleccionadas separadas por "," o vacío si no hay opciones seleccionadas.
Obtener todos los valores de una columna de un campo tabla
Para iterar los valores, ver ejemplos al final de este post.
Flokzu.getAllColumnValues( [[campo::columna]] );Manejo de errores
IMPORTANTE: El manejo de errores solo puede realizarse dentro de las funciones invocadas desde "onAction". Si se lanza un error desde una función que no se ejecuta "onAction" el mismo no tendrá el efecto deseado.
Al lanzar un error dentro de "onAction" se impide que la tarea se complete. El usuario no podrá avanzar en el proceso hasta tanto no modifique los valores de los campos de forma tal que en el "onAction" la función no lance el error.
Lanzar un error para un campo
El mensaje debe describir que sucedió para que el usuario pueda corregir el error.
Flokzu.error( [[campo]] , "mensaje" );Otros/Utiles
Obtener el usuario actual (email)
El correo del usuario que está logueado en el sistema
Flokzu.currentUser();Obtener los usuarios asignados
Retorna nombre y correo de los usuarios o el rol asignado a la tarea
Flokzu.getCurrentAssignees();Obtener Fecha actual
Retorna la fecha actual, de acuerdo a la zona horaria de la cuenta, y el formato de fecha definido
Flokzu.getCurrentDate();Obtener Hora actual
Retorna la hora actual, de acuerdo a la zona horaria de la cuenta, y en formato HH:mm:ss
Flokzu.getCurrentTime();Obtener Fecha y Hora actual
Retorna la fecha y hora actual, de acuerdo a la zona horaria de la cuenta, y el formato de fecha definido
Flokzu.getCurrentDateTime();Ejecutar función de columna
Es posible, mediante nuestra API, ejecutar las funciones y scripts definidos en las columnas de una tabla. Esto es útil por ejemplo si quisiéramos definir valores por defecto a una tabla.
Flokzu.executeTableFunction([[campo::columna]]);Obtener el ID de un campo a partir de su nombre
Esta función es útil en caso de no querer/poder utilizar la notación para hacer referencia a campos [[ ]] ya sea por conveniencia, o porque el campo no se va a resolver de forma estática a nivel de script, sino que se resolverá en tiempo de ejecución dependiendo de otras variables.
Flokzu.getFieldByName( "NombreDeCampo" );Modificar el tamaño de las columnas
En caso de querer modificar el tamaño de las columnas de la tabla, se debe utilizar el siguiente script
La suma de todos los valores deber ser = 100 en el siguiente caso nuestra tabla cuenta con 5 columnas, por ello tenemos 5 tamaños.
function resize(){
Flokzu.resizeTable( [[Nombre de Tabla]] , [ 60, 10, 10, 10, 10 ] );
}
Flokzu.onInit(resize);Este script debe ser ubicado en la pestaña scripts de Configurar de visibilidad y scripts
En caso de querer que el tamaño se mantenga en todas las tareas ubicarlo en -Master script-
Librerías adicionales
Moment.js
Flokzu incorpora la librería Moment.js (https://momentjs.com/) para el manejo de fechas/horas. La versión incluida es la 2.22.2 y puede utilizarse por completo en los scripts de formulario para todo lo que tenga que ver con cálculo de fechas. Puede combinarse con getFieldValue.
Ejemplo: moment( Flokzu.getFieldValue([[Campo Hora]]) , "HH:mm:ss");Sweet Alert
Flokzu incorpora la librería SweetAlert (https://sweetalert.js.org) para desplegar popups visualmente atractivos. La versión incluída es la 1.1.3 y puede utilizarse para indicar errores a los usuarios en el momento que cambia un campo, sin esperar a que ejecute el "onAction". Cabe aclarar que mostrar un error con SweetAlert no impedirá que la tarea se complete.
Ejemplo: swal( {type : 'error' , title : 'Error!' , text: 'Mensaje de error'} );jQuery
Flokzu incorpora la librería jQuery (https://jquery.com), la cual permite realizar un sin fin de operaciones/funciones. La versión incluída es la 3.5.0 y puede utilizarse para diversas tareas/atajos, desde realizar llamadas Ajax,
Ejemplos
Scripts de Visibilidad
Ejecutar lógica "onAction"
Iterar los valores de una columna de campo tabla
Validar una dirección Ethereum y lanzar un SweetAlert
Restar dos campos de tipo "Fecha" con un campo Autocalculado
Restar dos campos de tipo "Hora" con un campo Autocalculado
Validar si el valor de un campo "Fecha" es menor a la fecha actual
Acotar la cantidad de decimales de un número en un script
TIP: Si una operación aritmética no está funcionando de manera deseable, es conveniente "parsear" los valores involucrados usando las funciones parseInt y parseFloat de JavaScript para asegurarse que el cálculo se realizará sobre números bien definidos. Además es deseable limitar la cantidad de decimales con la función toFixed (ver ejemplo más abajo).
Scripts de Visibilidad
Ver el Post Configurar la visibilidad por script para entender como se configuran los scripts que permiten alterar la visibilidad de un campo, así como ver distintos ejemplos.
Ejecutar lógica "onAction"
Usando onAction se puede definir lógica que va a ser ejecutada cuando se presione alguno de los botones para completar tarea. Como mencionamos anteriormente, es posible además determinar qué botón fue presionado para realizar distintas operaciones dependiendo de esto.
Para poder evaluar el botón presionado, la función debe recibir dos parámetros. El primero no es de importancia para este ejemplo, mientras que el segundo si es el nombre del botón presionado. En el siguiente ejemplo, si el botón es "Rechazar" haremos requerido el campo "Motivo de Rechazo" y de lo contrario lo ocultaremos.
function validarAcciones(msg,boton){
if(boton== "Rechazar"){
Flokzu.setRequired( [[Motivo de Rechazo]] );
}
else{
Flokzu.setHidden( [[Motivo de Rechazo]] );
}
}
Flokzu.onAction(validarAcciones);Iterar los valores de una columna de campo tabla
En algunos casos es necesario iterar sobre los valores de una columna de un campo tabla para averiguar si determinado valor ha sido ingresado y definir lógica a partir de ello.
La función Flokzu.getAllColumnValues(); retorna un identificador que luego debe ser utilizado con la función "each" de jQuery para iterar los elementos. Dentro de la función "each" se utiliza $(this).attr('value') para obtener el valor de la celda iterada.
function iterarTabla(msg, data){
$( Flokzu.getAllColumnValues( [[campo::columna]] ) ).each(
function(){
//Lanza un alert con el valor.
alert( $(this).attr('value') );
}
);
}
Flokzu.onTableChange( [[campo::columna]] , iterarTabla );Validar una dirección Ethereum y lanzar un SweetAlert
En este ejemplo validaremos la dirección ethereum ingresada en un campo en el momento que el usuario la ingrese, y en caso de error mostraremos un popup SweetAlert. Para ello utilizaremos la validación de un patrón con regex JavaScript para validar la dirección ethereum, luego un SweetAlert en caso de error y en caso de que además la función se ejecute al intentar completar una tarea (sender == evt_ruteo) entonces utilizaremos Flokzu.error para evitar que la misma se complete.
Notar que en este ejemplo usamos una sola funcion tanto para onChange como onAction, e intermanente distinguimos si se trata de un action (sender == evt_ruteo) o un onChange simplemente.
function ethValidator(sender , button){
if( ! (/^0x[a-fA-F0-9]{40}$/.test( Flokzu.getFieldValue([[Campo dirección eth]])) )){
swal({type : 'error' , title : 'Error!' , text: 'invalid address'});
if(sender == 'evt_ruteo'){
Flokzu.error( [[Campo dirección eth]] , "Dirección ETH inválida" );
}
}
}
Flokzu.onChange( [[Campo dirección eth]], ethValidator);
Flokzu.onAction(ethValidator);Restar dos campos de tipo "Fecha" con un campo Autocalculado
Con Flokzu crear un campo autocalculado que en todo momento muestre la diferencia (en días) entre 2 campos tipo "Fecha" es muy simple. Para ello utilizaremos la librería Moment.js que Flokzu ya tiene incorporada.
Paso 1
Agregar 2 campos de tipo Hora (Ejemplo: "Fecha 1" y "Fecha 2").
Paso 2
Agregar un campo autocalculado (Ejemplo: "Resta")
Paso 3
Agregar el script al autocalculado
Script considerando solo lunes a viernes
calcDiff();
function calcDiff(){
var start = moment( Flokzu.getFieldValue([[Fecha 1]]) , "YYYY/MM/DD");
var end = moment( Flokzu.getFieldValue([[Fecha 2]]) , "YYYY/MM/DD");
var weekdayCounter = 0;
while (start <= end) {
if (start.format('ddd') !== 'Sat' && start.format('ddd') !== 'Sun'){
weekdayCounter++; //add 1 to your counter if its not a weekend day
}
start = moment(start, 'YYYY-MM-DD').add(1, 'days'); //increment by one day
}
return weekdayCounter;
}Script considerando días de corrido
calcDiff();
function calcDiff(){
var m1 = moment( Flokzu.getFieldValue([[Fecha 1]]) , "YYYY/MM/DD");
var m2 = moment( Flokzu.getFieldValue([[Fecha 2]]) , "YYYY/MM/DD");
return Math.abs(m1.diff(m2, 'days')) + 1;
}Restar dos campos de tipo "Hora" con un campo Autocalculado
Con Flokzu crear un campo autocalculado que en todo momento muestre la diferencia (en horas) entre 2 campos tipo "Hora" es muy simple. Para ello utilizaremos la librería Moment.js que Flokzu ya tiene incorporada.
Paso 1
Agregar 2 campos de tipo Hora (Ejemplo: "Campo 1" y "Campo 2").
Paso 2
Agregar un campo autocalculado (Ejemplo: "Resta")
Paso 3
Agregar el script al autocalculado
calcDiff();
function calcDiff(){
var m1 = moment( Flokzu.getFieldValue([[Campo 1]]) , "HH:mm:ss");
var m2 = moment( Flokzu.getFieldValue([[Campo 2]]), "HH:mm:ss");
if(m1.isBefore(m2)){
return (moment.utc(m2.diff(m1)).format("HH:mm:ss"));
}else{
return (moment.utc(m1.diff(m2)).format("HH:mm:ss"));
}
}La salida de este script tiene formato "HH:mm:ss" pero es totalmente configurable (Ejemplo: "HH:mm" para no mostrar los segundos transcurridos). Para más información acudir a la documentación de la librería Moment.js
Notar que no se definió ningún "listener" ya que al ser un autocalculado los listeners son inferidos por el motor de scripts de Flokzu automáticamente.
Resultado
Validar si el valor de un campo "Fecha" es menor a la fecha actual
En ocasiones queremos realizar algún tipo de comprobación con las fechas ingresadas en los campos de tipo Fecha de Flokzu. En este caso, si queremos que al presionar un botón se compruebe si la fecha ingresada es menor a la fecha actual y en caso contrario lanzar un error y no permitir avanzar, los pasos a seguir son los siguientes:
Paso 1
Agregar un campo de tipo Fecha (Ejemplo: "Fecha 1").
Paso 2
Vamos a la sección de configuración de visibilidad y scripts y allí dentro a "Scripts"
Paso 3
Definimos el siguiente script en la tarea que nos interese.
function verificarFecha(msg, button){
if(button == "Nombre del boton que nos interesa"){
// Obtenemos la fecha ingresada
var fechaIngresada = moment(Flokzu.getFieldValue( [[Fecha 1]] ) , "YYYY/MM/DD" );
// Obtenemos la fecha actual
var fechaActual = moment();
// Si la fecha ingresada es mayor a la actual lanzamos error
if(fechaIngresada.isAfter(fechaActual)){
Flokzu.error([[Fecha 1]], "Aqui el mensaje de error personalizado");
}
}
}
//linkeamos la funcion verificarFecha a el clickeo de un botón
Flokzu.onAction(verificarFecha);Hecho esto, cuando el usuario presione el botón deseado, se ejecutará el script y si la fecha seleccionada es mayor a la actual, se lanzará un error y no permitirá continuar.
Acotar la cantidad de decimales de un número en un script
Usando un Autocalculado de tipo Script, es posible realizar operaciones aritméticas que involucren varios campos de Flokzu.
Por ejemplo si quisiéramos multiplicar 2 campos "A" y "B", el script sería algo como:
Flokzu.getFieldValue([[A]]) * Flokzu.getFieldValue([[B]])Si bien este script funciona y es válido, es posible que al multiplicar números con decimales el resultado contenga una cantidad infinita de decimales. Para evitarlo, podemos modificar la función de la siguiente manera y acotar los decimales a 3.
( Flokzu.getFieldValue([[A]]) * Flokzu.getFieldValue([[B]]) ).toFixed(3)Cambiá "3" por el número de decimales que quieras.
Creación de scripts con ChatGPT
Flokzu cuenta con una integración con ChatGPT, un modelo de Inteligencia Artificial Generativa entrenado para comprender conversaciones escritas de forma natural y responder preguntas acerca de una amplia variedad de temas. En Flokzu, ChatGPT será tu asistente que tu ayudará a ahorrar tiempo en algunas tareas complejas.
Dirígete a la sección Configurar visibilidad y scripts en el márgen derecho de tu pantalla. A continuación ve a la pestaña Scripts
Selecciona la Tarea de Usuario donde quieres colocar el script y apreta el botón
En la ventana emergente escribe una descripción del comportamiento que deseas obtener y apreta el botón ▶️ para que la IA genere el script
Flokzu devolverá un script generado con una breve explicación de cada paso
Para confirmar el script apreta el botón Aceptar. El script se copiará en la ventana de configuración sin incluir el texto descriptivo
Puedes modificar o corregir el script desde la ventana de configuración
A pesar de la asistencia de la IA, siempre recomendamos una revisión humana del código generado. Los desarrolladores pueden hacer ajustes necesarios para garantizar su correcto funcionamiento.
La inteligencia artificial, aunque poderosa, no es infalible por lo que el código generado por la IA puede no ser perfecto en todas las situaciones. Aquíl tienes algunas razones por los cuales el código JavaScript puede no funcionar como se espera:
Complejidad del Contexto: La IA se basa en patrones y datos existentes para generar código. Si el contexto o la solicitud son demasiado complejos o únicos, la IA puede no entender completamente el objetivo, lo que podría llevar a errores.
Dependencia de Datos de Entrenamiento: La IA se entrena en una amplia gama de datos, pero no siempre puede anticipar todas las posibles situaciones. Si un caso es inusual o no se encuentra en los datos de entrenamiento, el código generado puede no ser óptimo.
Errores en los datos de entrada: Si a la IA se le proporcionan datos inexactos de entrada, como ser nombres de campos que no existen o mal escritos, puede generar un código que entre en conflicto con la librería de Flokzu.
Es importante entender que, aunque esta función agiliza el proceso de desarrollo, no sustituye la experiencia y conocimiento de un desarrollador. Recomendamos que los usuarios técnicos revisen y prueben el código generado para garantizar que se ajuste a sus necesidades.
Actualizado el: 22/10/2023
¡Gracias!