Introducción

En INTEGRADOC 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.

Teniendo esto en mente desarrollamos 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 utilizando un lenguaje ampliamente reconocido como JavaScript.

Los scripts en INTEGRADOC se deben definir utilizando el lenguaje de programación JavaScript 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

La metodología de desarrollo para los scripts en INTEGRADOC es bastante simple. 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, internamente pueden hacer uso de operaciones de visibilidad, manejo de errores o 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.

Integradoc.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.

Integradoc.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 en este post).

Integradoc.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.

Integradoc.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

Integradoc.setHidden([[campo]]);

Hacer que un campo sea solo lectura

Integradoc.setReadOnly([[campo]]);

Hacer que un campo sea editable (no requerido)

Integradoc.setEditable([[campo]]);

Hacer que un campo sea requerido

Integradoc.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.

Integradoc.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.

Integradoc.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 en este post.

Integradoc.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.

Integradoc.error([[campo]], "mensaje");

Otros/Utiles

Obtener el usuario actual (email)

El correo del usuario que está logueado en el sistema

Integradoc.currentUser();

Obtener los asignados actuales de la instancia

Devuelve los usuarios o roles asignados actualmente en la tarea activa

Integradoc.getCurrentAssignees();

Obtener Fecha actual

Retorna la fecha actual, de acuerdo a la zona horaria de la cuenta, y el formato de fecha definido

Integradoc.getCurrentDate();

Obtener Hora actual

Retorna la hora actual, de acuerdo a la zona horaria de la cuenta, y en formato HH:mm:ss

Integradoc.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

Integradoc.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.

Integradoc.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.

Integradoc.getFieldByName("NombreDeCampo");

Librerías adicionales

Moment.js

INTEGRADOC 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( Integradoc.getFieldValue([[Campo Hora]]) , "HH:mm:ss");

Sweet Alert

INTEGRADOC 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

INTEGRADOC 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 2.2.4 y puede utilizarse para diversas tareas/atajos, desde realizar llamadas Ajax,



Más info en: Visibilidad y obligatoriedad de campos por script y en Ejemplos de Scripts útiles en INTEGRADOC

Actualizado el: 07/04/2020