Introducción

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.

Para ello, Flokzu cuenta con un Script Engine que provee varias funciones predefinidas a nivel de formulario para poder realizar todo tipo de validaciones, detección de errores y algoritmos. Los scripts deben ser definidos utilizando JavaScript como lenguaje de programación y puede aprovecharse la mayoría de las características que el lenguaje 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, toda la lógica debe definirse dentro de funciones JavaScript, las cuales serán invocadas mediante listeners que las asocian a eventos específicos del formulario (como el cambio de valor de un campo o la apertura de una tarea). Estos *listeners *se describen en detalle más adelante en este artículo.
La única excepción a esta regla son los campos de tipo autocalculado, donde el código puede escribirse como una expresión directa sin necesidad de declarar una función ni registrar un listener, ya que Flokzu infiere automáticamente los campos a escuchar.

Las funciones definidas pueden utilizar operaciones internas para manejar la visibilidad, errores y lectura/escritura de campos. Además podrás utilizar librerías externas como date-fns y Sweet Alert.

Todas las variables utilizadas dentro de las funciones deben ser declaradas explícitamente usando la palabra reservada var. Flokzu no admite variables globales (declaradas fuera de una función) ni la declaración implícita de variables (es decir, asignar un valor a un identificador sin haberlo declarado previamente).

Nombres de los campos utilizados en scripts

El uso de caracteres especiales como { } [ ] : < > = + ^ # $ / ! % * ? & | al comienzo de los nombres de campos puede generar conflictos con scripts personalizados, especialmente porque los nombres pueden ser usados como identificadores en el DOM, y los caracteres como claves en objetos JavaScript, en selectores CSS/JS o en expresiones regulares. Muchos de estos caracteres tienen significados reservados en estos contextos, lo que puede provocar errores de sintaxis o comportamientos inesperados.
Para evitar problemas, se recomienda evitar el uso de dichos caracteres en general, especialmente al inicio del nombre.

Funciones disponibles

"Listeners"

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

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.

Visibilidad

Estas funciones te permiten controlar cuando un campo es editable, solo lectura u oculto de forma dinámica. 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

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", "Tabla" y "firma" 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

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 información de la instancia

Devuelve los datos de la información de la instancia: referencia, nombre del proceso, descripción, tarea actual, fecha de creación, fecha de asignación, iniciador, tags, fecha de finalización.

Flokzu.currentInstance()

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

Librerías adicionales

date-fns

Flokzu incluye date-fns para la gestión de fechas y horas, por lo que no es necesario importar la biblioteca en tus scripts personalizados. La versión incluida es la 4.1.0 y se puede utilizar íntegramente en los scripts de los formularios para cualquier tarea relacionada con el cálculo de fechas.
Todas las funciones de date-fns están disponibles a través del objeto dateFns, por lo que no es necesario añadir una instrucción import a tus scripts. El objeto dateFns ya está disponible de forma global en la aplicación.

var my_day = dateFns.parse(“12-07-2027”, “MM-dd-yyyy”, new Date()); // Crea un objeto Date
var full_date = dateFns.format(my_day, “PPPP”); // 'Martes, 7 de diciembre de 2027 a las 12:00:00 a. m.'

Correcto:

dateFns.format(date, “yyyy-MM-dd”);
dateFns.addDays(date, 1);
dateFns.isBefore(date1, date2);

Incorrecto:

date.format(“yyyy-MM-dd”);
date.addDays(1);
date1.isBefore(date2);

Flokzu también incluye de forma predeterminada el módulo date-fns/locale, que se utiliza para dar formato a las fechas utilizando los nombres de los meses, los días de la semana, etc., en diferentes idiomas (en lugar del inglés predeterminado). Se utiliza pasando un objeto de configuración regional como opción a funciones como format, formatDistance, formatRelative, etc.

var date = dateFns.parse('14/07/2027', 'd/MM/yyyy', new Date() );
console.log( dateFns.format(date, 'PPPP', { locale: dateFns.locale.fr }) ); // 'mercredi 14 juillet 2027'

🇪🇸 → dateFns.locale.es
🇫🇷 → dateFns.locale.fr
🇧🇷 → dateFns.locale.pt
🇩🇪 → dateFns.locale.de
🇬🇧 → dateFns.locale.en

Ejemplos de uso:

// Formato con los nombres de los meses y los días de la semana en alemán
dateFns.format(new Date(2027, 9, 3), 'PPPP', {locale: dateFns.locale.de});
// "Sonntag, 3. Oktober 2027"

// Distancia relativa ("hace 3 días", etc.)
dateFns.formatDistance(new Date(2027, 8, 7), new Date(2026, 4, 14), {locale: dateFns.locale.pt});
// "mais de 1 ano"

// Formato relativo ("hoy a las..."», "ayer a las...")
dateFns.formatRelative(new Date(2027, 7, 25), new Date(2027, 7, 28), {locale: dateFns.locale.es});
// "el miércoles pasado a las 00:00"

Sweet Alert

Flokzu incorpora la librería SweetAlert 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'} );

mask / inputMask

Con esta librería podrás aplicar máscaras de entrada en tus campos (teléfonos, documentos, códigos, etc.).
Documentación

Algunos ejemplos que puedes implementar:

// Atar una mascara directamente a un campo
Flokzu.addMask([[Telefono]], { mask: '9999-9999', placeholder: '*' }); // Esta es una máscara personalizada
Flokzu.addMask([[Email]], { alias: 'email' }); // En este caso aplica un alias, una máscara definida por Inputmask
Flokzu.addMask([[Campo]], { alias: 'ip' });

// Remover una mascara de un campo
Flokzu.removeMask([[Campo]]);


// Alias y definiciones que se pueden usar en máscaras personalizadas
Inputmask.extendDefinitions({ 'K': { validator: '[0-9Kk]', casing: 'upper' } });
Inputmask.extendAliases({ flokzuRut: { mask: '9{7,8}-K', greedy: false } });
Flokzu.addMask([[Rut]], { alias: 'flokzuRut' });

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

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 función tanto para onChange como onAction, e internamente distinguimos si se trata de una acción (sender == evt\_ruteo) o simplemente un onChange.

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 date-fns 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

function calcDiff() {
  var start = dateFns.parse(Flokzu.getFieldValue([[Fecha 1]]), 'yyyy/MM/dd', new Date());
  var end = dateFns.parse(Flokzu.getFieldValue([[Fecha 2]]), 'yyyy/MM/dd', new Date());

  var weekdayCounter = 0;
  
  while (start <= end) {
    if (!dateFns.isWeekend(start)) {
      weekdayCounter++;
    }

    start = dateFns.addDays(start, 1);
  }

  return weekdayCounter;
}

Script considerando días de corrido

function calcDiff() {
  var start = dateFns.parse(Flokzu.getFieldValue([[Fecha 1]]), 'yyyy/MM/dd', new Date());
  var end = dateFns.parse(Flokzu.getFieldValue([[Fecha 2]]), 'yyyy/MM/dd', new Date());

  return dateFns.differenceInDays(end, start) + 1;
}

Restar dos campos de tipo "Hora"

Paso 1
Agregar 2 campos de tipo Hora (Ejemplo: "Hora 1" y "Hora 2").

Paso 2
Agregar un campo texto (Ejemplo: "Resta")

Paso 3
Agregar el script a la tarea donde se calculará la resta

function calcDiff() {
  // Obtener valores de los campos "Hora 1" y "Hora 2"
  var t1 = Flokzu.getFieldValue([[Hora 1]];
  var t2 = Flokzu.getFieldValue([[Hora 2]];
  
  const baseDate = new Date(2000, 0, 1); // Fecha de referencia arbitraria, el mismo día para ambos

  // Construir los objetos Date a partir de t1 y t2
  var start = dateFns.parse(t1, 'HH:mm:ss', baseDate);
  var end = dateFns.parse(t2, 'HH:mm:ss', baseDate);

  var diffInSeconds = Math.abs(dateFns.differenceInSeconds(end, start)); // Calcula a diferencia de las fechas en segundos

  // Utiliza la fecha base para construir un objeto Date y representarlo en formato Hora
  var result = dateFns.format( dateFns.addSeconds(baseDate, diffInSeconds), 'HH:mm:ss');  


   // Actualizar el campo de resultado con la diferencia calculada
   Flokzu.setFieldValue([[Resta]], result);
}

// Llamar la función cuando el valor de los campos cambie
Flokzu.onChange([[Hora 1]], calcDiff);
Flokzu.onChange([[Hora 2]], calcDiff);

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 == 'Aprobar'){  // Nombre del botón que ejecutará la verificación

       // Obtener los datos ingresados
       var fechaIngresada= dateFns.parse(Flokzu.getFieldValue([[Fecha 1]]), 'yyyy/MM/dd', new Date());

    
      // Obtener la fecha actual
       var fechaActual = new Date();
       
      // Si la fecha ingresada es podterior a la actual, lanza un error
       if (dateFns.isAfter(fechaIngresada, fechaActual )){
           Flokzu.error([[Fecha 1]], 'Mensaje de error personalizado');
       }
   }
}

// Asociamos la función al evento de completar tarea
Flokzu.onAction(verificarFecha);

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)

Actualizado el: 02/09/2026