Expresiones, parámetros y variables

Tres mecanismos distintos

Dova separa las plantillas de campos de Mapping, los parámetros tipados de ejecución y las condiciones JSON de Workflow. Cada mecanismo tiene sintaxis y alcance propios. Una plantilla ${field} no es una condición de decisión; un valor booleano JSON no es la cadena "true"; un parámetro secreto es una referencia protegida, no una contraseña para interpolar en un archivo.

Use parámetros para representar variaciones de entorno y de tarea que no cambian la estructura del proceso. Use variables de Workflow cuando la definición de orquestación las contemple. Use condiciones para seleccionar ramas a partir de valores o estados disponibles. La guía de Sessions describe dónde se editan estos valores, y Workflows explica su relación con las tareas.

Definición de parámetros

Cada definición admite name, type, description, required, sensitive, overridable, scopes, default, enum, minimum, maximum y maxLength. El contrato admite hasta 100 definiciones, con nombres únicos. Un nombre comienza por letra, tiene hasta 64 caracteres y puede incluir letras, números, guion bajo, punto y guion. Los prefijos sys. y dova. están reservados.

Description está limitada a 300 caracteres. Max length admite valores entre 1 y 32768. Minimum no puede superar Maximum. Enum debe contener entre 1 y 50 candidatos, se normaliza según el tipo y no está disponible para JSON o Secret. Un parámetro marcado Sensitive debe usar el tipo Secret: no se convierte una cadena ordinaria en un secreto seguro mediante una etiqueta.

Las referencias Secret reconocen los esquemas gcp-secret, aws-secretsmanager, azure-keyvault, vault y worker-secret. Esta sintaxis pertenece a parámetros de orquestación; no debe mezclarse mecánicamente con las formas específicas que usa Customer vault en Connections. Resolver una referencia requiere la infraestructura y autorización correspondientes.

Capas y precedencia

Una capa posterior reemplaza el valor anterior dentro de las reglas de validación. Scopes limita las capas aceptadas y Overridable participa en el control de sustitución. Required exige que exista un valor después de resolver defaults y capas. El resultado conserva la procedencia del valor, lo que permite diagnosticar por qué no se aplicó el valor que esperaba el diseñador.

Por ejemplo, defina REGION como String con default NORTE. Una capa Environment que establezca SUR debe prevalecer sobre ese default; una capa Task permitida que establezca CENTRO debe prevalecer sobre ambas. No elimine restricciones de scope para resolver un error sin comprobar quién tiene autoridad sobre esa configuración.

Plantillas de Calculated field

La plantilla reconoce ${nombre} para campos del registro y ${param.nombre} para parámetros. La sustitución produce texto y limita el resultado a 4000 caracteres. Un identificador reconocido pero ausente se sustituye por cadena vacía. El nombre de campo se busca como clave del registro; escribir un punto no garantiza navegación por un objeto anidado.

Con una fila que contiene name = Ana y un parámetro region = SUR, la plantilla Cliente ${name} / ${param.region} produce Cliente Ana / SUR. La expresión ${amount} * 2 produce una representación textual con * 2; no calcula una multiplicación. Use los componentes de transformación adecuados y no introduzca código esperando evaluación dinámica.

El helper de valor parametrizado reconoce una referencia completa ${param.nombre}. No implica que todos los campos de todos los conectores acepten interpolación parcial. Confirme la configuración del componente concreto antes de trasladar una plantilla de un campo a otro.

Condiciones JSON de Workflow

Una condición simple contiene ref, op y, salvo dos operadores, value. Las referencias admitidas son parameters.nombre, variables.nombre, tasks.identificador.status y tasks.identificador.outputs.nombre. No admiten acceso arbitrario a propiedades del servidor o código ejecutable.

Si una referencia no existe, las comparaciones ordinarias producen falso. Exists permite distinguir ausencia de un valor existente pero vacío. In y Not in requieren que el valor esperado sea una lista. Los números deben seguir siendo números JSON; la comparación no promete conversión automática desde texto.

Los grupos all y any combinan entre 1 y 20 expresiones; not niega una expresión. Se rechazan profundidades superiores a cinco y árboles que superen 40 nodos. El valor de comparación tiene un límite de 4096 bytes. Estos límites favorecen condiciones revisables; divida decisiones demasiado complejas en tareas claras.

{
  "all": [
    {"ref": "parameters.RUN_MODE", "op": "eq", "value": "full"},
    {"ref": "tasks.load.status", "op": "eq", "value": "succeeded"}
  ]
}

La referencia load debe corresponder al identificador real de una tarea. Las salidas sólo pueden consultarse cuando el contexto las contiene. El ejemplo no declara una salida universal de conteos ni presupone nombres de campos de un conector.

Decisiones y estados

Los tipos de tarea son Start, Session, Decision, Timer y End. Los enlaces contemplan Success, Failure, Always y Expression. Una decisión requiere ramas True y False complementarias: una expresión y su negación directa. La interfaz construye la rama falsa como not de la verdadera; no escriba dos condiciones independientes que puedan resultar ambas verdaderas o ambas falsas.

Los estados terminales reconocidos incluyen Succeeded, Failed, Skipped, Cancelled y Terminated. Ready, Queued, Running, Waiting y Retry wait son estados activos. La preparación de una tarea considera sus padres terminales y la política de unión. Always no significa que una tarea pueda ignorar todos los requisitos de la orquestación.

POC y diagnóstico

Prepare un Workflow sintético con una Session que procese dos filas, una Decision y dos ramas de finalización. Defina RUN_MODE como String con valores permitidos full y sample. Use una condición de igualdad sobre parameters.RUN_MODE, ejecute primero con full y después con sample, y compruebe que cambia la rama activa manteniendo la complementaria.

Después pruebe un valor no incluido en Enum y un booleano donde se exige String. El resultado esperado es rechazo de validación, no conversión silenciosa. Estas pruebas deben realizarse en un entorno autorizado y registrar el resultado observado. Si una rama no se activa, revise tipo JSON, nombre técnico, capa efectiva, estado del padre y existencia de la referencia antes de modificar la lógica.