Introducción a App Builder - Apéndice B: La capa de negocio en App Builder (Avanzado)

Este es el segundo apéndice de la serie de tutoriales Introducción a App Builder. Estos apéndices complementan las lecciones de la serie y proporcionan información más detallada sobre los conceptos introducidos.

En esta lección, exploraremos más a fondo la capa de negocio de App Builder, el área donde creamos reglas.

Uniones

Los joins, introducidos en Lección 7, se utilizan cuando trabajamos con reglas que extraen datos de más de una tabla en la capa de datos. Combinan datos horizontalmente, agregando columnas de una segunda tabla junto a las columnas de la primera.

Las uniones funcionan de manera diferente: en lugar de agregar columnas, apilan filas. Una unión añade los resultados de una consulta encima de otra, produciendo una lista combinada de registros extraídos de más de una tabla. Para que una unión funcione, ambas consultas deben incluir al menos una columna con el mismo nombre, porque App Builder utiliza esa columna compartida como base para apilar los resultados. Por esto podemos combinar directamente las columnas de País de nuestras tablas Cliente y Proveedor: ambas columnas comparten el mismo nombre.

Para demostrar cómo funciona una unión, vamos a crear manualmente una unión que muestre todos los países que existen en la fuente de datos Northwinds. Hay dos tablas, Proveedor y Cliente, que contienen una columna llamada País, así que combinaremos los registros de ambas.

1. En App Workbench > Reglas, haz clic en + Regla.

2. Cuando aparezca la pantalla de creación de reglas:

   1. En el campo Nombre, ingresa Proveedor (Países para Proveedor y Cliente).

   2. En el campo Propósito, selecciona Objeto de Negocio.

   3. Asegúrate de que Proveedor esté seleccionado en el campo Destino.

   4. Haz clic en Crear.

3. App Builder creará la regla. Por defecto, agrega la tabla de destino y selecciona su clave primaria. Sin embargo, en esta regla solo nos interesan los países presentes en las tablas, así que desmarca IDProveedor, selecciona la columna País y márcala como clave primaria.

4. Necesitamos agregar la otra tabla que contiene información de países, así que haz clic en + Tablas.

5. Encuentra la tabla Cliente y haz clic en Agregar. App Builder agregará la tabla Cliente y podrás verla en la pestaña Tablas junto a Proveedor.

6. Ve a la pestaña Joins.

7. App Builder ha creado un join, pero ajústalo para que sea el tipo que deseas. Asegúrate de que Proveedor esté seleccionado en el campo Izquierda y que el campo Tipo diga Unión.

8. Haz clic en la pestaña SQL para ver la sintaxis de tu unión:

   

9. Para ver los resultados, haz clic en el botón Resultados en el panel Regla.

10. Observa que los resultados contienen países duplicados. Esto es esperado: múltiples clientes y proveedores se basan en las mismas regiones, por lo que cada país aparece una vez por cada registro en cada tabla. Para producir una lista limpia y única de países, utilizaremos el botón Seleccionar Distinto.

11. Regresa al Generador de Reglas.

12. En el panel Regla, haz clic en Más > Caso Especial. Se abre el diálogo Configuración de Casos Especiales. Este diálogo proporciona control avanzado sobre tu regla. Consulta Opciones avanzadas en Pestaña Reglas de App Workbench para una descripción completa de todas las opciones disponibles.

13. Marca la casilla de verificación Seleccionar Distinto para eliminar filas redundantes de los resultados, asegurando que cada registro en la lista sea único. Haz clic en Guardar.

14. Haz clic en el botón Results nuevamente. La regla ahora devuelve una lista distinta de todos los países representados en las tablas Customer y Supplier.

Hora de practicar: Usa tu regla de unión como un control de lista

Ahora, pongamos tu nueva regla de unión en funcionamiento. Ve a las páginas emergentes Customer y Supplier y cambia el tipo de control del campo Country a List. En la pestaña List Options, selecciona el objeto empresarial de unión que acabas de crear y establece tanto la Key como la Title en la columna Country.

Reglas CRUD

Presentamos las reglas CRUD en la Lección 7, pero ahora veamos más detalladamente.

El acrónimo CRUD significa "Create, Read, Update, Delete" (Crear, Leer, Actualizar, Eliminar). Esto quiere decir que los desarrolladores de App Builder usan las reglas CRUD para insertar, recuperar, modificar o borrar registros de las tablas presentes en la fuente de datos.

Capa de destino: empresarial vs. datos

Cuando creas una regla CRUD, debes seleccionar una capa de destino: ya sea la capa empresarial o la capa de datos. Esta decisión es crítica y tiene implicaciones significativas.

Dirigirse a la capa empresarial es el enfoque recomendado para la mayoría de las operaciones. Cuando tu regla CRUD se dirige a la capa empresarial (por ejemplo, el objeto empresarial Order (Source)), actúa como un usuario interactuando con la aplicación. Desencadena todos los eventos intrínsecos (Save, Update, etc.) asociados a ese objeto empresarial. Esto significa que todas tus reglas de validación configuradas, acciones personalizadas y seguimiento de auditoría se ejecutarán automáticamente. Este enfoque garantiza la integridad de los datos y la coherencia con la lógica de tu aplicación. También permite usar manejadores de éxito, fallo y reversión para el evento.

Dirigirse a la capa de datos omite toda la lógica empresarial. Cuando te diriges a la capa de datos (por ejemplo, la tabla Order), tu regla interactúa directamente con la base de datos. No desencadenará ningún evento intrínseco, validaciones o seguimiento de auditoría configurados en el objeto empresarial. Este es un enfoque de "puerta trasera", útil para operaciones masivas de alto rendimiento donde intencionalmente quieres omitir la lógica empresarial.

Puedes ver esta diferencia visualmente en el flujo de trabajo visual; una regla que se dirige a la capa empresarial mostrará subprocesos para su lógica de eventos, mientras que una que se dirige a la capa de datos no lo hará.

Actualización CRUD

Primero, veamos cómo crear una regla de actualización CRUD. Esto significa modificar registros existentes en una tabla. Para demostrarlo, vamos a crear una regla que aumente todas las cantidades de los productos pedidos.

1. En App Workbench > Rules, haz clic en + Rule.

2. En el campo Name, ingresa OrderDetail (Quantity + 1).

3. En el campo Purpose, selecciona CRUD.

4. En el campo Action, selecciona Update.

5. En Target Layer, selecciona Data Layer. (Para esta actualización masiva simple, omitiremos la lógica empresarial).

6. En el campo Target, selecciona OrderDetail.

7. Haz clic en Create. App Builder tardará unos segundos en crear la regla.

8. En la pestaña Tables, la tabla OrderDetail aparecerá, con su clave principal, OrderDetailID, seleccionada. Selecciona también la columna Quantity haciendo clic en su casilla de verificación.

9. Agregaremos una columna nueva con un alias para ayudarnos a visualizar que la regla funciona. Ve a la pestaña Columns y haz clic en + Column. Cuando se abra el diálogo Column - Add Column, ingresa la siguiente información:

   1. En el campo Column or Expression, ingresa OD.Quantity + 1.

   2. En el campo Alias, ingresa un nombre legible. Usaremos QuantityPlus.

   3. En el campo Target, selecciona Quantity. Esto le dice a App Builder que escriba el resultado de esta expresión en la columna Quantity.

10. Haz clic en Guardar.

11. En la pestaña Columnas, ahora verás tanto Cantidad como CantidadPlus. La columna original OD.Cantidad también se dirigirá a Cantidad de forma predeterminada. Debemos desactivar su destino para evitar ambigüedad:

    1. Encuentra la fila OD.Cantidad en la lista Columnas.

    2. Haz clic en su menú desplegable Destino. Aparece un botón X junto a él. Haz clic en él para desactivar el destino de la columna.

       Esto garantiza que solo se use nuestra expresión CantidadPlus para actualizar la columna Cantidad. Si ambas tuvieran destino activado, la que tuviera el índice más alto "ganaría", lo que generaría un comportamiento impredecible.

12. La regla está lista. En el panel Regla, haz clic en el panel Resultados para verla en funcionamiento. Observa que la columna adicional que agregaste aumenta todas las cantidades en uno:

    

Copiar regla

Piensa en cómo crearías una regla de actualización CRUD similar a la que hemos creado arriba, pero con el efecto opuesto; es decir, una regla que modifique todas las entradas en la columna Cantidad de la tabla OrderDetail restando uno. Sin embargo, en lugar de construir esta regla desde cero, usemos la función Copiar regla de App Builder, que duplica una regla existente para que puedas usarla como punto de partida, ahorrando tiempo cuando creas reglas similares a las que ya has construido.

1. En App Workbench > Reglas, localiza la regla OrderDetail (Cantidad + 1) y haz clic en Más > Copiar regla.

2. Haz clic en Copiar.

3. App Builder crea la nueva regla, nombrándola OrderDetail (Cantidad + 1) (Nueva). Se te lleva directamente a su pantalla de edición. En el panel Regla, actualiza el campo Nombre a OrderDetail (Cantidad - 1), luego navega a la pestaña Columnas.

4. Encuentra la expresión OD.Cantidad + 1 y edítala. Cambia la expresión a OD.Cantidad - 1 y actualiza el Alias de CantidadPlus a CantidadMenos. Haz clic en Guardar.

5. Verifica que la regla funcione correctamente haciendo clic en Resultados en el panel Regla.

Hora de practicar: Agrega controles de cantidad

Ahora que tienes ambas reglas de cantidad, conéctalas al panel Detalles de la orden en la página Órdenes.

1. Abre el objeto de negocio OrderDetail (Origen) y crea un evento personalizado para la regla OrderDetail (Cantidad + 1). En el diálogo de creación de eventos, ingresa Cantidad Plus en el campo Nombre y establece Alcance de actualización en Fila. Esto garantiza que cuando se active el evento, solo se actualice la fila afectada en lugar del panel completo.

2. Repite el paso 1 para crear un segundo evento llamado Cantidad Menos, adjuntando la regla OrderDetail (Cantidad - 1) y también estableciendo Alcance de actualización en Fila.

3. Navega a la pantalla de edición de la página Órdenes. En el panel Detalles de la orden, agrega dos controles de Botón: uno que ejecute el evento Cantidad Plus y otro que ejecute el evento Cantidad Menos.

4. Visita la vista previa de la página Órdenes y prueba los botones nuevos.

CRUD eliminar

Las reglas de eliminación CRUD se usan para borrar registros de las tablas. Sin embargo, como es fácil usar elementos de la interfaz para eliminar registros individuales, las reglas de eliminación CRUD generalmente se usan solo para eliminar muchos registros a la vez. Para demostrarlo, vamos a crear una regla de eliminación CRUD que elimine todos los detalles de la orden asociados con una orden individual, para eliminar la necesidad de eliminar todos los detalles de la orden por separado cuando se cancela una orden.

1. En App Workbench > Reglas, haz clic en + Regla.

2. En el campo Nombre, ingresa OrderDetail (Eliminar OrderDetail para Order).

3. En el campo Propósito, selecciona CRUD.

4. En el campo Acción, selecciona Eliminar.

5. En Capa de destino, selecciona Capa de datos.

6. En el campo Destino, selecciona OrderDetail.

7. Haz clic en Crear.

8. En la pestaña Tablas, App Builder ha agregado la tabla OrderDetail y ha seleccionado su clave principal, OrderDetailID. Mantenla seleccionada, ya que dirigirse a la clave principal es la forma más eficiente y segura de realizar una operación de eliminación. Selecciona también la columna OrderID; usaremos esta columna en la siguiente sección para vincular la regla a una orden específica.

Eventos

Las reglas CRUD solo se pueden usar cuando están asociadas a eventos, que son procesos integrados en tablas u objetos de negocio que se ejecutan en respuesta a ciertas acciones, como guardar un registro. Todas las tablas y objetos de negocio tienen intrínsecamente cuatro eventos: guardar, actualizar, eliminar e insertar, que se ejecutan conforme se modifican los registros en App Builder.

Activemos las reglas CRUD que creamos. Para ello, crearemos nuestros propios eventos personalizados. A diferencia de los eventos intrínsecos, los eventos personalizados deben estar asociados a un control para ejecutarse. Las reglas CRUD que estamos creando requieren eventos personalizados para ejecutarse cuando los deseemos.

Primero, crearemos un evento personalizado para asociarlo con nuestra regla CRUD de eliminación, de modo que cuando se elimine un pedido, también se eliminen los detalles de pedido relacionados.

1. En App Workbench > Rules, ubica y abre la regla Order (Source).

2. En el panel Rule, haz clic en Events. Se abre la página All Events (Order (Source)). Enumera los cuatro eventos intrínsecos que App Builder incluye para cada tabla y objeto de negocio: Insert, Save, Update y Delete. Para una descripción completa de esta página y sus opciones, consulta Configure an event.

3. Dado que estamos creando un evento personalizado, haz clic en + Rule Event. Se abre la página Event, donde puedes añadir los detalles del nuevo evento (consulta Event detail options para una descripción completa de todos los campos):

   1. En Event Information, en el campo Name, ingresa Delete Order Details.

   2. En Messages, en el campo Confirmation, ingresa un mensaje que se mostrará a los usuarios antes de que se ejecute el evento, pidiéndoles que confirmen si desean continuar. El mensaje debe indicar claramente qué sucederá si el usuario continúa, ayudando a prevenir acciones accidentales. Consulta Configure an event para obtener información sobre otros tipos de mensajes.

      

   3. En la sección Execution Properties, marca la casilla Transaction. Esto asegura que el evento sea una ejecución de todo o nada: como nuestra regla de eliminación afecta múltiples elementos de línea, una transacción garantiza que si ocurre un error a mitad del proceso, App Builder revierta todos los cambios. Esto previene un escenario donde se eliminen algunos registros mientras otros permanecen, dejando los datos en un estado inconsistente. Consulta Execution properties para una descripción completa de todas las opciones en esta sección.

   4. Deja los otros campos con sus selecciones predeterminadas y haz clic en Save. App Builder creará el evento.

      Nota

      Para escenarios de acceso concurrente donde la integridad de datos podría verse comprometida, App Builder también proporciona Event Locking, que fuerza la ejecución en serie y puede limitarse a registros individuales. Deja esto sin marcar para el evento actual, pero téngalo en cuenta para entornos de alto tráfico o flujos de trabajo complejos donde la sincronización a nivel de registros es un requisito.

4. El evento ha sido creado, y App Builder te muestra su pantalla de configuración:

   

   Actualmente estás en la Grid View (que se muestra en la captura de pantalla anterior), que proporciona una lista de alto nivel de todas las acciones y validaciones registradas en este evento. Una vista alternativa del evento se puede ver en el Visual Workflow Editor, que muestra el orden de ejecución y la relación entre eventos heredados. Para verla, haz clic en el icono en el panel Event. Para volver a Grid View en cualquier momento, haz clic en el icono que lo reemplaza.

   El Visual Workflow Editor transforma tus eventos en diagramas de flujo interactivos, facilitando la visualización de la ruta que toman tus datos conforme se desplazan por el sistema. Cada evento se asigna como un proceso con puntos de inicio y fin distintos, y los subprocesos marcados con un icono de más se pueden hacer doble clic para explorar capas más profundas de lógica. Puedes usar los botones dedicados para añadir nuevas acciones o validaciones directamente en la secuencia, y seleccionar cualquier nodo para editar sus detalles, eliminarlo o reordenarlo dentro de la cadena lógica. Consulta Visual Workflow Editor para una descripción completa de sus funciones.

5. El evento aún no tiene ninguna acción asociada. Si estás en la Vista de Cuadrícula, notarás que el panel Acciones está vacío; haz clic en su botón Registrar. Si estás en el Editor de Flujo de Trabajo Visual, haz clic en el botón + Acción en la parte superior del panel Diagrama de Eventos. Al hacer esto, se abre el diálogo Acción:

   1. En el campo Tipo, selecciona Regla.

   2. En el campo Regla, selecciona OrderDetail (Delete OrderDetail for Order), la regla de eliminación CRUD que creaste anteriormente.

   3. Deja los otros campos con sus selecciones predeterminadas. Estos incluyen configuraciones de Posición que controlan el orden y el tiempo de ejecución. Consulta Tipos de acciones de eventos para una descripción completa. Haz clic en Guardar. El diálogo de la acción mostrará más detalles:

      

   4. En el panel Vínculos, haz clic en + Vínculo. Selecciona OrderID como Columna de Origen y OrderID como Columna de Regla.

      Nota

      Este paso de vinculación es crítico, ya que filtra los resultados de tu regla por el registro del panel en el que ejecutaste el evento. Si se deja "sin vincular", la regla de eliminación afectaría a todos los registros en la tabla OrderDetail. Al vincular la Columna de Origen (OrderID del registro del panel Order (Source)) a la Columna de Regla (OrderID en nuestra regla de eliminación), agregamos un filtro implícito (por ejemplo, WHERE OrderID = 10248).

      Esto asegura que solo se eliminen los registros de OrderDetail que coincidan con ese OrderID específico. Si se omite este vínculo, al activar el evento se eliminarían todos los registros de la tabla OrderDetail.

   5. Haz clic en Guardar.

6. El evento personalizado ya está listo para implementarse.

Hora de practicar: Añade un control de eliminación

Ahora que tu regla de eliminación y evento están listos, pongámoslos a trabajar en la interfaz. Añade un botón Eliminar Detalles de Orden al panel Órdenes y vinculalo al evento Eliminar Detalles de Orden que acabas de configurar. Esto permite que tus usuarios eliminen los detalles de una orden completa con un solo clic.

Reglas de subconsulta

Una regla de subconsulta actúa como intermediaria de lógica, calculando o ajustando datos antes de pasarlos a otro objeto. A diferencia de las reglas estándar que interactúan directamente con un registro, las subconsultas no escriben datos en las tablas. En su lugar, realizan una operación específica, como una agregación, para generar un valor para usar en otra parte de tu aplicación.

Demostraremos creando una regla de subconsulta. Se utilizará para encontrar el OrderNumber máximo de la tabla Order y luego sumarle uno. Más adelante crearemos una regla CRUD con el propósito de copiar una orden, y dependerá de esta subconsulta para funcionar.

1. En App Workbench > Reglas, haz clic en + Regla.

2. En el campo Nombre, introduce Order (OrderNumber + 1).

3. En el campo Propósito, selecciona Subconsulta.

4. En el campo Destino, selecciona Order.

5. Haz clic en Crear. App Builder creará la nueva regla.

6. App Builder seleccionará automáticamente la clave principal de la tabla Order, pero no la necesitaremos para esta regla. Deselecciónala en la pestaña Tablas.

   ¿Por qué deseleccionar OrderID?

   Al usar una función de agregación como haremos aquí, agregar cualquier otra columna a la consulta (como OrderID) hará que la base de datos aplique una cláusula GROUP BY para esa columna.

Si incluyéramos OrderID, la expresión encontraría el OrderNumber máximo por OrderID. Esto simplemente devolvería el OrderNumber para cada pedido, lo cual no es lo que deseamos.

Para encontrar el único OrderNumber máximo en toda la tabla, no debemos incluir ninguna otra columna en nuestra consulta. Por eso utilizamos una subconsulta: para realizar primero este cálculo de agregación de modo que pueda usarse en otra regla.

1. En la pestaña Columns, haz clic en + Column. Se abrirá el diálogo Column - Add Column.

2. En el campo Column or Expression, ingresa la expresión Max(O.OrderNumber) + 1. La sintaxis Max() invoca la función Max(), que encuentra el valor más grande en la columna O.OrderNumber. Posteriormente, se le suma uno.

3. En el campo Alias and Target, ingresa un alias apropiado para esta columna, como MaxOrderNumber.

4. En el campo Logical Data Type, selecciona Number, ya que OrderNumber no es un valor UUID, sino un número natural.

5. Haz clic en Save.

6. Verifica que la regla funciona correctamente haciendo clic en el botón Results. Solo debe haber una fila con un número de pedido, que debería ser un número mayor que el número de pedido más grande presente actualmente en la tabla Order.

Ahora, vamos a crear una regla CRUD capaz de copiar un pedido. Esta regla CRUD dependerá de la subconsulta que acabamos de crear para funcionar.

1. En App Workbench > Rules, haz clic en + Rule.

2. En el campo Name, ingresa Order (Copy Order).

3. En el campo Purpose, selecciona CRUD.

4. En el campo Action, selecciona Insert.

5. En el campo Target Layer, selecciona Logic Layer.

6. En el campo Target, selecciona Order.

7. Haz clic en Create. App Builder creará la regla.

Una vez que se cree la regla, configura sus columnas y objetivos:

1. En la pestaña Tables, App Builder ha añadido automáticamente la tabla Order, pero necesitaremos más. Haz clic en + Tables.

2. Selecciona la regla de subconsulta que creamos para este propósito, Order (OrderNumber + 1). Haz clic en Add.

3. En la pestaña Tables, marca la casilla junto a la barra de búsqueda en la parte superior de la lista de columnas. Esto selecciona todas las columnas existentes de la tabla Order de una vez.

4. Haz clic en el nombre de la tabla Order. Se abre el diálogo Table. Bajo Select all Columns, activa la casilla. Esto garantiza que cualquier nueva columna añadida a la tabla Order en el futuro se incluya automáticamente en esta regla. Cierra el diálogo.

5. De la tabla de subconsulta Order (OrderNumber + 1), selecciona su única columna, MaxOrderNumber.

6. En la pestaña Columns, perfecciona la asignación de datos de la regla de la siguiente manera:

   • Elimina el objetivo para OrderID. Dado que se trata de una clave principal generada automáticamente, la capa de negocio asignará automáticamente un valor único cuando se ejecute la regla.
   • OrderNumber: Confirma que la fila OON.MaxOrderNumber apunta a OrderNumber, asignando el nuevo valor incrementado a la columna correcta.
   • OrderDate: Haz clic en el campo Column or Expression para esta columna y reemplaza su valor actual con Now() para establecer la fecha del pedido copiado a hoy.
   • No todas las columnas son necesarias en esta regla. Elimina las siguientes:
     • RequiredDate, ShippedDate y Freight: Estos detalles deben ingresarse manualmente para el nuevo pedido en lugar de duplicarse del original.
     • AddedOn, AddedBy, ChangedOn, ChangedBy e IsActive: App Builder genera automáticamente estos valores al crear.

   Lectura adicional

   Obtén más información sobre este concepto en Target in business object rules.

7. Haz clic en Results en el panel Rule para verificar que la regla funciona correctamente.

Ahora vamos a crear una segunda regla CRUD para copiar los elementos de línea del pedido. Esta regla se registrará como controlador de éxito en el evento Copy Order, asegurando que las líneas de detalle solo se creen una vez que exista el nuevo registro de pedido.

1. En App Workbench > Rules, haz clic en + Rule.

2. En el campo Name, ingresa OrderDetail (Insert) Copy Order Detail.

3. En el campo Purpose, selecciona CRUD.

4. En el campo Action, selecciona Insert.

5. En el campo Target Layer, selecciona Logic Layer.

6. En el campo Target, selecciona OrderDetail.

7. Haz clic en Create.

8. En la pestaña Tables, marca la casilla junto a la barra de búsqueda para seleccionar todas las columnas existentes a la vez. Luego haz clic en el nombre de la tabla OrderDetail, habilita Select all Columns en el diálogo Table y cierra el diálogo.

9. En la pestaña Columns, realiza los siguientes cambios:

   • Elimina las columnas de auditoría ligera y seleccionables por el usuario (AddedOn, AddedBy, ChangedOn, ChangedBy, IsActive). Estas se completarán automáticamente al crear.
   • Actualiza la expresión para OrderDetailID a NewUUID(). Esto garantiza que cada artículo de línea copiado reciba su propio identificador único.
   • Elimina el destino para OrderID y establece su alias en BindOrderID. Este valor representa la ID de la orden original, que usaremos para vinculación durante el evento.
   • Agrega una nueva expresión usando Generated() dirigida a OrderID. La función Generated() recupera un valor creado durante la ejecución del evento actual y toma dos argumentos: el valor y el tipo de dato. Ingresa Generated('OrderID', 'UUID') como expresión.

10. Haz clic en Results para verificar la regla.

Ahora hemos creado ambas reglas de copia. Vamos a adjuntar la regla Copy Order a un evento personalizado y vincular la regla Copy Order Lines para que se ejecute automáticamente cuando aquella tenga éxito.

1. En App Workbench > Rules, localiza y abre la regla Order (Source).

2. En el panel Rule, haz clic en Events. Se abre la página All Events (Order (Source)).

3. Haz clic en + Rule Event. Se abre la página Event:

   1. En Event Information, en el campo Name, ingresa Copy Order.

   2. En el campo Refresh Scope, selecciona Panel Refresh. Esto garantiza que el panel se actualice inmediatamente después de que se complete la copia, para que la nueva orden aparezca sin una actualización manual.

   3. En Messages, configura un mensaje de confirmación, éxito y error usando sustitución dinámica. Al usar llaves dobles, puedes extraer datos en tiempo real de la regla subyacente e inyectarlos en el texto. Como este evento está registrado en la regla Order (Source), tienes acceso a todas sus columnas. Por ejemplo:

      • Confirmation: ¿Estás seguro de que deseas duplicar la orden {{OrderNumber}}?
      • Success: ¡La orden {{OrderNumber}} se ha copiado exitosamente!
      • Failure: Error: ¡La orden {{OrderNumber}} no se pudo copiar!

   4. En la sección Execution Properties, marca la casilla Transaction para garantizar la integridad de los datos revirtiendo todo el proceso si alguna parte de la duplicación falla.

   5. Deja los otros campos con sus selecciones predeterminadas y haz clic en Save.

      Nota

      Consulta Event detail options para una descripción completa de todos los campos.

4. El evento se ha creado. En el panel Actions, haz clic en Register. Se abre el diálogo Action:

   1. En el campo Type, selecciona Rule.
   2. En el campo Rule, selecciona Order (Copy Order).
   3. En el panel Bindings, haz clic en + Binding. Selecciona OrderID como Source Column y OrderID como Rule Column. Usar OrderID para vinculación es más confiable que OrderNumber, que puede no ser único.
   4. Guarda.

5. En el panel Actions, hay un campo Handlers que muestra tres botones: Success, Failure y Rollback:

   • Success Handler: Se activa solo cuando la regla principal se completa exitosamente. Úsalo para encadenar lógica, como copiar los detalles de nuestra orden, que depende de que el registro principal exista primero.
   • Failure Handler: Se activa solo si la regla principal encuentra un error. Úsalo para enviar alertas, registrar errores o desencadenar acciones compensatorias.
   • Rollback Handler: Se utiliza cuando se trabaja con sistemas que no admiten transacciones de base de datos estándar, como una API REST de terceros. Ejecuta acciones en orden cronológico inverso para deshacer manualmente la ejecución de la regla hasta ese punto.

Haz clic en Success. Se abre el diálogo Success Handlers. Haz clic en Create. Se abre el diálogo Action:

1. En el campo Type, selecciona Rule.
2. En el campo Rule, selecciona OrderDetail (Insert) Copy Order Detail.
3. Guarda.
4. En el panel Bindings, haz clic en + Binding y asigna lo siguiente:
   • Source Column: Selecciona OrderID (el ID único del pedido que se está copiando actualmente).
   • Rule Column: Selecciona BindOrderID (el alias que creamos en la regla para identificar el registro de origen).

5. Guarda.

6. Cierra los diálogos abiertos y navega al Visual Workflow Editor haciendo clic en el icono . El diagrama de eventos ahora es más complejo que el evento Delete Order Details que revisamos anteriormente. Observa lo siguiente:

   • Logic Layer: Tanto las reglas Copy Order como Copy Order Lines se ejecutan a través de la capa de negocio, por eso ambos bloques de reglas muestran el icono +. Haz doble clic en cualquier bloque para navegar directamente a los eventos principales que desencadena.
   • Conditional paths: Puedes ver las rutas de bifurcación para Success y Failure. La ruta Success muestra la regla Copy Order Lines siendo desencadenada, mientras que la ruta Failure no muestra eventos posteriores, lo que confirma que el proceso se detiene si la copia principal falla.

Tiempo de práctica: Agrega un control de copia

Ahora que tus reglas de copia y evento están listos, pongámoslos a funcionar en la UI. Agrega un botón Copy al panel Orders y vinculalo al evento Copy Order que acabas de crear. Una vez que se agregue el botón, pruébalo: deberías ver el mensaje de confirmación con el número de pedido dinámico y, si tiene éxito, aparecerá un nuevo pedido usando el siguiente número de pedido disponible.

Validaciones

Las reglas de validación se utilizan para asegurar que los datos ingresados en App Builder sean válidos antes de guardarse. En la Lección 7, cubrimos una validación simple de "campo requerido". Ahora, exploraremos un escenario de validación más complejo, que incluye lógica personalizada y mensajes de error dinámicos.

Al igual que otras reglas, las reglas de validación deben adjuntarse a un evento para usarse. La elección del evento depende del caso de uso:

• Intrinsic event: Utiliza esto cuando quieras que la validación se ejecute automáticamente durante operaciones estándar (por ejemplo, impedir que se guarde si los datos no son válidos).

• Custom event: Utiliza esto cuando quieras desencadenar la validación bajo demanda desde un control específico (por ejemplo, un clic en un botón).

Vamos a crear una regla de validación para asegurar que un descuento en un pedido nunca sea mayor al 10%. Queremos que se ejecute cada vez que se guarde un registro OrderDetail, así que la adjuntaremos al evento de guardado intrínseco.

1. En App Workbench > Rules, haz clic en + Rule.

2. En el campo Name, ingresa OrderDetail (Validate Discount).

3. En el campo Purpose, selecciona Validation.

4. En el campo Target, selecciona OrderDetail.

5. Haz clic en Create.

6. En la pestaña Tables, selecciona la columna Discount (puedes deseleccionar OrderDetailID).

7. En la pestaña Where, haz clic en + Where Clause. Se abre un diálogo donde puedes crear cláusulas WHERE:

   

   1. En el campo Left Expression, ingresa OD.Discount.

   2. En el campo Operator, selecciona >.

   3. En el campo Right Expression, ingresa 0.1.

8. Haz clic en Save.

La regla está creada. Está diseñada para encontrar datos "incorrectos" (registros donde el descuento sea mayor al 10%).

Umbral dinámico

En el último paso, codificamos un límite del 10%. Ahora, hagámoslo configurable: almacenaremos el umbral como un parámetro de aplicación para que el negocio pueda actualizarlo desde la UI sin tocar la regla. Aplica los siguientes pasos utilizando habilidades de lecciones anteriores:

1. Agrega una columna DiscountMaximum a la tabla Parameter. Establece el Logical Data Type en Percent y la escala en 4 para capturar valores precisos como 12.25%.

2. Navega a la página Parámetro. En la pantalla de edición de tabla, el botón Páginas proporciona un acceso directo: enumera todas las páginas que actualmente usan esta tabla, lo que te permite ir directamente a la página correcta.

3. Añade DiscountMaximum como un control numérico a la página y complétalo con un valor como .3 para permitir descuentos de hasta el 30%.

4. Regresa a App Workbench > Reglas y abre la regla OrderDetail (Validar Descuento).

5. En la pestaña Tablas, haz clic en + Tablas y añade la tabla Parámetro. Selecciona la columna DiscountMaximum.

6. En la pestaña Donde, haz clic en el icono de lápiz para editar la cláusula WHERE. En el campo Expresión Derecha, reemplaza 0.1 con P.DiscountMaximum.

Cualquier valor establecido en la página Parámetro ahora controla el umbral para esta validación.

Adjunta la regla de validación

Ahora, vamos a adjuntar la regla de validación al evento de guardado intrínseco para OrderDetail.

1. En App Workbench > Reglas, encuentra el objeto comercial OrderDetail (Origen) y ábrelo.

2. En el panel Regla, haz clic en Eventos. Se abre la página Todos los Eventos (OrderDetail (Origen)).

3. Encuentra la fila Guardar. Observa que hay dos botones del diseñador: Detalle de Evento de Tabla y Detalle de Evento de Regla. Queremos registrar esta validación utilizando Detalle de Evento de Regla. Esta es una distinción importante: garantiza que la validación solo se aplique cuando se utiliza esta regla específica, en lugar de imponer una restricción global en toda la tabla OrderDetail. Esto mantiene la aplicación flexible. Por ejemplo, podrías construir posteriormente una página de Aprobación de Gerente. Al usar un objeto comercial diferente allí, un supervisor podría autorizar descuentos más altos sin ser bloqueado por la regla estándar que estamos construyendo aquí. Haz clic en Detalle de Evento de Regla para el evento Guardar.

4. En el panel Validaciones, haz clic en Registrar. Se abre el diálogo Validación:

   

5. En el campo Tipo, selecciona Regla.

6. En el campo Regla, selecciona OrderDetail (Validar Descuento), la regla de validación que acabamos de crear.

7. En el campo Vinculación, selecciona Implícita.

   Nota

   La vinculación implícita valida contra los datos actualmente "en memoria" en la pantalla del usuario. Este es el valor que el usuario ha escrito, antes de que se haya guardado en la base de datos. Utilizamos la vinculación implícita aquí porque queremos impedir que el usuario guarde un registro nuevo mientras el valor Descuento sea inválido (es decir, mayor que el umbral configurado). Por otro lado, la vinculación explícita valida contra los datos que ya están guardados en la base de datos.

   Para ilustrar, imagina que se guardó un registro con un descuento inválido del 50%. Un usuario abre ese registro, corrige el campo Descuento a un valor válido como 7% y lo envía. Si el evento de validación utiliza vinculación explícita, verificará la base de datos, verá el valor original del 50% y fallará la validación. Sin embargo, si el evento de validación utiliza vinculación implícita, verificará el valor en memoria (7%), verá que no es mayor que el umbral y aprobará la validación, permitiendo el guardado.

   Lee más en Vinculación implícita y explícita.

8. En el campo Falla, selecciona Fallar cuando se devuelven datos.

   Nota

   Las validaciones de App Builder pueden configurarse de dos formas. La predeterminada, que estamos utilizando, es Fallar cuando se devuelven datos. Esto significa que la regla de validación se escribe para encontrar los datos malos (por ejemplo, Descuento es mayor que el umbral). Si la regla encuentra algún registro que coincida con este criterio "malo", falla y muestra el mensaje de error. La alternativa es Fallar cuando no se devuelven datos, que se utiliza cuando una regla se escribe para encontrar datos buenos.

9. En el campo Severidad, selecciona Error.

   Nota

   El campo Severidad determina la fuerza con la que App Builder interactúa con el usuario cuando se activa una validación:

   • Error: El nivel más crítico. Indica un problema importante e impide completamente el guardado. El usuario ve una notificación roja y debe corregir los datos antes de poder continuar.
   • Advertencia: Un bloqueo suave. Alerta al usuario sobre un posible problema con una notificación amarilla, pero le da la opción de cancelar y corregirlo o proceder a guardar el registro de todas formas.
   • Información: Puramente informativo. Proporciona una notificación azul después de que se ejecute el evento para darle al usuario un contexto útil, pero nunca detiene ni interrumpe el flujo de trabajo.

10. En el campo Message, ingresa: Discount cannot be greater than {{ DiscountMaximum }}. Usar sustitución dinámica aquí garantiza que el mensaje de error refleje automáticamente cualquier umbral que esté establecido en la página Parameter.

11. Haz clic en Save para cerrar el diálogo.

La validación está adjunta. Para probarla, ve a la vista previa de la página Orders, selecciona una orden e intenta editar un elemento OrderDetail para que tenga un descuento mayor que el umbral que estableciste. Cuando hagas clic para guardar, deberías ver el mensaje de error dinámico.

Para que el marcador de posición {{ DiscountMaximum }} se resuelva correctamente, la columna debe estar disponible en el objeto de negocio OrderDetail (Source). Como DiscountMaximum se encuentra en una tabla Parameter separada, necesitas agregarlo explícitamente:

1. Regresa a App Workbench > Rules y abre la regla OrderDetail (Source).

2. En la pestaña Tables, haz clic en + Tables y agrega la tabla Parameter. Selecciona la columna DiscountMaximum.

El nombre de la columna en la regla debe coincidir exactamente con el marcador de posición en tu mensaje de validación. Si hubieras usado un nombre diferente en el mensaje (por ejemplo, {{ MaxDiscount }}), necesitarías asignar un alias a la columna en la regla para que coincida.

Aprendizaje adicional

Esto concluye esta inmersión profunda en los detalles de la capa de negocio de App Builder. Consulta Appendix A para un análisis más detallado de la capa de datos, Appendix C para la capa de interfaz de usuario o Appendix D para la capa de seguridad.