Document

El componente Document dentro de Nappai te permite interactuar de manera segura y sencilla con tus bases de datos MongoDB. Su objetivo principal es ayudarte a gestionar tus registros (datos) sin necesidad de escribir código complejo, ofreciendo herramientas intuitivas para buscar, agregar, modificar, eliminar o simplemente contar cuántos elementos existen en una colección. Está diseñado para funcionar como un puente confiable entre tus flujos de automatización y tu sistema de gestión de datos.

¿Cómo funciona?

Internamente, este componente actúa como un “gestor inteligente” que se conecta a tu base de datos MongoDB. Cuando configuras el nombre de la base de datos y la colección donde deseas trabajar, el sistema valida tus credenciales, verifica que los filtros y datos de entrada sean correctos, y ejecuta la operación solicitada de forma segura. Una vez que completa la tarea, te devuelve el resultado (por ejemplo, la lista de documentos encontrados o una confirmación de que se insertaron/modificaron correctamente) listo para ser usado en el siguiente paso de tu automatización. La lógica de validación, conexión y manejo de errores se encarga el sistema en segundo plano, permitiéndote enfocarte únicamente en lo que quieres lograr con tus datos.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con el servicio externo:

Dirígete a la sección de Credenciales en tu panel de Nappai.
Crea una nueva credencial del tipo MongoDB Connection y guarda los campos requeridos (método de conexión, cadena de conexión, usuario, contraseña, cluster y dominio).
En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Entradas

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones según lo que decidas realizar:

Database Name: Indica el nombre de la base de datos donde están almacenados tus datos. Es un campo obligatorio para establecer el destino correcto de la operación.
Collection Name: El nombre de la colección (equivalente a una tabla o carpeta de registros) donde se realizarán las operaciones con los documentos.
Operation: Permite elegir qué deseas hacer con los datos: buscar documentos, agregar nuevos, actualizar datos existentes, reemplazar documentos completos, eliminar registros o simplemente contar cuántos hay.
Filter: Especifica qué documentos deben ser afectados por la operación. Puedes indicar condiciones como estado, fecha o tipo de dato. Debe contener una condición válida; si lo dejas vacío {, afectará a todos los documentos de la colección.
Query Filter: Documento de consulta utilizado específicamente para seleccionar documentos en las operaciones de búsqueda y conteo. Debe ser un JSON válido. Si lo dejas vacío, se considerarán todos los documentos.
Document: Los datos que deseas agregar o reemplazar en la base de datos. Puede aceptar objetos de datos, mensajes o cadenas en formato JSON. Es obligatorio cuando eliges operaciones de inserción o reemplazo.
Update Data: Especifica los cambios que deseas realizar utilizando los operadores de actualización de MongoDB (como modificación de valores o incremento de números). Es obligatorio para la operación de actualización.
Upsert: Si lo activas, creará un nuevo documento si no encuentra ninguno que coincida con tu filtro. Ideal cuando quieres actualizar datos existentes o crearlos automáticamente si aún no existen.
Multiple Documents: Define si los cambios deben aplicarse a todos los documentos que coincidan con el filtro (Verdadero) o solo al primero que se encuentre (Falso).
Limit: Establece el número máximo de resultados que se devolverán. Útil para controlar el volumen de datos que procesas en cada ejecución y evitar sobrecargas.
Skip: Permite omitir los primeros N resultados. Es muy útil para la paginación, por ejemplo, para saltarte los primeros 100 registros y visualizar el siguiente grupo.
Sort: Define el orden de los resultados devueltos. Puedes usar 1 para ordenar de forma ascendente (A-Z, menor a mayor) o -1 para descendente (Z-A, mayor a menor). Deja vacío para mantener el orden original.
Return ID: Cuando está activado, incluye el campo único de identificación de MongoDB en los resultados. Desactívalo si solo necesitas un resultado más limpio y legible para mostrar en paneles o reportes.

Salidas

Data: Contiene los documentos recuperados o confirmados tras la ejecución exitosa del componente. Este resultado puede conectarse directamente a otros nodos del flujo para mostrarlo en un dashboard, transformar su formato, guardarlo en otro sistema o evaluarlo en condiciones lógicas.

Ejemplo de Respuesta JSONjson

{ “status”: “success”, “data”: [ { “_id”: “64f7a1b2c9d8e7f6a5b4c3d2”, “name”: “Ana Pérez”, “role”: “admin”, “last_login”: “2023-10-25T14:30:00Z” }, { “_id”: “64f7a1b2c9d8e7f6a5b4c3d1”, “name”: “Carlos López”, “role”: “user”, “last_login”: “2023-10-24T09:15:00Z” } ], “count”: 2 }

Conectividad

En un flujo de automatización, este componente suele conectarse como un origen de datos o validador. Por ejemplo, su salida Data puede enlazarse directamente a nodos de Visualización para mostrar resultados en un dashboard, a nodos de Transformación para limpiar o reestructurar la información, o a nodos condicionales para verificar si se encontraron registros antes de ejecutar un paso crítico. También es común usar esta salida en validaciones previas a operaciones de actualización o eliminación, asegurando que solo se actúe sobre los documentos correctos.

Ejemplo de Uso

Imagina que estás automatizando la gestión de clientes en tu sistema. Puedes usar el componente Document con la operación Buscar para recuperar todos los clientes cuyo estado sea “activo”. Configuras el Query Filter como {"status": "active"}, estableces un Limit de 50 y activas el Sort para ordenarlos por fecha de registro de forma ascendente. Una vez ejecutado, el componente devolverá la lista de clientes en su salida Data, la cual puedes conectar directamente a un nodo para enviarles un email personalizado, actualizarlos en otra herramienta o mostrarlos en una tabla interactiva de tu panel de control.

Consejos y Mejores Prácticas

Comienza siempre con operaciones de Buscar o Contar para verificar que tus filtros y credenciales están funcionando correctamente antes de realizar cambios.
Usa el campo Limit con moderación cuando trabajes con colecciones grandes para evitar sobrecargar la conexión de la base de datos y mejorar el rendimiento del flujo.
Cuando necesites realizar cambios masivos, activa la opción Multiple Documents y valida tus filtros cuidadosamente para asegurar que solo se afecten los registros deseados.
Si solo necesitas verificar si un documento existe o cuántos hay, utiliza la operación Contar en lugar de Buscar, ya que es más rápida y consume menos recursos del sistema.
Mantén los filtros lo más específicos posible para evitar operaciones accidentalmente amplias que puedan afectar a datos importantes.

Consideraciones de Seguridad

Asegúrate de que las credenciales de MongoDB estén configuradas con los permisos mínimos necesarios para la operación que necesitas (solo lectura para búsquedas, solo escritura para actualizaciones/eliminaciones).
Evita usar filtros vacíos {} en operaciones de actualización o eliminación en entornos de producción, ya que podrían afectar a toda la colección por error.
Revisa los logs de Nappai si alguna operación falla; el mensaje de error generado te ayudará a identificar rápidamente si el problema es de conexión, validación de datos o permisos de usuario.
No compartas ni expongas las cadenas de conexión o credenciales en nodos públicos o compartidos. Utiliza siempre el gestor de credenciales integrado de Nappai para mantener la información segura.