DataStore - Almacenamiento de datos

Que es el DataStore

El DataStore es un sistema de almacenamiento clave-valor con capacidades de agrupación y etiquetado. Permite a los workflows persistir, consultar y gestionar datos estructurados sin necesidad de bases de datos externas.

Los datos se almacenan en la tabla datastores de la base de datos del sistema, proporcionando un mecanismo integrado y accesible desde cualquier nodo del workflow.

---

Conceptos clave

• Grupo (group): Agrupación lógica de registros. Funciona como una “tabla” o “colección” conceptual. Ejemplos: "clientes", "pedidos", "configuracion".
• Clave (key): Identificador único dentro de un grupo. Equivale a una clave primaria dentro de ese grupo.
• Datos (row_data): Objeto JSON con los datos del registro. Puede contener cualquier estructura valida de JSON.
• Tags: Etiquetas para categorizar y filtrar registros. Son cadenas de texto libres separadas por comas.

La combinación de grupo + clave es única. Si se inserta un registro con un grupo y clave que ya existen, se realiza un UPSERT automático (actualización en lugar de error).

---

Operaciones disponibles

La operación a ejecutar se define en el parámetro config.action.

add - Insertar o actualizar un registro

Inserta un nuevo registro o actualiza uno existente si la combinación grupo + clave ya existe.

• Si la clave ya existe en el grupo, actualiza los datos
• Si no existe, inserta un nuevo registro
• Emite el evento insert o update según corresponda (utilizable por DataStore Triggers)

bulk - Inserción/actualización masiva

Permite procesar múltiples registros en una sola operación.

• Recibe un array de registros
• keyField: campo dentro de cada registro que se usa como clave única
• Optimizado para grandes volumenes de datos

filter - Consultar registros

Busca y retorna registros que coincidan con los criterios especificados.

• Filtrar por grupo, clave, tags
• tagMode: define como se aplican los filtros por tags:
  • any (OR entre tags)
  • all (AND entre tags)
  • exclude (excluir tags)
• Retorna un array de registros coincidentes

getField - Obtener un campo especifico

Extrae un solo campo de un registro identificado por grupo + clave.

• Útil cuando solo se necesita un valor puntual de un registro
• Retorna únicamente el valor del campo solicitado

exists / isFoundKey - Verificar existencia

Comprueba si un registro existe en el DataStore.

• Retorna true o false según si el registro existe o no
• Se busca por grupo + clave

delete - Eliminar registros

Elimina registros del DataStore.

• Se puede eliminar por ID directo o por la combinación grupo + clave

modifyTags - Gestionar etiquetas

Permite agregar y/o eliminar tags de registros existentes.

• Se pueden agregar nuevos tags a un registro
• Se pueden eliminar tags existentes de un registro
• Ambas operaciones se pueden realizar en una sola llamada

map - Mapear claves a valores

Dado un array de claves, obtiene el valor de un campo especifico para cada una.

• Útil para resoluciones masivas de datos (por ejemplo, obtener nombres a partir de IDs)
• Soporta transformaciones: uppercase, lowercase, trim

logs - Historial de cambios

Consulta el log de cambios de un registro.

• Permite auditar las modificaciones realizadas sobre un registro
• Retorna el historial de operaciones con sus detalles

---

Parámetros comunes

Parámetro	Tipo	Descripción
action	select	Operación a realizar (add, bulk, filter, getField, exists, delete, modifyTags, map, logs)
group	text	Nombre del grupo al que pertenece el registro
key	text	Clave única del registro dentro del grupo
row	json/textarea	Datos del registro en formato JSON
tags	text	Etiquetas separadas por coma
tagMode	select	Modo de filtrado por tags: any, all, exclude

---

Ejemplo: CRUD básico

Guardar un cliente

{
  "action": "add",
  "group": "clientes",
  "key": "CLI-001",
  "row": {
    "nombre": "Juan Perez",
    "email": "juan@email.com",
    "plan": "premium"
  },
  "tags": "activo,premium"
}

Si el registro clientes / CLI-001 no existe, se inserta. Si ya existe, se actualizan los datos y los tags.

Buscar clientes premium

{
  "action": "filter",
  "group": "clientes",
  "tags": "premium",
  "tagMode": "any"
}

Retorna todos los registros del grupo clientes que tengan el tag premium.

Obtener email de un cliente

{
  "action": "getField",
  "group": "clientes",
  "key": "CLI-001",
  "field": "email"
}

Retorna únicamente el valor "juan@email.com".

Verificar si un cliente existe

{
  "action": "exists",
  "group": "clientes",
  "key": "CLI-001"
}

Retorna true si el registro existe, false en caso contrario.

Eliminar un cliente

{
  "action": "delete",
  "group": "clientes",
  "key": "CLI-001"
}

---

DataStore Trigger

El nodo DataStore Trigger permite iniciar un workflow automáticamente cuando se modifican registros en el DataStore.

Eventos disponibles

• insert: Se dispara cuando se inserta un nuevo registro
• update: Se dispara cuando se actualiza un registro existente
• bulk_insert: Se dispara durante inserciones masivas
• bulk_update: Se dispara durante actualizaciones masivas

Datos recibidos

Cuando se dispara el trigger, el nodo recibe:

• Los datos actuales del registro
• previousRecord para eventos de update, lo que permite comparar los valores anteriores con los nuevos

Ejemplo de uso

Escenario: Enviar un correo de bienvenida cuando se registra un nuevo cliente.

DataStore Trigger (evento: insert, grupo: "clientes")
  -> SendMail (para: {{email}}, asunto: "Bienvenido {{nombre}}")
  -> End

El trigger detecta la inserción en el grupo clientes y el workflow envia automáticamente un correo utilizando los datos del registro insertado.

---

Tags y filtrado avanzado

Los tags son cadenas de texto libres que se asignan a los registros para categorizarlos. Ejemplos: "activo", "premium", "pendiente", "urgente".

Modos de filtrado (tagMode)

• any (OR): Retorna registros que tengan AL MENOS uno de los tags especificados.

  Ejemplo: tags "premium,vip" con tagMode any retorna registros que sean premium O vip (o ambos).

• all (AND): Retorna registros que tengan TODOS los tags especificados.

  Ejemplo: tags "activo,premium" con tagMode all retorna solo registros que sean activo Y premium a la vez.

• exclude: Retorna registros que NO tengan ninguno de los tags especificados.

  Ejemplo: tags "inactivo,eliminado" con tagMode exclude retorna registros que no sean ni inactivo ni eliminado.

Combinación con grupo

Se recomienda combinar el filtrado por tags con el filtrado por grupo para obtener resultados mas precisos. Por ejemplo, filtrar por grupo "clientes" y tags "premium" con tagMode any retorna solo los clientes que sean premium, sin afectar otros grupos.

---

Ejemplo: Workflow completo con DataStore

A continuación se muestra un workflow que gestiona pedidos utilizando el DataStore para persistir datos y tags para controlar el estado.

Escenario: Procesamiento de pedidos con control de stock

Webhook (recibe pedido)
  -> DataStore (add: guardar pedido con tags "nuevo,pendiente")
  -> HTTP (consultar stock en API externa)
  -> Decision (hay stock disponible?)
    -> true: DataStore (modifyTags: quitar "pendiente", agregar "confirmado")
    -> false: DataStore (modifyTags: quitar "pendiente", agregar "sin_stock")
  -> Merge -> End

Detalle de cada paso

1. Webhook - Recibe los datos del pedido:

{
  "pedido_id": "PED-2024-100",
  "producto": "Camiseta Azul",
  "cantidad": 3,
  "cliente_email": "cliente@email.com"
}

2. DataStore (add) - Guarda el pedido:

{
  "action": "add",
  "group": "pedidos",
  "key": "PED-2024-100",
  "row": {
    "producto": "Camiseta Azul",
    "cantidad": 3,
    "cliente_email": "cliente@email.com",
    "fecha": "2026-03-23T10:00:00.000Z"
  },
  "tags": "nuevo,pendiente"
}

3. HTTP Request - Consulta el stock del producto en una API externa.

4. Decision - Evalua si hay stock suficiente basandose en la respuesta de la API.

5a. DataStore (modifyTags - rama true) - Si hay stock, actualiza el estado:

{
  "action": "modifyTags",
  "group": "pedidos",
  "key": "PED-2024-100",
  "removeTags": "pendiente",
  "addTags": "confirmado"
}

5b. DataStore (modifyTags - rama false) - Si no hay stock:

{
  "action": "modifyTags",
  "group": "pedidos",
  "key": "PED-2024-100",
  "removeTags": "pendiente",
  "addTags": "sin_stock"
}

6. Merge -> End - Ambas ramas convergen y el workflow finaliza.

Posteriormente, se puede usar un DataStore Trigger en el grupo "pedidos" para detectar cambios de estado y disparar workflows adicionales, como el envío de notificaciones al cliente o la generación de facturas.