DataStore - Almacenamiento de datos

Que es el DataStore

El DataStore es un sistema de almacenamiento clave-valor con capacidades de agrupacion 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): Agrupacion logica de registros. Funciona como una “tabla” o “coleccion” conceptual. Ejemplos: "clientes", "pedidos", "configuracion".
• Clave (key): Identificador unico 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 combinacion de grupo + clave es unica. Si se inserta un registro con un grupo y clave que ya existen, se realiza un UPSERT automatico (actualizacion en lugar de error).

---

Operaciones disponibles

La operacion a ejecutar se define en el parametro config.action.

add - Insertar o actualizar un registro

Inserta un nuevo registro o actualiza uno existente si la combinacion 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 segun corresponda (utilizable por DataStore Triggers)

bulk - Insercion/actualizacion masiva

Permite procesar multiples registros en una sola operacion.

• Recibe un array de registros
• keyField: campo dentro de cada registro que se usa como clave unica
• 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.

• Util cuando solo se necesita un valor puntual de un registro
• Retorna unicamente el valor del campo solicitado

exists / isFoundKey - Verificar existencia

Comprueba si un registro existe en el DataStore.

• Retorna true o false segun 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 combinacion 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.

• Util 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

---

Parametros comunes

Parametro	Tipo	Descripcion
action	select	Operacion a realizar (add, bulk, filter, getField, exists, delete, modifyTags, map, logs)
group	text	Nombre del grupo al que pertenece el registro
key	text	Clave unica 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 basico

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 unicamente 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 automaticamente 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 insercion en el grupo clientes y el workflow envia automaticamente 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.

Combinacion 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 continuacion 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 envio de notificaciones al cliente o la generacion de facturas.