Escribir una directiva de datos

Objetivo

Añadir una regla que la plataforma no incluye («no por encima de su límite de aprobación», «no una vez facturado») y filtrar por ella el permiso de un rol.

Requisitos previos

• Ha iniciado sesión en el Centro de control de administración, hay un entorno seleccionado y ha abierto la solución a la que debe pertenecer la directiva: ahí está la pantalla, porque la directiva viaja en el paquete de esa solución.
• Conoce los nombres lógicos de los campos que lee su regla. Están en la pantalla Campos de la tabla.

Tres tipos, y cómo elegir el adecuado

Las directivas integradas responden a qué registros: los míos, los de mi unidad, los de todos. Cubren casi todo lo que necesita un rol. Escriba una propia cuando no basten, y lo primero que hay que decidir es de qué tipo:

	Qué registros	Regla en cada registro
Qué es	una condición convertida en un filtro de base de datos	una regla que se comprueba al guardar un registro
Úsela cuando	la respuesta depende de quién pregunta: su región, su equipo	la respuesta depende de lo que dice el registro: un límite de aprobación, un estado
Qué ve un usuario	los registros simplemente no están	un mensaje que explica por qué se rechazó el guardado
Ejemplo	Record.par_region == CurrentUser.par_region	«Ese total supera su límite de aprobación».

Una directiva Qué registros es la mejor herramienta siempre que encaja: los registros que excluye nunca salen del servidor, así que aplicarla no cuesta nada y no hay ningún mensaje que nadie tenga que leer. Pero no lo puede hacer todo: se convierte en una consulta, así que solo puede comparar campos con valores.

Una directiva Regla en cada registro es la que puede decir Total is under my approval limit, porque esa no es una pregunta sobre qué registros existen. Se ejecuta sobre cada registro que se guarda y puede explicarse.

El tercer tipo, De quién son los registros (portal), no es para personas con la sesión iniciada: responde a la misma pregunta de «qué registros» para un visitante de un portal, y se declara en una tabla en lugar de concederse a un rol. Si es eso lo que busca, esta no es la página adecuada: consulte Decidir de quién son los registros que ve un visitante.

Si su regla es en realidad «todo el mundo debe rellenar esto», lo que quiere es una regla de negocio o un paso de complemento en la tabla: se aplican a todos, que es lo que significa una regla de calidad de datos. Una directiva se aplica a quien tiene un permiso sujeto a ella, que es lo que significa un permiso.

Pasos

1. Abra Soluciones, abra la solución en la que vive su aplicación y seleccione Directivas de datos en su navegación. La pantalla muestra las directivas que contiene esta solución; la solución predeterminada («Main») muestra todas las directivas del entorno.

2. Seleccione Nuevo.

3. Asígnele un nombre para mostrar: así se llamará en la lista de directivas de la pantalla de roles. El nombre lógico se rellena solo con el prefijo de su editor; puede cambiarlo ahora, pero no después, porque es el nombre al que se referirá cada concesión.

4. Elija el tipo. Decide qué pide el resto del formulario y no se puede cambiar después. Los pasos siguientes son para Regla en cada registro; para Qué registros, vaya a Escribir una directiva Qué registros.

5. Elija Qué registros. En una directiva de regla, es la directiva integrada que filtra las listas, y no es opcional: consulte Por qué una directiva de regla también necesita un ámbito. Todos los registros significa «todo, sujeto a mi regla».

6. Marque las operaciones en las que se comprobará la regla. De forma predeterminada son crear, actualizar y eliminar. Deje la lectura desmarcada salvo que lo quiera de verdad: una regla que rechaza una lectura hace que los registros desaparezcan de las listas por un motivo que nadie puede ver.

7. Escriba la regla. Está en BS Lang, el mismo lenguaje que una regla de negocio, y se ejecuta sobre un registro:

   if (getValue("par_total") > currentUser("par_approvallimit")) {
     deny("That total is over your approval limit.");
   }

   Llame a deny("…") para rechazar. Una regla que no rechaza nada permite la operación. El mensaje que escriba es lo que ve el usuario, así que diga qué haría aceptable el registro, no que algo estaba mal.

8. Seleccione Guardar. Si la regla no se puede analizar, el guardado falla e indica dónde. Es deliberado: la alternativa es enterarse cuando alguien es rechazado por una regla que no se puede ejecutar.

9. Abra la pantalla Roles de la solución y, en la celda del permiso que quiere filtrar, elija su nueva directiva. Aparece en la misma lista que las integradas.

Escribir una directiva Qué registros

Una directiva Qué registros se convierte en una consulta de base de datos, así que se escribe de otra forma y pide otras cosas.

1. Elija la tabla. A diferencia de una regla, este tipo de directiva se escribe sobre los campos de una tabla, así que tiene que nombrar una, y nombrarla es lo que permite a la plataforma comprobar al guardar que esos campos existen. Solo se ofrecerá en la fila de esa tabla en la pantalla Roles de la solución.

2. Escriba la condición: una condición, no un script:

   Record.par_region == CurrentUser.par_region && Record.par_status != "Closed"

   Record.<field> es un campo de la tabla elegida. CurrentUser.<name> es un dato de la persona con la sesión iniciada: los mismos nombres que aparecen en Qué puede leer una regla, más cualquier campo de la tabla de usuarios. Combine condiciones con && y ||, y agrúpelas con paréntesis.

3. Comparar con un conjunto significa «es uno de»: Record.owning_unit == CurrentUser.UnitsAndBelow selecciona los registros que se poseen en cualquier punto de su unidad o por debajo de ella. También puede comparar con una lista escrita: Record.par_status == ["Draft", "Submitted"].

4. Seleccione Guardar. Todo lo que la plataforma no pueda convertir en una consulta se rechaza en ese momento, con el motivo; consulte más abajo.

Lo que no puede expresar una condición

Esto es deliberadamente limitado, porque todo lo que contiene tiene que convertirse en una consulta de base de datos:

No permitido	Porque	En su lugar
>=, <=	no existe un operador de consulta para ellos	> o <
!(…)	una consulta no se puede negar	diga qué conservar, usando !=
length(x), cualquier función	habría que ejecutarla, y un filtro no se ejecuta	compare el campo directamente
Record.total * 2 > 100	la aritmética impide que una consulta use un índice	compare con el número al que se refiere
Record.account.owner	seguir una búsqueda es una combinación (join), y una combinación oculta es lenta en cada consulta	un campo de esta tabla
varias condiciones en varias líneas	una directiva es una sola condición	combínelas con &&

Todo esto se rechaza al guardar, indicando la línea. Es el único motivo de que el lenguaje de condiciones sea tan reducido: una condición que la plataforma no pudiera aplicar, sin avisar, mostraría registros que alguien creía ocultos.

Qué puede leer una regla

Llamada	Le da
getValue("par_total")	El registro tal como quedará después del cambio.
getPreValue("par_total")	El registro tal como está guardado ahora. Vacío al crear.
currentUser("par_approvallimit")	Un campo del propio registro de usuario de la persona con la sesión iniciada.
isOwner()	Si esta persona posee el registro.
hasRole("Manager")	Si tiene un rol.
operation()	Create, Read, Update o Delete.
entityName()	El nombre lógico de la tabla.
deny("…")	Rechazar, con el motivo que leerá el usuario.

currentUser lee la tabla de usuarios de este entorno, así que para comparar con un límite de aprobación primero tiene que añadir ese campo a ella, exactamente como lo haría con cualquier otra tabla.

Por qué una directiva de regla también necesita un ámbito

Una regla necesita un registro que ya se haya cargado. Una lista es precisamente lo que se tiene antes de cargar ninguno, así que una regla no puede filtrarla: la plataforma tendría que obtener todas las filas para decidir qué filas obtener. Una directiva Qué registros tiene la propiedad contraria, y por eso precisamente es un tipo aparte y no una regla más ingeniosa.

Así que una directiva de regla lleva ambas cosas: Qué registros es una directiva integrada que la plataforma traslada a la base de datos, y la regla se comprueba después sobre cada registro que alguien realmente abre, guarda o elimina. Establezca Qué registros en la directiva integrada más restringida que sea cierta, y deje que la regla se encargue del resto.

Desactivar una

Desmarque En vigor y guarde. La directiva sigue existiendo y todas las concesiones sujetas a ella siguen funcionando, solo con su respuesta de Qué registros y sin comprobar la regla. Es lo prudente mientras averigua por qué una regla rechaza algo; eliminar la directiva no lo es, y la plataforma no le dejará eliminar una que todavía use un rol.

Una directiva Qué registros no tiene ese interruptor, y no es un descuido: es la respuesta a qué registros, así que desactivarla solo podría significar mostrarlo todo o no mostrar nada, y ninguna de las dos cosas es lo que alguien entendería por pausarla. Cambie su condición o cambie la concesión.

Las directivas viajan con la solución

Una directiva pertenece a una solución, igual que una tabla o un formulario, y viaja con esa solución cuando la exporta y llega cuando la importa en otro sitio.

Ese es el sentido de escribir una. «Una factura por encima de mi límite de aprobación no me corresponde aprobarla» forma parte de cómo funciona la aplicación, no es un ajuste que alguien configura en cada entorno; distribuir la aplicación sin ella dejaría que Prueba y Producción permitieran en silencio lo que Desarrollo rechazaba, que es la peor dirección posible en la que puede fallar una regla de seguridad.

De ello se derivan tres cosas:

• La regla se vuelve a comprobar al importar, exactamente igual que cuando la escribió. Un paquete que lleva una directiva que ya no compila se rechaza en la importación, en lugar de descubrirse con la primera persona a la que deniega por error.
• Una directiva distribuida desactivada llega desactivada. Desmarque En vigor en una regla preparada antes de una puesta en marcha y el entorno de destino la recibirá en ese estado; la importación no activará una regla que nadie ha pedido todavía.
• Desinstalar la solución quita la directiva, y también las concesiones hechas con ella, que es la única vez que desaparecen sin que se pregunte. De lo contrario, una concesión cuya directiva ya no existe empezaría a denegar todo lo que antes permitía, sin nada en pantalla que explicara por qué.

A quién se le concede algo con la directiva no viaja: eso nombra a sus personas, y se queda en el entorno donde lo decidió.

Solución de problemas

• «La regla de la directiva no se puede analizar». — una errata en la regla. El mensaje indica el lugar.
• «… es una de las directivas propias de la plataforma». — ha usado un nombre integrado. Las directivas propias llevan el prefijo de su editor.
• «… sigue filtrando permisos que tienen N rol(es)». — cambie antes esas concesiones en la pantalla Roles de la solución. Eliminar ahora la directiva denegaría todas ellas.
• Nadie puede guardar nada en la tabla. — revise la comparación de la regla. Una regla que lee un campo que no existe obtiene un valor vacío, y "" > 100 no es la comparación que pretendía. Desmarque En vigor mientras lo resuelve.
• La regla parece no ejecutarse nunca. — revise las operaciones que marcó y que la concesión del rol apunte de verdad a su directiva y no a una integrada.
• Se rechaza a un usuario con un mensaje sobre una directiva que no se pudo evaluar. — la regla no se pudo ejecutar. La operación se rechaza en lugar de permitirse, porque una regla que no se pudo ejecutar no ha dicho que el registro sea aceptable. Corrija la regla o desmarque En vigor.
• «Esta condición no se puede convertir en una consulta». — una condición de Qué registros que usa algo que una consulta no puede expresar. El mensaje indica la línea y qué usar en su lugar; la tabla anterior las enumera todas.
• Mi directiva Qué registros no se ofrece en la fila que quiero. — está escrita sobre una tabla, así que solo se ofrece en la fila de esa tabla, y nunca en Todas las tablas. Escriba una directiva aparte para la otra tabla.
• Una directiva Qué registros no muestra nada a nadie. — una condición que se resuelve en nada no selecciona nada, que es la dirección segura que la plataforma toma siempre. Compruebe los nombres de los campos y, si comparó con un conjunto como CurrentUser.Teams, que la persona esté de verdad en alguno.

Escenarios relacionados

• Decidir de quién son los registros que ve un visitante
• Conceder a un rol acceso a registros.
• Cambiar el propietario de un registro.