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 objetos de negocio o reglas.

Uniones

Las uniones, introducidas 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, añadiendo columnas de una segunda tabla junto a las columnas de la primera.

Las uniones funcionan de manera diferente: en lugar de añadir columnas, apilan filas. Una unión añade los resultados de una consulta sobre 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 eso podemos combinar directamente las columnas Country de nuestras tablas Customer y Supplier: 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, Supplier y Customer, que contienen una columna llamada Country, así que combinaremos las entradas de ambas.

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

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

   1. En el campo Name, ingresa Supplier (Countries for Supplier and Customer).

   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, añade 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 SupplierID, selecciona la columna País y márcala como la clave primaria.

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

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

6. Ve a la pestaña Uniones.

7. App Builder ha creado una unión, pero ajústala para que sea del 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 tus 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 están basados 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. Navega de regreso al Constructor de Reglas.

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

13. Marca la casilla 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 Resultados nuevamente. La regla ahora devuelve una lista distinta de todos los países representados en las tablas Cliente y Proveedor.

Tiempo de práctica: Usa tu regla de unión como control de lista

Ahora, pongamos en práctica tu nueva regla de unión. Navega a las páginas emergentes de Cliente y Proveedor y cambia el tipo de control del campo País a Lista. En la pestaña de Opciones de Lista, selecciona el objeto de negocio de unión que acabas de crear y establece tanto la Clave como el Título en la columna País.

Reglas CRUD

Introdujimos las reglas CRUD en Lección 7, pero ahora echemos un vistazo más de cerca a ellas.

El acrónimo CRUD significa "Crear, Leer, Actualizar, Eliminar". Esto significa que las reglas CRUD son lo que los desarrolladores de App Builder utilizan para insertar, recuperar, alterar o borrar registros de las tablas presentes en la fuente de datos.

Capa de destino: negocio vs. datos

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

Dirigirse a la capa de negocio es el enfoque recomendado para la mayoría de las operaciones. Cuando tu regla CRUD se dirige a la capa de negocio (por ejemplo, el objeto de negocio Orden (Fuente)), actúa como un usuario interactuando con la aplicación. Esto desencadena todos los eventos intrínsecos (Guardar, Actualizar, etc.) asociados con ese objeto de negocio. Esto significa que todas tus reglas de validación configuradas, acciones personalizadas y seguimiento de auditoría ligera se ejecutarán automáticamente. Este enfoque asegura la integridad y consistencia de los datos con la lógica de tu aplicación. También te permite utilizar controladores de éxito, fracaso y reversión para el evento.

Dirigirse a la capa de datos elude toda la lógica de negocio. Cuando te diriges a la capa de datos (por ejemplo, la tabla Orden), 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 de negocio. Este es un enfoque de "puerta trasera", útil para operaciones masivas de alto rendimiento donde deseas eludir intencionalmente la lógica de negocio.

Puedes ver esta diferencia visualmente en el flujo de trabajo visual; una regla que apunte a la capa de negocio mostrará subprocessos para su lógica de eventos, mientras que una que apunte 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 > Reglas, haz clic en + Regla.

2. En el campo Nombre, ingresa OrderDetail (Cantidad + 1).

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

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

5. En Capa de Destino, selecciona Capa de Datos. (Para esta simple actualización masiva, evitaremos la lógica de negocio).

6. En el campo Destino, selecciona OrderDetail.

7. Haz clic en Crear. App Builder tomará unos segundos para crear la regla.

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

9. Agregaremos una nueva columna con un alias para ayudarnos a visualizar que la regla está funcionando. Ve a la pestaña Columnas y haz clic en + Columna. Cuando se abra el cuadro de diálogo Columna - Agregar Columna, ingresa la siguiente información:

   1. En el campo Columna o Expresión, ingresa OD.Quantity + 1.

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

   3. En el campo Destino, selecciona Cantidad. Esto le indica a App Builder que escriba el resultado de esta expresión en la columna Cantidad.

   4. Haz clic en Guardar.

10. En la pestaña Columnas, ahora verás tanto Cantidad como CantidadPlus. La columna original OD.Quantity también estará dirigida a Cantidad por defecto. Debemos desmarcarla para evitar ambigüedades:

    1. Encuentra la fila OD.Quantity en la lista de Columnas.

    2. Haz clic en su menú desplegable Target. Aparece un botón X junto a él. Haz clic en él para desasignar la columna.

       Esto asegura que solo se use nuestra expresión QuantityPlus para actualizar la columna Quantity. Si ambas estuvieran asignadas, la que tenga el índice más alto "ganaría", lo que llevaría a un comportamiento impredecible.

11. La regla está lista. En el panel Rule, haz clic en el panel Results para ver cómo funciona. Observa que la columna adicional que has agregado 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 modifica todas las entradas en la columna Quantity 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 al crear reglas que son similares a las que ya has construido.

1. En App Workbench > Rules, localiza la regla OrderDetail (Quantity + 1) y haz clic en More > Copiar Regla.

2. Haz clic en Copiar.

3. App Builder crea la nueva regla, nombrándola OrderDetail (Quantity + 1) (New). Se te lleva directamente a su pantalla de edición. En el panel Rule, actualiza el campo Name a OrderDetail (Quantity - 1), luego navega a la pestaña Columns.

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

5. Verifica que la regla esté funcionando correctamente haciendo clic en Results en el panel Rule.

Tiempo de práctica: Agregar controles de cantidad

Ahora que tienes ambas reglas de cantidad, conéctalas al panel Order Details en la página de Orders.

1. Abre el objeto de negocio OrderDetail (Source) y crea un evento personalizado para la regla OrderDetail (Quantity + 1). En el cuadro de diálogo de creación de eventos, ingresa Quantity Plus en el campo Name y establece Refresh Scope en Row. Esto asegura que cuando se active el evento, solo se actualice la fila afectada en lugar de todo el panel.

2. Repite el paso 1 para crear un segundo evento llamado Quantity Minus, adjuntando la regla OrderDetail (Quantity - 1) y también estableciendo Refresh Scope en Row.

3. Navega a la pantalla de edición de la página Orders. En el panel Order Details, agrega dos controles de Button: uno que ejecute el evento Quantity Plus y otro que ejecute el evento Quantity Minus.

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

CRUD eliminar

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

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

2. En el campo Name, ingresa OrderDetail (Delete OrderDetail for Order).

3. En el campo Purpose, selecciona CRUD.

4. En el campo Action, selecciona Delete.

5. Bajo Target Layer, selecciona Data Layer.

6. En el campo Target, selecciona OrderDetail.

7. Haz clic en Create.

8. En la pestaña Tables, App Builder ha agregado la tabla OrderDetail y seleccionado su clave primaria, OrderDetailID. Mantén esta selección, ya que apuntar a la clave primaria es la forma más eficiente y segura de realizar una operación de eliminación. Selecciona también la columna OrderID; utilizaremos esta columna en la siguiente sección para vincular la regla a un pedido específico.

Events

Las reglas CRUD solo se pueden usar cuando están adjuntas a events, 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 a medida que alteras registros en App Builder.

Vamos a activar las reglas CRUD que creamos. Para hacerlo, crearemos nuestros propios eventos personalizados. A diferencia de los eventos intrínsecos, los eventos personalizados deben estar adjuntos a un control para poder ejecutarse. Las reglas CRUD que estamos creando requieren eventos personalizados para ejecutarse cuando lo deseamos.

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

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)). 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. Debido a que estamos creando un evento personalizado, haz clic en + Rule Event. Se abre la página Event, donde puedes agregar 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 aprender sobre los 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: dado que nuestra regla de eliminación afecta múltiples elementos de línea, una transacción garantiza que si ocurre un error a mitad de camino, App Builder revierta todos los cambios. Esto previene un escenario en el que algunos registros se eliminan 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 Guardar. App Builder creará el evento.

      Nota

      Para escenarios de acceso concurrente donde la integridad de los datos podría verse comprometida, App Builder también proporciona Bloqueo de Eventos, que obliga a la ejecución en serie y puede ser limitado a registros individuales. Deja esto desmarcado para el evento actual, pero tenlo en cuenta para entornos de alto tráfico o flujos de trabajo complejos donde la sincronización a nivel de registro sea un requisito.

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

   

   Actualmente estás en la Vista de Cuadrícula (mostrada 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 Editor de Flujo Visual, que muestra el orden de ejecución y la relación entre eventos heredados. Para verlo, haz clic en el ícono en el panel de Evento. Para regresar a la Vista de Cuadrícula en cualquier momento, haz clic en el ícono que lo reemplaza.

   El Editor de Flujo Visual transforma tus eventos en diagramas de flujo interactivos, facilitando la visualización del camino que toman tus datos a medida que se mueven a través del sistema. Cada evento se mapea como un proceso con puntos de inicio y fin distintos, y los subprocesos marcados con un ícono de más se pueden hacer doble clic para profundizar en capas más profundas de lógica. Puedes usar los botones dedicados para agregar 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 Editor de Flujo Visual para una descripción completa de sus características.

5. El evento aún no tiene acciones adjuntas. Si estás en la Vista de Cuadrícula, nota que el panel de Acciones está vacío, y haz clic en su botón de Registrar. Si estás en el Editor de Flujo Visual, haz clic en el botón + Acción en la parte superior del panel de Diagrama de Evento. Hacer esto abre el diálogo de Acción:

   1. En el campo Tipo, selecciona Regla.

   2. En el campo Regla, selecciona OrderDetail (Eliminar OrderDetail para Pedido), la regla de eliminación CRUD que hemos creado previamente.

   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 evento para una descripción completa. Haz clic en Guardar. El diálogo para la acción mostrará más detalles:

      

   4. En el panel de Vinculaciones, haz clic en + Vinculación. Selecciona OrderID como la Columna de Origen y OrderID como la 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 contra el cual has ejecutado 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 Pedido (Origen)) a la Columna de Regla (OrderID en nuestra regla de eliminación), añadimos 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 omitiera esta vinculación, activar el evento eliminaría todos los registros de la tabla OrderDetail.

   5. Haz clic en Guardar.

6. El evento personalizado ahora está listo para ser implementado.

Tiempo de práctica: Agregar un control de eliminación

Ahora que tu regla de eliminación y evento están listos, pongámoslos a trabajar en la interfaz de usuario. Agrega un botón de Eliminar Detalles del Pedido al panel de Pedidos y vincúlalo al evento de Eliminar Detalles del Pedido que acabas de configurar. Esto permite a tus usuarios eliminar todos los detalles de un pedido con un solo clic.

Reglas de subconsulta

Una regla de subconsulta actúa como un intermediario lógico, 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 de vuelta en las tablas. En su lugar, realizan una operación específica, como una agregación, para generar un valor que se utilizará en otra parte de tu aplicación.

Demostraremos haciendo una regla de subconsulta. Se utilizará para encontrar el OrderNumber máximo de la tabla Order, y luego se le sumará uno. Más adelante crearemos una regla CRUD con el propósito de copiar un pedido, y dependerá de esta subconsulta para funcionar.

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

2. En el campo Name, ingresa Order (OrderNumber + 1).

3. En el campo Purpose, selecciona Subquery.

4. En el campo Target, selecciona Order.

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

6. App Builder seleccionará automáticamente la clave primaria de la tabla Order, pero no la necesitaremos para esta regla. Desmárcala en la pestaña Tables.

   ¿Por qué desmarcar OrderID?

   Al usar una función de agregación como lo 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 solo devolvería el OrderNumber para cada pedido, lo cual no es lo que queremos.

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

7. En la pestaña Columnas, haz clic en + Columna. Se abrirá el diálogo Columna - Agregar Columna.

8. En el campo Columna o Expresión, 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. Luego, se le suma uno.

9. En el campo Alias y Objetivo, ingresa un alias apropiado para esta columna, como MaxOrderNumber.

10. En el campo Tipo de Dato Lógico, selecciona Número, ya que OrderNumber no es un valor UUID, sino un número natural.

11. Haz clic en Guardar.

12. Verifica que la regla esté funcionando correctamente haciendo clic en el botón Resultados. Debería haber solo una fila con un número de orden, que debería ser un número mayor que el mayor número de orden actualmente presente en la tabla Order.

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

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

2. En el campo Nombre, ingresa Pedido (Copiar Pedido).

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

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

5. En el campo Capa Objetivo, selecciona Capa Lógica.

6. En el campo Objetivo, selecciona Pedido.

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

Una vez que la regla esté creada, configura sus columnas y objetivos:

1. En la pestaña Tablas, App Builder ha agregado automáticamente la tabla Pedido, pero necesitaremos más. Haz clic en + Tablas.

2. Selecciona la regla de subconsulta que hemos creado para este propósito, Pedido (OrderNumber + 1). Haz clic en Agregar.

3. En la pestaña Tablas, 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 Pedido a la vez.

4. Haz clic en el nombre de la tabla Pedido. Se abre el diálogo Tabla. Bajo Seleccionar todas las Columnas, habilita la casilla. Esto asegura que cualquier nueva columna añadida a la tabla Pedido en el futuro se incluya automáticamente en esta regla. Cierra el diálogo.

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

6. En la pestaña Columns, refina el mapeo de datos de la regla de la siguiente manera:

   • Elimina el objetivo para OrderID. Dado que esta es una clave primaria autogenerada, la capa de negocio asignará automáticamente un valor único cuando se ejecute la regla.
   • OrderNumber: Confirma que la fila OON.MaxOrderNumber apunte a OrderNumber, mapeando 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 en hoy.
   • No todas las columnas son necesarias en esta regla. Elimina lo siguiente:
     • 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 autogenera estos valores al momento de la creación.

   Lectura adicional

   Aprende más sobre este concepto en Target in business object rules.

7. Haz clic en Results en el panel de Rule para verificar que la regla esté funcionando correctamente.

Ahora vamos a crear una segunda regla CRUD para copiar los elementos de línea del pedido. Esta regla se registrará como un 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 de Table y cierra el diálogo.

9. En la pestaña Columnas, 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 momento de la creación.
   • Actualiza la expresión para OrderDetailID a NewUUID(). Esto asegura que cada línea de artículo copiada reciba su propio identificador único.
   • Elimina el objetivo para OrderID y establece su alias como BindOrderID. Este valor representa el ID del pedido original, que utilizaremos para enlazar durante el evento.
   • Agrega una nueva expresión usando Generated() con el objetivo de OrderID. La función Generated() recupera un valor creado durante la ejecución actual del evento y toma dos argumentos: el valor y el tipo de dato. Ingresa Generated('OrderID', 'UUID') como la expresión.

10. Haz clic en Resultados para verificar la regla.

Ahora hemos creado ambas reglas de copia. Vamos a adjuntar la regla Copiar Pedido a un evento personalizado y conectar la regla Copiar Líneas de Pedido para que se ejecute automáticamente en su éxito.

1. En App Workbench > Reglas, localiza y abre la regla Pedido (Fuente).

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

3. Haz clic en + Evento de Regla. Se abre la página Evento:

   1. En Información del Evento, en el campo Nombre, ingresa Copiar Pedido.

   2. En el campo Actualizar Alcance, selecciona Actualizar Panel. Esto asegura que el panel se actualice inmediatamente después de que la copia se complete, para que el nuevo pedido aparezca sin necesidad de una actualización manual.

   3. En Mensajes, configura un mensaje de confirmación, éxito y fallo utilizando sustitución dinámica. Al usar dobles llaves, puedes extraer datos en tiempo real de la regla subyacente e inyectarlos en el texto. Dado que este evento está registrado en la regla Pedido (Fuente), tienes acceso a todas sus columnas. Por ejemplo:

      • Confirmación: ¿Está seguro de que desea duplicar el pedido {{OrderNumber}}?
      • Éxito: ¡El pedido {{OrderNumber}} se ha copiado con éxito!
      • Fallo: Error: ¡El pedido {{OrderNumber}} no se pudo copiar!

   4. En la sección de Propiedades de Ejecución, marque la casilla de Transacción para garantizar la integridad de los datos al revertir todo el proceso si alguna parte de la duplicación falla.

   5. Deje los otros campos con sus selecciones predeterminadas y haga clic en Guardar.

      Nota

      Consulte Opciones de detalle del evento para una descripción completa de todos los campos.

4. El evento ha sido creado. En el panel de Acciones, haga clic en Registrar. Se abre el diálogo de Acción:

   1. En el campo de Tipo, seleccione Regla.
   2. En el campo de Regla, seleccione Pedido (Copiar Pedido).
   3. En el panel de Vinculaciones, haga clic en + Vinculación. Seleccione OrderID como la Columna de Origen y OrderID como la Columna de Regla. Usar OrderID para la vinculación es más confiable que OrderNumber, que puede no ser único.
   4. Guarde.

5. En el panel de Acciones, hay un campo de Controladores que muestra tres botones: Éxito, Fallo y Revertir:

   • Controlador de Éxito: Se activa solo cuando la regla principal se completa con éxito. Úselo para encadenar lógica, como copiar los detalles de nuestro pedido, que depende de que el registro principal exista primero.
   • Controlador de Fallo: Se activa solo si la regla principal encuentra un error. Úselo para enviar alertas, registrar errores o activar acciones compensatorias.
   • Controlador de Revertir: Se utiliza al trabajar 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.

   Haga clic en Éxito. Se abre el diálogo de Controladores de Éxito. Haga clic en Crear. Se abre el diálogo de Acción:

   1. En el campo de Tipo, seleccione Regla.
   2. En el campo de Regla, seleccione OrderDetail (Insertar) Copiar Detalle del Pedido.
   3. Guarde.
   4. En el panel de Vinculaciones, haga clic en + Vinculación y mapee lo siguiente:
      • Columna de Origen: Seleccione OrderID (el ID único del pedido que se está copiando actualmente).
      • Columna de Regla: Seleccione BindOrderID (el alias que creamos en la regla para identificar el registro de origen).
   5. Guarde.

6. Salga de los diálogos abiertos y navegue al Editor de Flujo de Trabajo Visual haciendo clic en el ícono . El diagrama de eventos es ahora más complejo que el evento Eliminar Detalles del Pedido que revisamos anteriormente. Observe lo siguiente:

   • Capa de Lógica: Tanto las reglas Copiar Pedido como Copiar Líneas de Pedido se ejecutan a través de la capa de negocio, por lo que ambos bloques de reglas muestran el ícono +. Haga doble clic en cualquiera de los bloques para navegar directamente a los eventos padres que activa.
   • Rutas Condicionales: Puede ver las rutas de ramificación para Éxito y Fallo. La ruta de Éxito muestra la regla Copiar Líneas de Pedido siendo activada, mientras que la ruta de Fallo no muestra eventos subsiguientes, confirmando que el proceso se detiene si la copia principal falla.

Tiempo de práctica: Agregar un control de copia

Ahora que sus reglas de copia y evento están listas, pongámoslas a trabajar en la interfaz de usuario. Agregue un botón Copiar al panel de Pedidos y vincúlelo al evento Copiar Pedido que acaba de crear. Una vez que se agregue el botón, pruébelo: debería ver el mensaje de confirmación con el número de pedido dinámico, y al tener éxito, aparecerá un nuevo pedido utilizando 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 que se guarden. En 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 estar adjuntas a un evento para ser utilizadas. La elección del evento depende del caso de uso:

• Evento intrínseco: Utilice esto cuando desee que la validación se ejecute automáticamente durante las operaciones estándar (por ejemplo, prevenir un guardado si los datos son inválidos).

• Evento personalizado: Utilice esto cuando desee activar la validación a demanda desde un control específico (por ejemplo, un clic en un botón).

Creemos una regla de validación para asegurar que un descuento en un pedido nunca sea mayor al 10%. Queremos que esto se ejecute cada vez que se guarde un registro de DetallePedido, por lo que lo 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 ahora está creada. Está diseñada para encontrar datos "malos" (registros donde el descuento es superior al 10%).

Dynamic threshold

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 interfaz de usuario sin tocar la regla misma. 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 Parameter. En la pantalla de edición de la tabla, el botón Pages proporciona un acceso directo: lista todas las páginas que actualmente utilizan esta tabla, permitiéndote saltar directamente a la página correcta.

3. Agrega DiscountMaximum como un control numérico a la página y pópulalo con un valor como .3 para permitir descuentos de hasta el 30%.

4. Regresa a App Workbench > Rules y abre la regla OrderDetail (Validate Discount).

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

6. En la pestaña Where, haz clic en el ícono de lápiz para editar la cláusula WHERE. En el campo Right Expression, reemplaza 0.1 con P.DiscountMaximum.

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

Adjuntar la regla de validación

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

1. En App Workbench > Rules, encuentra el objeto de negocio OrderDetail (Source) y ábrelo.

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

3. Encuentra la fila de Guardar. Nota que hay dos botones de diseñador: Detalle del Evento de Tabla y Detalle del Evento de Regla. Queremos registrar esta validación usando Detalle del Evento de Regla. Esta es una distinción importante: asegura que la validación solo se aplique cuando se utilice esta regla de negocio específica, en lugar de imponer una restricción global en toda la tabla de OrderDetail. Esto mantiene la aplicación flexible. Por ejemplo, más adelante podrías construir una página de Aprobación del Gerente. Al usar un objeto de negocio 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 del Evento de Regla para el evento de Guardar.

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

   

5. En el campo de Tipo, selecciona Regla.

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

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

   Nota

   La vinculación implícita valida contra los datos que actualmente están "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. Usamos la vinculación implícita aquí porque queremos detener al usuario de guardar un nuevo registro mientras el valor de Descuento es 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 un registro se guardó con un descuento inválido del 50%. Un usuario abre ese registro, corrige el campo de Descuento a un valor válido como el 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 pasará la validación, permitiendo el guardado.

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

8. En el campo Failure, selecciona Fail on data returned.

   Nota

   Las validaciones del App Builder se pueden configurar de dos maneras. La predeterminada, que estamos utilizando, es Fail on data returned. Esto significa que la regla de validación está escrita para encontrar los datos incorrectos (por ejemplo, Discount 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 Fail on no data returned, que se utiliza cuando se escribe una regla para encontrar datos buenos.

9. En el campo Severity, selecciona Error.

   Nota

   El campo Severity determina cuán enérgicamente interactúa el App Builder con el usuario cuando se activa una validación:

   • Error: El nivel más crítico. Indica un problema mayor y evita que se guarde completamente. El usuario ve una notificación roja y debe corregir los datos antes de poder continuar.
   • Warning: 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 continuar y guardar el registro de todos modos.
   • Information: Puramente informativo. Proporciona una notificación azul después de que se ejecuta el evento para dar 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í asegura que el mensaje de error refleje automáticamente cualquier umbral que esté configurado actualmente en la página Parameter.

11. Haz clic en Save para salir del diálogo.

La validación está adjunta. Para probarla, ve a la vista previa de la página Orders, selecciona un pedido y trata de editar un ítem de OrderDetail para que tenga un descuento mayor que el umbral que configuraste. Cuando hagas clic en 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). Dado que 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 utilizado un nombre diferente en el mensaje (por ejemplo, {{ MaxDiscount }}), tendrías que aliasar 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 Apéndice A para un vistazo más cercano a la capa de datos, o Apéndice C para la capa de UI.