Cleaners

Un Cleaner es un conjunto de reglas que se aplica a filas de datos: las filas que un Flow extrajo o una hoja de cálculo que subes. Estandariza formatos, convierte monedas y unidades, traduce texto, calcula columnas nuevas, busca valores en tus propios datos, marca valores atípicos, recoge valores de un revisor y puede disparar acciones cuando una fila rompe una regla.

La extracción responde “¿qué dice este documento?”. Un Cleaner responde “¿qué forma debe tener esto antes de entrar a nuestros sistemas?”: un solo formato de fecha, una sola moneda, números de parte vinculados a tu catálogo, un total que cuadra.

Cada ejecución de un Cleaner sobre un lote de filas se llama limpieza (en inglés, sweep).

Haz clic en Crear Cleaner en la página de Cleaners. Tavnit primero pregunta “¿De dónde vienen los datos?” y ofrece cuatro puntos de partida.

Con Desde un flow y Desde un archivo, el siguiente paso también ofrece Sugerir reglas de limpieza con IA. Si lo dejas apagado, el Cleaner se crea solo con los campos base. Si lo activas, puedes describir qué quieres limpiar o calcular (por ejemplo “Normaliza los nombres de proveedores y deja el RUC sin guiones”) y luego hacer clic en Sugerir reglas.

Desde cero abre el constructor, donde le pones nombre al Cleaner y recorres las mismas secciones que tiene la página de detalle:

1. 1Campos Base. Elige una Fuente de Datos: Manual para definir las columnas desde cero, Desde Flow para importar los campos de salida de un Flow, o Desde Archivo para leer la fila de encabezados de un CSV o Excel. Se necesita al menos un campo.
2. 2Campos calculados. Agrega cualquiera de los tipos de campo de la referencia de abajo. Es opcional: un Cleaner con solo campos base es un paso directo válido.
3. 3Salidas. Una dirección de correo y una URL de webhook para las limpiezas que el Cleaner ejecuta por su cuenta. Opcional.
4. 4Omitir Filas. Descarta las primeras N filas o las filas vacías de las cargas. Opcional.

Para que cada Run de un Flow se limpie automáticamente, vincula el Cleaner a ese Flow: marca Vincular este Cleaner al Flow cuando construyes desde un Flow, o elige el Cleaner en el ajuste Cleaner del Flow. Un Flow solo puede tener un Cleaner; un Cleaner puede servir a varios Flows, que aparecen en Flows Vinculados en su página de detalle. Crear y editar Cleaners requiere el rol de Admin u Owner.

Cada columna de un Cleaner tiene un tipo que decide qué hace. La página de detalle los agrupa en su panel izquierdo bajo Entrada y Calculados, con un conteo para cada uno. Este es el conjunto completo, en el orden en que la app los muestra.

Cualquier campo se puede marcar como Excluir de la salida: sigue disponible para las columnas calculadas, pero no aparece en lo que entrega el Cleaner. Así usas un valor intermedio (un monto sin procesar, una clave de búsqueda) sin enviarlo más adelante.

Los tipos de formato y conversión tienen cada uno un pequeño conjunto de ajustes. Estos son los que cambian el resultado.

Un campo de Acciones Condicionales es una regla: cuando una fila cumple estas condiciones, haz estas cosas. Es el único tipo de campo que cambia lo que pasa con los datos en lugar de lo que contiene una celda, y es la forma de que una falla de validación se convierta en algo más que un número en una tabla.

Las condiciones se agrupan, y los grupos se combinan con AND u OR, así que puedes expresar cosas como (total > 10,000 O la moneda no es USD) Y el proveedor no está en la lista aprobada. Las condiciones también pueden leer columnas calculadas, incluidos los campos de Resumen y de Anomalías. Una regla sin ninguna condición se dispara en todas las filas.

Ejemplo práctico. En un Cleaner de facturas, agrega un campo de Acciones Condicionales con dos reglas. La primera detecta las filas donde el total de la línea no es igual a cantidad × precio unitario y envía el Run a Human in the Loop. La segunda detecta cualquier factura por encima de tu umbral de aprobación y le envía un correo al responsable de finanzas. Todo lo demás pasa directo al Bucket sin que nadie lo toque.

Un campo Calculado evalúa una expresión aritmética sobre la fila en la que está. Referencia otras columnas por nombre entre llaves y, si quieres, empieza la fórmula con un signo igual: tanto ={Quantity} * {Unit Price} como {Quantity} * {Unit Price} funcionan.

Los campos de Resumen agregan sobre todas las filas de la limpieza en lugar de calcular por fila, y escriben el resultado en cada fila. Responden “¿cuál es el total de este documento?” sin que tengas que sumar las filas más adelante.

• Incluir solo las filas que coinciden: grupos de condiciones opcionales, para sumar solo las filas de una categoría o un estado.
• Formato del resultado: decimales y separadores opcionales, como en los campos Calculados. El valor sigue siendo numérico.
• Celdas con varios valores: cuando una columna tiene varios valores por fila (un campo de varios valores de un Flow, como cada línea de descuento de un recibo de sueldo), cada valor cuenta. Sum los suma todos, Count cuenta cada uno y Average divide entre la cantidad de valores.
• Los resultados de Resumen se pueden usar en fórmulas y en las condiciones de Acciones Condicionales.

Un campo de Entrada Humana es una columna que nadie extrae: un revisor escribe o elige su valor en la pantalla de revisión. Úsalo para información que no está en el documento, como el almacén al que va una entrega o un código de aprobación.

• Tipo de entrada: Free text (texto libre) o Menu. Un menú toma sus opciones de los valores distintos de una columna de un Bucket, opcionalmente filtrados por condiciones sobre otras columnas del Bucket o sobre los valores de la fila actual.
• Value is mandatory (valor obligatorio): si está activo, la aprobación se bloquea hasta que todas las filas tengan un valor. Desactívalo para permitir valores vacíos.
• Revisores: elige al menos uno. Se suman a los revisores del Run.

Un campo de Anomalías (Detección de Anomalías) marca las filas cuyo valor en una columna se aleja del resto de la limpieza: una cantidad muy distinta a las demás, o un código de una categoría que casi nadie más usa. Devuelve true cuando el valor se aleja del resto y false en otro caso. Es determinista y no usa IA.

Un campo de Anomalías solo produce una marca. Para actuar sobre ella, agrega una regla de Acciones Condicionales como este campo es igual a true → Human in the Loop. Luego la pantalla de revisión muestra el motivo de cada valor marcado.

Un Cálculo de Fechas hace aritmética de fechas en cada fila, de forma determinista y sin IA. Tiene dos modos.

• Unidades para una diferencia: Días, Semanas (solo semanas completas), Meses (completos), como una edad, Meses calendario (cambios de mes, sin importar el día) y Años (completos).
• Hoy es la fecha de tu organización cuando se procesan los datos.
• Una fecha vacía da una celda vacía. Combina el resultado con un campo Condicional (por ejemplo dias_para_vencer >= 30 → sí, si no → no) para marcar filas.

El campo Código Arancelario asigna un código arancelario de aduana a cada fila a partir de la descripción del producto. Recorre el arancel de Panamá (SA 2022): sección, luego capítulo, luego partida y luego la línea arancelaria nacional, en lugar de buscar coincidencias entre la descripción y una lista de códigos.

• Benchmark Fields (campos de referencia): las columnas que lee el clasificador, normalmente la descripción del producto, a veces junto con el material o el uso. Si no eliges ninguna, se usa la fila completa.
• Instrucciones para la IA: los casos que tu catálogo clasifica mal, como qué hacer con kits, repuestos o mercancías que podrían ir en dos capítulos.
• Section preselect (recomendado): empieza la clasificación por las 22 secciones del SA antes de los capítulos.
• Output Format: solo el código (por ejemplo 0101.29.00.00.00) o el código con su descripción.
• Cada fila se clasifica de forma independiente, así que una fila difícil no afecta a las demás.

Después de las columnas calculadas, un Cleaner puede descartar filas basura, elegir y ordenar las columnas que entrega, pasar datos largos a formato ancho y enviar el resultado a una dirección de correo o a un webhook.

Pivot es el formato de entrega, no solo una vista. Elige la Columna a explotar, la columna de Valores desde, cómo Agrupar filas por (todas las demás columnas automáticamente, o las columnas que elijas) y qué hacer cuando una etiqueta se repite dentro de un grupo: sumar los valores, mantener el primer valor, o mantener el primer valor y marcar una advertencia. Las Columnas de resumen opcionales (Suma, Promedio, Mínimo, Máximo o Conteo) se calculan por fila sobre las columnas expandidas y aparecen en el extremo derecho. En Aplicar a, elige el payload del webhook, la salida por email y las descargas; con las descargas activadas, la página de la limpieza abre en la vista pivotada.

Una limpieza es una ejecución de un Cleaner sobre un lote de filas.

Abre cualquier limpieza desde el Historial de Limpiezas del Cleaner para ver exactamente qué hizo. La página se actualiza en vivo mientras la limpieza se procesa.

• Estado (Procesando, Completado, Fallido o Cancelado) con las Filas y el Origen de la limpieza.
• Advertencias: problemas por fila, como una fórmula que dividió entre cero o un valor que no se pudo leer como número. Cada problema queda ligado a la fila que lo causó, así una fila mala no hace fallar la limpieza.
• Información de la Limpieza: el Cleaner, cuándo se creó la limpieza, y el Run de Origen y el Flow cuando vino de un Flow.
• La tabla de datos, con un selector Limpiados / Pivotado / Sin Procesar para comparar la salida con lo que entró, y Expandir para verla a pantalla completa. Puedes seleccionar y copiar celdas.
• Exportación a CSV y JSON de la vista actual. Con un pivot aplicado a las descargas, la exportación tiene la forma pivotada.
• Salidas: un registro de cada entrega (correo, webhook, notificaciones) y si tuvo éxito.
• Cambios en Buckets: cada celda de Bucket que cambiaron las acciones Edit Bucket Row de la limpieza.

Un Cleaner puede ejecutarse por su cuenta desde tus sistemas, sin ningún Flow de por medio. Copia su ID en el panel ID del Cleaner y autentícate con tu clave de API.

Ambos devuelven HTTP 202 con un sweep_id. Cuando la limpieza termina, la Salida por Email y el Webhook del propio Cleaner entregan las filas limpias. Consulta la página de la API para la autenticación y la forma de la respuesta.

La limpieza ocurre después de la extracción y antes de la entrega. Ese orden importa: todo lo que viene después (la pantalla de revisión, el payload del webhook, las filas del Bucket, las variables de entrada de un Agente) ve la salida limpia, no la extracción sin procesar.

1. 1El Flow extrae las filas del documento.
2. 2El Cleaner vinculado limpia esas filas: formatos, conversiones, búsquedas, columnas calculadas.
3. 3Se disparan las Acciones Condicionales: se descartan filas, salen notificaciones y puede pedirse una revisión. Un campo de Entrada Humana siempre pide revisión.
4. 4Si se activó la revisión, el Run se pausa y un revisor ve la tabla limpia.
5. 5Al terminar, los resultados se entregan por las salidas del Flow: correo, webhook, Bucket, llenado de formulario o un Agente encadenado.

El Mapa de Pipeline muestra esto para tu propio espacio de trabajo, incluidos los Flows que comparten un Cleaner.