Saltar al contenido principal

Acciones (Actions)

Personalizaciones en las operaciones de base de datos.

Introducción​

Constantemente se realiza alguna manipulación de datos, y es habitual que existan reglas como, por ejemplo:

  • Al eliminar un cliente debe eliminarse su historial.
  • Al cancelar un producto es necesario eliminarlo de los pedidos y ajustar el importe total.
  • Al finalizar una compra es necesario enviar los datos a otro sistema que realiza la distribución.

Las acciones (actions) sirven precisamente para eso, para inyectar código que se ejecute en situaciones específicas cuando se produce una manipulación de datos.

Al insertar o modificar alguna información, se ejecutan las acciones de guardar (save) y guardado (saved):

  • save: Antes de ejecutar el comando en la base de datos.
  • saved: Después de haber ejecutado el comando en la base de datos.

En cambio, al eliminar, borrar o suprimir alguna información se ejecutan las acciones de eliminar (remove) y eliminado (removed).

  • remove: Antes de ejecutar el comando en la base de datos.
  • removed: Después de haber ejecutado el comando en la base de datos.

Así, cuando modificamos algo en un formulario, con operaciones de crear, modificar o eliminar información, se ejecutan operaciones distintas en la base de datos y se ejecutan las respectivas acciones (actions).

¿Ha oído hablar de los triggers de base de datos? El trigger de base de datos se ejecuta siempre que hay modificaciones de datos; por tanto, las acciones (actions) son similares a los triggers, solo que a nivel del código.

Recuerde que cada tipo de operación ejecuta un comando distinto en la base de datos, que son:

  • Crear: insert into ...
  • Modificar: update ...
  • Eliminar: delete from ...

Cuando ejecutamos uno de estos comandos de base de datos mediante _db.execute(...), no se ejecutará ninguna acción, porque el comando se ejecuta directamente en la base de datos sin que sea posible interactuar con las acciones.

En el código de las acciones puede utilizar cualquier recurso de la framework low-code políglota.

Las acciones se ejecutan cuando se produce alguna manipulación de datos en los formularios del backoffice autogenerado por Netuno, o cuando ejecutamos operaciones en la base de datos en el código utilizando:

  • _db.insert(...), _db.form(...).insert(), _db.insertIfNotExits(...), _db.insertMany(...), entre otros.
  • _db.update(...), _db.form(...).update(), _db.updateMany(...), entre otros.
  • _db.delete(...), _db.form(...).delete(), _db.deleteMany(...), entre otros.

Es decir, cuando utilizamos en el código algún mecanismo de la framework low-code políglota para realizar las operaciones de manipulación de datos, se ejecutará la acción correspondiente si existe.

Sin embargo, si se ejecuta un comando directamente en la base de datos, no será posible ejecutar la acción.

Se recomienda evitar ejecutar comandos directamente en la base de datos para no eludir los mecanismos de manipulación de datos que ofrece Netuno.

En el código de las acciones puede realizar cualquier operación asociada a la manipulación de datos.

Elemento de Datos (Data Item)​

El elemento de datos (_dataItem) es un recurso de la framework low-code políglota que contiene toda la relación de datos que se está creando, modificando o eliminando.

A través del recurso _dataItem podemos acceder a toda la información y verificar detalles del proceso de la operación que está ocurriendo.

Consulte la documentación del recurso DataItem para obtener más detalles sobre lo que admite el recurso _dataItem.

Atención: El recurso _dataItem solo está disponible en el código de las acciones (actions).

Guardar, Salvar, Modificar o Crear Nuevo (Save)​

Para crear una acción que se ejecutará cuando se cree un nuevo registro, o cuando se modifique algo, el script de esta acción se llamará save, que significa que algo se está guardando en la base de datos, por ejemplo:

  • mi_app/server/actions/mi_formulario/save.js

Esta acción se ejecuta antes de ejecutar el comando de base de datos.

Cuando se quiera ejecutar código después de que los datos se hayan guardado en la base de datos, utilizamos la acción saved, por ejemplo:

  • mi_app/server/actions/mi_formulario/saved.js

Esta acción se ejecuta después de haber ejecutado el comando de base de datos.

Es decir, dentro de la aplicación, en la carpeta server/actions, creamos una subcarpeta con el nombre del formulario (tabla) y dentro colocamos un script llamado save o saved, que contiene el código correspondiente para ejecutarse antes o después del comando de base de datos.

Para distinguir si es una creación de datos, podemos comprobar con un if el resultado del método _dataItem.isInsert(), por ejemplo:

mi_app/server/actions/mi_formulario/save.js
if (_dataItem.isInsert()) {
    // Se están creando nuevos datos...
}

Para distinguir si es una modificación de datos, podemos comprobar con un if el resultado del método _dataItem.isUpdate(), por ejemplo:

mi_app/server/actions/mi_formulario/saved.js
if (_dataItem.isUpdate()) {
    // Se están modificando los datos...
}

Obtener el ID​

Para obtener el ID (identificador) del elemento que se está modificando:

_dataItem.getId()

Verificar qué se modifica​

Para verificar qué se está modificando, podemos utilizar getOldRecord() para obtener los datos antiguos de la base de datos y compararlos con los nuevos datos de getRecord(), por ejemplo:

if (_dataItem.getOldRecord().getString("correo") != _dataItem.getRecord().getString("correo")) {
    // ¡Atención: se está modificando el correo electrónico!
}

Generar error​

Es posible generar un error para impedir que la operación avance; la generación del error normalmente se realiza antes de ejecutar el comando de base de datos, por tanto, en la acción save, por ejemplo:

mi_app/server/actions/mi_formulario/save.js
_dataItem.setStatusWithError()
    .setErrorTitle("Correo")
    .setErrorMessage("No se permite modificar el correo electrónico.")

Verificar si hubo error​

Es posible verificar si hubo algún error en la ejecución del comando en la base de datos; pueden producirse diversos errores, por ejemplo:

  • No se permite tener correos electrónicos repetidos.
  • Un campo obligatorio no se rellenó correctamente.
  • Entre muchos otros.

La comprobación de errores se realiza normalmente después de la ejecución del comando de base de datos, por tanto, en la acción saved, por ejemplo:

mi_app/server/actions/mi_formulario/saved.js
if (_dataItem.isError()) {
    // Se produjo algún error y no se pudieron guardar los datos...
}

Configuración​

Es posible tener una action específica que se ejecuta solo cuando se realizan modificaciones de datos durante la configuración (setup) de la base de datos.

Por ejemplo:

  • mi_app/server/actions/mi_formulario/setup_save.js
  • mi_app/server/actions/mi_formulario/setup_saved.js

Eliminar, Borrar o Suprimir (Remove)​

Para crear una acción que se ejecutará cuando se elimine algún registro, el script de esta acción se llamará remove, que significa que algo se está eliminando en la base de datos, por ejemplo:

  • mi_app/server/actions/mi_formulario/setup_remove.js

Esta acción se ejecuta antes de ejecutar el comando de base de datos.

Cuando se quiera ejecutar código después de que los datos se hayan eliminado de la base de datos, utilizamos la acción removed, por ejemplo:

  • mi_app/server/actions/mi_formulario/setup_removed.js

Esta acción se ejecuta después de haber ejecutado el comando de base de datos.

Es decir, dentro de la aplicación, en la carpeta server/actions, creamos una subcarpeta con el nombre del formulario (tabla) y dentro colocamos un script llamado remove o removed, que contiene el código correspondiente para ejecutarse antes o después del comando de base de datos.

Conflicto con relaciones​

Según el modelo de datos, puede ocurrir que al eliminar un registro que se esté utilizando en la relación con otra tabla, que también es otro formulario, no se pueda eliminar para evitar que la relación quede rota.

Entonces, en la acción removed, que se ejecuta después del comando de base de datos de eliminación, podemos comprobar si se produce este error de la siguiente forma:

mi_app/server/actions/mi_formulario/removed.js
if (_dataItem.isStatusAsError() && _dataItem.isStatusAsRelations()) {
    _log.error(
        "No se pudo eliminar porque hay una relación con la tabla "
        + _dataItem.getRelationTable() +" utilizando el ID " + _dataItem.getRelationItem().getInt("id")
    )
}

Como alternativa, en la acción remove, que se ejecuta antes de realizar el comando de base de datos que borra el registro, podemos implementar la "limpieza" de otros registros que pueden tener relación, por ejemplo:

mi_app/server/actions/mi_formulario/remove.js
_db.form("otro_formulario")
    .where(
        _db.where("mi_formulario_id")
            .equals(_dataItem.getRecord().getInt("id"))
    )
    .delete()

Configuración​

Es posible tener una action específica que se ejecuta solo cuando se realiza la eliminación de datos durante la configuración (setup) de la base de datos.

Por ejemplo:

  • mi_app/server/actions/mi_formulario/setup_remove.js
  • mi_app/server/actions/mi_formulario/setup_removed.js

Conclusión​

Con las acciones (actions) podemos centralizar operaciones específicas que están relacionadas con la manipulación de determinados datos.

Permite equipar con código que proporciona mecanismos útiles para garantizar la integridad, facilitar tareas, realizar integraciones, hacer operaciones paralelas, tener comprobaciones adicionales y mucho más.

Codificar acciones es sencillo y extremadamente útil; es posible extenderlas con la utilización de cualquier otro recurso de la framework low-code políglota.

En el código de las acciones puede utilizar cualquier recurso de la framework low-code políglota.

Considere el uso de las acciones y rápidamente podrá comprobar cómo la facilidad obtenida puede potenciar muchas estrategias útiles.