Lists

Este componente actúa como un puente directo entre Nappai y Microsoft SharePoint. Su propósito es permitirte organizar, consultar y modificar listas y sus registros sin necesidad de escribir código ni acceder a entornos de desarrollo. A través de una interfaz visual intuitiva en tu dashboard, puedes seleccionar una sitio de SharePoint, elegir una lista específica y realizar acciones sobre los datos almacenados en ella. El sistema se encarga automáticamente de las conexiones seguras con los servidores de Microsoft, garantizando que tu información se mantenga sincronizada y accesible.

¿Cómo funciona?

El componente funciona siguiendo un flujo paso a paso muy similar a cómo interactuarías manualmente con SharePoint: primero eliges el contexto (el sitio y la lista), luego defines qué acción quieres realizar y finalmente proporcionas los datos necesarios. Internamente, traduce tus selecciones y entradas en solicitudes seguras hacia la API de SharePoint. Dependiendo de la operación que elijas, el componente sabrá si debe leer datos existentes, crear registros nuevos, actualizar información ya guardada o eliminar elementos. Todo este proceso está controlado por un solo interruptor de operación para evitar confusiones y asegurar que cada ejecución cumpla exactamente con lo que necesitas.

Conexión y Credenciales

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

1. Dirígete a la sección de Credenciales en tu panel de Nappai.
2. Crea una nueva credencial del tipo Microsoft Shared Point y guarda los campos requeridos (Client ID, Client Secret, Tenant ID y Scope).
3. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Get Site Lists: Obtiene y muestra todas las listas disponibles dentro de un sitio de SharePoint seleccionado.
• Create List: Crea una nueva lista en SharePoint con el nombre, plantilla y descripción que indiques.
• Get List Items: Recupera los registros (ítems) existentes en una lista específica de SharePoint.
• Create List Item: Agrega un nuevo registro o fila dentro de una lista ya existente.
• Update List Item: Modifica la información de un registro específico que ya existe en una lista.
• Delete List Item: Elimina permanentemente un registro seleccionado de una lista de SharePoint.
• Bulk Create Items: Permite crear múltiples registros a la vez mediante un lote de datos estructurados.
• Search List Items: Busca y filtra registros en una lista usando palabras clave o consultas específicas.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

• Bulk Items Data: Contiene una lista de estructuras de datos para crear varios registros a la vez.
  • Visible en: Bulk Create Items
• List Item Data: Guarda los datos y metadatos necesarios para agregar o modificar un registro.
  • Visible en: Create List Item, Update List Item, Bulk Create Items
• Operation: Define cuál será la acción principal que ejecutará el nodo en esta iteración.
  • Visible en: Get Site Lists, Create List, Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items
• Filter Query: Aplica condiciones específicas para filtrar qué registros se mostrarán o procesarán.
  • Visible en: Get List Items, Search List Items
• List Item ID: Es el identificador único del registro que deseas modificar o eliminar.
  • Visible en: Update List Item, Delete List Item
• Items Count: Establece cuántos registros máximo deseas recuperar en una sola operación.
  • Visible en: Get Site Lists, Get List Items, Search List Items
• List Description: Texto explicativo que se guardará como descripción de la nueva lista.
  • Visible en: Create List
• List ID: Identificador único de la lista de SharePoint donde se realizará la operación.
  • Visible en: Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items
• List Name: Nombre legible para crear una nueva lista o como término de búsqueda.
  • Visible en: Create List
• List Template: Elige el tipo de estructura predefinida que tendrá tu nueva lista.
  • Visible en: Create List
• Mapping Mode: Activa o desactiva las opciones avanzadas de vinculación de datos entre componentes.
  • Visible en: Get Site Lists, Create List, Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items
• Search Query: Palabra clave o frase que usará SharePoint para buscar registros coincidentes.
  • Visible en: Search List Items
• Site ID: Identificador del sitio de SharePoint donde se buscarán o guardarán los datos.
  • Visible en: Get Site Lists, Create List, Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items
• Mode: Determina si los datos se ingresan manualmente o se seleccionan de opciones sugeridas por el sistema.
  • Visible en: Get Site Lists, Create List, Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items
• Site: Selecciona el sitio de SharePoint desde donde deseas trabajar.
  • Visible en: Get Site Lists, Create List, Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items
• List: Elige la lista específica dentro del sitio seleccionado donde se realizarán los cambios.
  • Visible en: Get Site Lists, Create List, Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items
• List Item: Permite seleccionar un registro concreto para operar sobre él de forma visual.
  • Visible en: Get Site Lists, Create List, Get List Items, Create List Item, Update List Item, Delete List Item, Bulk Create Items, Search List Items

Salidas

Al ejecutar el componente, recibirás información estructurada que podrás usar en los siguientes pasos de tu flujo:

• Data: El contenido principal devuelto por la operación (por ejemplo, una lista de registros recuperados o confirmación de creación).
• result: Un resumen en formato diccionario que indica si la operación fue exitosa, incluye métricas o detalles del estado final.
• status_code: Código numérico que indica el resultado técnico de la conexión con el servidor (ej. 200 para éxito, 404 si no se encontró algo, 500 para errores del servidor).
• errors: Lista de mensajes detallados en caso de que la operación falle, ayudándote a diagnosticar y corregir el problema.

Ejemplo de Respuesta JSONjson

{ “data”: [ { “id”: “42”, “Title”: “Revisión de Proyecto Alpha”, “Status”: “Pendiente”, “DueDate”: “2024-11-30”, “AssignedTo”: “juan.perez@empresa.com” }, { “id”: “43”, “Title”: “Solicitud de Presupuesto Q4”, “Status”: “En espera”, “DueDate”: “2024-12-15”, “AssignedTo”: “maria.garcia@empresa.com” } ], “status_code”: 200, “result”: { “success”: true, “message”: “Registros recuperados correctamente”, “count”: 2 } }

Conectividad

Las salidas de este componente están diseñadas para fluir naturalmente hacia otros nodos de automatización en tu dashboard. Por ejemplo, el campo Data suele conectarse a componentes de almacenamiento (como bases de datos o hojas de cálculo), a motores de procesamiento de datos (para ordenar o transformar información) o a sistemas de notificación (para enviar alertas basadas en los registros encontrados). Si usaste una operación de búsqueda o recuperación, es común conectar el resultado a un componente de lógica condicional que decida qué hacer según el estado de los registros. Esta arquitectura permite que los datos de SharePoint sean el punto de partida fiable para el resto de tus flujos de trabajo.

Ejemplo de Uso

Escenario: Actualizar el estado de una tarea pendiente en una lista de seguimiento de proyectos.

1. Selecciona la operación Update List Item.
2. En Site, elige tu sitio de trabajo principal.
3. En List, selecciona la lista “Proyectos Q4”.
4. En List Item ID, ingresa o mapea el ID del registro que necesitas modificar.
5. En List Item Data, agrega un diccionario con los campos a actualizar: {"Status": "Completado", "ReviewDate": "2024-10-01"}.
6. Al ejecutar el nodo, el componente se conectará a SharePoint, encontrará el registro específico y actualizará solo los campos indicados, devolviendo un status_code: 200 y confirmando el cambio en Data.

Notas Importantes

🔒 Protect Sensitive Data 🔴 SharePoint list operations expose data to the network. Ensure your credentials are stored securely and use encrypted connections to protect sensitive information.

🟡 Component is in Development 🟡 This component is flagged as ‘is_development’, meaning it may contain bugs or incomplete features. Unexpected behavior or errors could occur during use.

📋 Valid SharePoint Credentials Required 🔴 To use this component you must provide valid Microsoft SharePoint authentication credentials and the URL of the SharePoint site you want to manage.

💡 Use Specific List Names 🟢 When creating, updating, or deleting lists, specify the exact list name to avoid affecting unintended lists. This reduces the risk of accidental data loss.

⚙️ Enable Mapping Mode Carefully 🟢 The component’s ‘mapping_mode’ flag allows field mappings between your system and SharePoint. Ensure your mapping configuration is correct, as incorrect mappings can cause data mismatch.

ℹ️ Delete Operations Are Irreversible 🟡 When you delete a SharePoint list, the data is permanently removed and cannot be recovered through this component. Double‑check before executing delete actions.

Consejos y Mejores Prácticas

• Verifica siempre que el Site y la List seleccionados sean correctos antes de ejecutar operaciones de actualización o eliminación.
• Cuando trabajes con Bulk Create Items, divide los grandes volúmenes de datos en lotes manejables para evitar retrasos o límites de la API.
• Usa el modo Mapped en lugar de valores fijos cuando los datos provengan de otros pasos del flujo; esto hará tu automatización más dinámica y menos propensa a errores manuales.
• Revisa los códigos de status_code en cada ejecución; un 200 o 201 indica éxito, mientras que 4xx o 5xx requieren revisión de credenciales o permisos.
• Mantén una copia de respaldo o activa la papelera de reciclaje de SharePoint antes de realizar operaciones masivas o de borrado.

Consideraciones de Seguridad

Este componente interactúa directamente con servicios en la nube, por lo que es fundamental proteger tus credenciales de acceso. Nunca compartas tokens, Client IDs o Client Secrets por canales no seguros. Asegúrate de que tu cuenta de Microsoft Shared Point tenga solo los permisos necesarios (principio de mínimo privilegio) para evitar accesos no autorizados a información sensible. Además, verifica que tu entorno de Nappai utilice conexiones cifradas (HTTPS/TLS) y revisa periódicamente los registros de auditoría de tu tenant para detectar actividad inusual.