Directus Automatización: guía para desarrolladores sobre los Flujos en producción

Directus Flujos son el motor de automatización integrado de la plataforma para reaccionar ante eventos, recibir webhooks, ejecutar tareas programadas y coordinar flujos de trabajo de corta duración. Son adecuados para operaciones de contenido, aprobaciones, notificaciones, integraciones salientes, enriquecimiento ligero y acciones administrativas controladas.

No son un sustituto de propósito general para los servicios de aplicación, las colas duraderas ni los motores de flujos de trabajo de larga duración. La decisión importante en producción no es si un Flujo puede realizar una tarea. Es si el tiempo de ejecución, el comportamiento ante fallos, el límite de seguridad, la gestión del estado y la responsabilidad operativa de la tarea son aspectos que un Flujo puede admitir de forma segura.

Esta guía explica cómo diseñar una Directus automatización que funcione fuera de una demostración: cómo elegir desencadenadores, gestionar permisos, proteger webhooks, evitar efectos secundarios duplicados, supervisar ejecuciones y reconocer cuándo una extensión personalizada o un trabajador externo son una mejor opción arquitectónica.

Directus Flujos en producción: de un vistazo

Caso de uso	Opción más adecuada	Motivo
Notificar a un equipo cuando el contenido esté listo para revisión	Directus Flujo	De corta duración, basado en eventos y visible para personas que no son desarrolladoras
Activar la reconstrucción de un sitio web después de publicar	Flujo + webhook saliente protegido	Una integración asíncrona sencilla con criterios de éxito claros
Validar o transformar un elemento antes de guardarlo	Flujo con filtro o extensión personalizada	Usa un filtro solo cuando el trabajo sea rápido y deba afectar a la transacción
Procesar archivos grandes o decenas de miles de registros	Trabajador de colas o servicio dedicado	Requiere concurrencia controlada, reintentos duraderos y aislamiento de recursos
Esperar días a una aprobación externa o a la intervención de una persona	Flujo de trabajo de la aplicación u orquestador externo	El estado de larga duración no debe depender de una sola ejecución de Flujo
Reutilizar lógica específica del dominio en varios proyectos	Extensión de operación personalizada o servicio	Permite realizar pruebas, versionar, reutilizar y definir responsabilidades con mayor claridad

Para qué sirven los Directus Flujos

Un Flujo combina un desencadenador con una secuencia de operaciones. El desencadenador crea un contexto de ejecución y cada operación puede leer datos de la cadena de datos o añadirle datos a medida que avanza la automatización. Directus admite hooks de eventos, webhooks, programaciones, desencadenadores manuales y desencadenadores de Flujo a Flujo.

Este modelo resulta útil porque mantiene la automatización empresarial habitual cerca del contenido y del modelo de datos. Un equipo editorial puede usar un desencadenador manual para aprobar y publicar contenido. Una actualización de registro puede notificar a un equipo de distribución. Un Flujo programado puede identificar registros obsoletos para su revisión. Una solicitud saliente puede informar a una plataforma frontend de que el contenido publicado ha cambiado.

Para los equipos que usan Directus como backend componible, los Flujos son un componente de una arquitectura más amplia de CMS y plataforma de contenido. La base de datos, los contratos de la API, el modelo de roles, los flujos de trabajo editoriales, el proceso de entrega del frontend y los límites de integración siguen teniendo que diseñarse como un único sistema.

Elige el desencadenador según el riesgo de la transacción

El desencadenador determina cuándo se ejecuta un Flujo, pero también determina cómo afectan los fallos a los usuarios y a los sistemas conectados. Elígelo según lo que deba ocurrir antes de que pueda completarse una transacción, lo que pueda ocurrir después y quién o qué sea responsable de iniciar el trabajo.

Hooks de eventos: usa los filtros con moderación

Los hooks de eventos reaccionan a actividades como la creación, actualización o eliminación de elementos. Directus distingue entre filtros y hooks de acciones:

• Los filtros se ejecutan antes de que se complete la transacción de la base de datos. Pueden modificar un payload o impedir que una acción continúe.
• Las acciones se ejecutan después de que se completa la transacción. Son más adecuadas para notificaciones, integraciones posteriores y trabajos que no deberían bloquear a un editor o cliente de API.

Un filtro es apropiado para una validación rápida y determinista: por ejemplo, impedir que se publique un artículo sin un estado de revisión obligatorio. Es un mal lugar para realizar llamadas lentas a API externas, procesar documentos o ejecutar cualquier tarea que pueda fallar porque otro proveedor está teniendo un mal día.

Si un flujo de trabajo no necesita bloquear el guardado del usuario, es preferible usar una acción. Esto mantiene los fallos operativos separados de la transacción original de contenido o datos y facilita la recuperación.

Webhooks: trata a cada remitente como no confiable

Los flujos activados por webhooks son útiles cuando otro sistema necesita iniciar un trabajo en Directus: una plataforma de comercio recibe la confirmación de un pago, una herramienta de formularios envía un lead o una plataforma de despliegue informa del estado de una compilación. También son un punto de entrada expuesto.

No dependas de una URL poco conocida como mecanismo de control. Exige un mecanismo de autenticación, valida la solicitud entrante antes de realizar efectos secundarios y mantén las credenciales fuera de los registros y las notificaciones de los flujos. Según el sistema que realice la llamada, esto puede significar un encabezado con un secreto compartido, la verificación de una firma, restricciones de IP en la capa de red o una puerta de enlace que autentique la solicitud antes de que llegue a Directus.

Para una integración que escribe en varios sistemas empresariales, separa el webhook entrante del paso de procesamiento duradero. El webhook debería confirmar la recepción rápidamente; un trabajador o servicio de integración puede realizar el trabajo costoso e informar del estado de forma asíncrona. Este es el mismo principio en el que se basa una arquitectura de integración de CRM: el sistema que recibe un evento no debería acoplarse estrechamente a cada dependencia posterior.

Programaciones y activadores manuales

Las programaciones funcionan bien para tareas recurrentes y acotadas: un recordatorio nocturno, una comprobación de calidad semanal o tareas de limpieza con una política de retención clara. No son una razón para crear un bucle de sondeo mal controlado contra otro sistema.

Los activadores manuales son útiles cuando un editor o administrador necesita realizar una acción explícita, como «enviar para aprobación», «regenerar vista previa» o «volver a sincronizar este registro». Asigna al activador una etiqueta específica, explica su efecto en la interfaz y haz que la acción se pueda repetir de forma segura siempre que sea posible. Los buenos flujos de administración forman parte de un diseño de UX y accesibilidad, no son solo infraestructura del backend.

Usa deliberadamente la cadena de datos

Cada operación de un flujo de Directus puede acceder a valores contextuales como $trigger, $accountability, $env, y $last. Esto resulta práctico, pero también es el punto en el que flujos que de otro modo serían sencillos se vuelven difíciles de depurar.

$last contiene el resultado de la operación inmediatamente anterior. No es un almacén de variables persistente. Si varios pasos posteriores necesitan un valor, guárdalo con una clave con nombre o dale forma de payload explícito antes de ramificar. Un flujo debería hacer que sus entradas y salidas sean comprensibles para alguien que no lo haya creado.

Mantén los payloads pequeños. No pases un registro completo, un objeto de usuario entero o un grafo relacional grande a cada webhook simplemente porque esté disponible. Envía el identificador y los campos que realmente necesita el servicio posterior, y deja que ese servicio recupere más datos mediante una API autenticada si corresponde. Esto reduce la exposición accidental de datos y hace que las integraciones sean menos frágiles cuando cambia la colección.

Operaciones, scripts y extensiones personalizadas

Las operaciones integradas cubren necesidades habituales: acciones CRUD, condiciones, transformaciones de payloads, notificaciones, solicitudes salientes, scripts y la invocación de otro flujo. La operación Ejecutar script en el entorno aislado es útil para transformaciones de datos acotadas y lógica de decisiones, pero intencionadamente no es un entorno de ejecución completo para aplicaciones.

Si el trabajo necesita dependencias de paquetes, conexiones persistentes, un tiempo de ejecución prolongado, pruebas complejas o lógica de dominio reutilizable, crea una extensión de operación personalizada o traslada el trabajo a un servicio dedicado. Aquí es donde una pequeña dosis de disciplina de ingeniería evita una gran proliferación de flujos más adelante.

Una capa de desarrollo de software personalizado bien diseñada puede proporcionar procesamiento duradero de colas, adaptadores de integración, transformación de documentos, validación del dominio y un límite de API versionado, al tiempo que permite que los Flows de Directus sigan siendo la capa visible de orquestación.

Haz que cada Flow sea seguro para reintentar

La automatización en producción falla de formas habituales: un endpoint agota el tiempo de espera, un webhook de despliegue devuelve un 500, un usuario hace clic dos veces, dos actualizaciones llegan con poca diferencia o un trabajador se reinicia a mitad del procesamiento. La fiabilidad surge de decidir qué ocurrirá después antes de que se produzca el fallo.

Idempotencia: evita efectos secundarios duplicados

Una operación es idempotente cuando repetirla produce el mismo resultado previsto en lugar de crear otro efecto secundario. Esto es importante para cualquier Flow que envíe un correo electrónico, inicie una compilación, cree un registro en otro sistema, publique un mensaje o cambie un estado relacionado con el dinero.

Usa identificadores estables del registro de origen siempre que sea posible. Por ejemplo, un sistema externo podría almacenar el ID del elemento Directus y el tipo de operación como clave de idempotencia, rechazando una solicitud duplicada en lugar de crear un segundo recurso. Para las reconstrucciones de contenido, utiliza una estrategia de despliegue con espera de estabilización en lugar de iniciar una nueva compilación por cada pequeña edición.

Hazte esta pregunta antes de publicar un Flow: ¿qué ocurre si se ejecuta dos veces en el mismo segundo? Si la respuesta es “depende”, el Flow necesita otra revisión de diseño.

Evita los desencadenadores recursivos

Un Flow activado por items.update puede actualizar fácilmente el mismo elemento y activarse de nuevo. No dependas de la buena suerte para evitar ese bucle.

• Usa condiciones para comprobar si el campo relevante ha cambiado realmente.
• Utiliza un campo de estado u origen específico cuando un Flow deba marcar un elemento que ha procesado.
• Limita un desencadenador de actualización a la colección y los campos relevantes.
• Mantén separados, siempre que sea práctico, los campos de enriquecimiento de los campos que inician el flujo de trabajo.

Un campo como automation_processed_at puede ser útil cuando registra un resultado empresarial significativo. No añadas indicadores únicamente para parchear un diseño de desencadenador poco claro; eso suele crear estados en los que nadie confía seis meses después.

Asigna un responsable a los fallos

Cada solicitud saliente y cada rama importante necesitan un resultado de fallo explícito. Solo hay unas pocas opciones legítimas:

• Reintentar automáticamente cuando el error sea transitorio y la operación se pueda repetir de forma segura.
• Derivar a una persona cuando el resultado requiera criterio o afecte a un proceso de cara al cliente.
• Registrar y continuar cuando la operación no sea crítica y la empresa acepte una finalización retrasada o ausente.
• Fallar de forma visible cuando continuar dejaría el sistema en un estado inseguro o engañoso.

“El registro del Flow contiene el error” no es una estrategia de recuperación. Define quién recibe una alerta, qué información necesita para investigar, cómo repite o corrige el trabajo y si una acción fallida debe conciliarse con el sistema de origen.

Usa el límite de permisos más pequeño que funcione

Un Flow puede ejecutarse en el contexto del usuario que lo activa o en un contexto de responsabilidad configurado. Esa decisión forma parte de tu modelo de autorización.

Para las acciones editoriales, heredar el contexto del usuario que las activa puede ser útil: el Flow respeta los permisos de la persona que lo inició y crea un registro de auditoría comprensible. Para webhooks externos o tareas operativas programadas, utiliza una cuenta de servicio específica con los privilegios mínimos necesarios. No ejecutes todas las integraciones con una cuenta de administrador con permisos amplios solo por comodidad.

Revisa estos controles para cada Flow de producción:

• ¿Qué rol o cuenta de servicio realiza cada operación?
• ¿Esa identidad solo puede leer o escribir en las colecciones y los campos que necesita?
• ¿Las claves de API, los secretos compartidos y los hooks de despliegue se almacenan en variables de entorno o en un sistema de secretos gestionado?
• ¿Los registros de Flow pueden exponer datos personales, tokens de acceso o información confidencial de clientes?
• ¿Se autentica al emisor del webhook antes de crear un registro o iniciar una acción externa?

Para las organizaciones que conectan Directus con servicios de IA, procesadores de documentos o sistemas de conocimiento, mantén el límite de permisos igualmente explícito. Un asistente de contenido solo debe recibir el material necesario para su tarea y no debe recibir acceso administrativo sin restricciones simplemente para resumir o clasificar contenido. Nuestro desarrollo y automatización de IA siguen el mismo principio: una automatización útil necesita un límite de datos estrecho y auditable.

Trata los registros como un producto operativo

Los registros de ejecución de Flow son valiosos para la depuración porque muestran los datos del activador, los resultados de las operaciones y los errores. También son datos almacenados en tu base de datos y pueden incluir información que no querrías conservar indefinidamente.

Establece una política de retención antes de que el volumen de ejecuciones tome la decisión por ti. El periodo de retención adecuado depende de las necesidades de resolución de problemas, el presupuesto de almacenamiento, la sensibilidad de los datos y cualquier requisito empresarial o normativo aplicable. Prueba la limpieza con cuidado: debes eliminar los registros de ejecuciones antiguos sin borrar la información necesaria para un incidente activo.

La observabilidad en producción debe ir más allá de «¿se ejecutó el Flow?». Haz un seguimiento del estado empresarial relevante:

• ¿Cuántos registros entraron en el flujo de trabajo?
• ¿Cuántos se completaron correctamente?
• ¿Cuántos requieren revisión humana o corrección manual?
• ¿Cuánto tardan las automatizaciones importantes desde el activador hasta el resultado?
• ¿Qué dependencia externa provoca más ejecuciones fallidas o retrasadas?

En las plataformas de contenido, esto puede significar supervisar el número de eventos de publicación que activan correctamente una reconstrucción del frontend. En un flujo de comercio, puede significar comparar los pedidos recibidos con los pedidos enviados correctamente al ERP. El patrón es el mismo que en la automatización de pedidos de venta: el éxito técnico no es suficiente si el resultado empresarial previsto nunca se produce.

Promueve los Flows como código de aplicación

Los Flows suelen contener lógica empresarial real: decisiones de enrutamiento, integraciones, reglas de publicación y operaciones sensibles a los permisos. Tratarlos como configuración de producción sin seguimiento es un riesgo evitable.

Como mínimo, establece un proceso repetible para:

1. Diseño. Registra el activador, los permisos, la carga útil de entrada, las salidas previstas, el comportamiento ante fallos, el responsable y el enfoque de reversión.
2. Pruebas. Utiliza un proyecto de staging con datos representativos y escenarios de fallo reales, no solo el recorrido ideal.
3. Revisión. Haz que alguien distinto del autor inspeccione los permisos, el riesgo de recursión, la exposición de la carga útil y los efectos secundarios externos.
4. Promoción. Mueve la configuración del Flow entre entornos mediante un proceso de despliegue deliberado, en lugar de reconstruirla manualmente en producción.
5. Operación. Mantén un manual operativo para las alertas, el reprocesamiento, los modos de fallo conocidos y los cambios de responsables.

Esta disciplina resulta especialmente importante cuando un proyecto de Directus es una pieza de una arquitectura componible. Un frontend, un almacén de datos, un índice de búsqueda, un CRM y un portal de clientes pueden depender de que el modelo de contenido y el comportamiento de los eventos se mantengan estables. Si el alcance se amplía más allá de unos pocos Flows sencillos, los servicios de consultoría y soporte de entrega de software pueden ayudar a establecer la arquitectura y el modelo operativo antes de que la plataforma resulte difícil de modificar.

Cuándo utilizar un trabajador de colas o un servicio externo

Traslada el trabajo fuera de un Flow cuando sus requisitos de fiabilidad superen los de una tarea de orquestación de corta duración. Por lo general, un trabajador o servicio específico encaja mejor cuando necesitas:

• Procesamiento de larga duración o con uso intensivo de la CPU
• Colas persistentes y concurrencia controlada
• Importaciones, exportaciones o procesamiento de archivos por lotes de gran tamaño
• Políticas de reintento complejas, limitación de velocidad y gestión de colas de mensajes no entregables
• Estado de flujo de trabajo de larga duración, como esperar varios días la aprobación
• Pruebas automatizadas exhaustivas y control de versiones de las publicaciones
• Lógica de dominio reutilizable compartida por varias aplicaciones

La respuesta adecuada suele ser híbrida: Directus gestiona los desencadenadores editoriales y de cambios de datos, un servicio respaldado por una cola realiza el trabajo pesado o poco fiable, y Directus recibe una actualización de estado cuando el trabajo finaliza. Así, el flujo de trabajo sigue siendo visible para los equipos de contenido y operaciones sin pretender que el CMS deba ser una plataforma de procesamiento de trabajos.

Por eso, el debate entre «sin código y personalizado» suele ser equivocado. La pregunta práctica es dónde debe residir cada responsabilidad. Nuestra guía sobre herramientas de automatización de flujos de trabajo empresariales aborda el equilibrio más amplio entre la automatización empaquetada, las plataformas de integración y los sistemas a medida.

Directus Lista de comprobación de producción de Flows

• Desencadenador: ¿El tipo de desencadenador es adecuado y evita bloquear innecesariamente una transacción del usuario?
• Permisos: ¿El Flow utiliza, cuando es necesario, una identidad específica con los privilegios mínimos?
• Seguridad: ¿Los webhooks están autenticados y los secretos se almacenan fuera de la definición del Flow?
• Carga útil: ¿Cada sistema externo recibe únicamente los campos que necesita?
• Idempotencia: ¿Las operaciones importantes pueden ejecutarse dos veces sin efectos secundarios duplicados?
• Recursión: ¿La actualización de un elemento puede volver a activar su propio Flow y, en caso afirmativo, cómo se evita?
• Comportamiento ante fallos: ¿Están definidos explícitamente los reintentos, las alertas, la revisión manual y las decisiones de conciliación?
• Observabilidad: ¿El equipo puede ver tanto los fallos técnicos como los resultados empresariales?
• Retención: ¿Existe una política probada para los registros de ejecución y los datos confidenciales de las cargas útiles?
• Responsabilidad: ¿Un manual de operaciones identifica quién responde cuando falla la automatización?

Directus Automatización que no se convierte en un sistema misterioso

Directus Los Flows son potentes porque permiten a los equipos automatizar el trabajo cerca del contenido y del modelo de datos. Esa misma comodidad se convierte en un inconveniente si la lógica crítica se acumula sin permisos, pruebas, documentación ni una responsabilidad operativa claros.

Ridiculous Engineering ayuda a los equipos a diseñar y crear plataformas basadas en Directus que sean prácticas de operar: modelos de contenido, flujos de trabajo, integraciones, extensiones personalizadas, entrega frontend y las prácticas de ingeniería de apoyo que hacen que el sistema sea fiable después del lanzamiento. Podemos ayudarle tanto si implementa Directus por primera vez como si está desenredando una colección existente de Flows o decidiendo dónde establecer el límite entre la automatización nativa y los servicios personalizados.

Preguntas frecuentes

¿Para qué se utiliza Directus ?

Directus es una plataforma de datos y contenidos que proporciona API y una interfaz administrativa sobre una base de datos. Los equipos la utilizan como CMS sin interfaz, backend para operaciones internas, plataforma de contenidos y capa de integración. Los Flows de Directus añaden automatización basada en eventos para flujos de trabajo, notificaciones, programaciones y sistemas conectados.

¿Cuándo debo utilizar un Flow de Directus ?

Utiliza un Flow de Directus para tareas breves basadas en eventos cerca de tu modelo de datos de Directus : aprobaciones de contenido, notificaciones, webhooks sencillos, limpieza programada, acciones administrativas manuales y enriquecimiento ligero de registros. Utiliza un servicio dedicado o un trabajador de cola para tareas de larga duración, con un uso intensivo de cómputo, de gran volumen o con estado persistente.

¿Cómo evito los activadores recursivos en los Flows de Directus ?

Limita los activadores de actualización a la colección y los campos relevantes, añade condiciones que confirmen que el campo correspondiente realmente ha cambiado y evita actualizar el mismo elemento desde un Flow, a menos que dicha actualización esté protegida deliberadamente. Un campo significativo de estado de procesamiento puede ser útil cuando el flujo de trabajo necesita registrar su resultado.

¿Es seguro conservar indefinidamente los registros de los Flows de Directus ?

No. Los registros de los Flows consumen almacenamiento de la base de datos y pueden contener información sobre activadores o cargas útiles que no debería conservarse para siempre. Define una política de conservación basada en las necesidades operativas, la sensibilidad de los datos y los requisitos de cumplimiento; después, prueba el proceso de limpieza.

¿Pueden los Flows de Directus llamar a API externas?

Sí. Las operaciones de solicitudes salientes o webhooks pueden llamar a API externas. Establece tiempos de espera, autentica las solicitudes, gestiona explícitamente las respuestas no satisfactorias, minimiza la carga útil y diseña la operación para tolerar reintentos sin crear efectos secundarios duplicados.

Fuentes

• Documentación de Directus : Flows
• Documentación de Directus : Operaciones
• Documentación de Directus : Opciones de configuración

Recomendado

• Desarrollo de CMS y plataformas de contenidos
• Desarrollo de software personalizado
• Herramientas de automatización de flujos de trabajo empresariales
• Integración con Salesforce: guía de patrones, API y arquitectura