SharePointDocumentsComponent

Este componente actúa como un puente seguro y visual entre tu flujo de trabajo en Nappai y tus repositorios de Microsoft SharePoint. Está diseñado para simplificar tareas complejas de gestión de archivos, permitiéndote automatizar la subida, descarga, organización, búsqueda y compartición de documentos sin necesidad de escribir código ni acceder directamente a la interfaz web de Microsoft 365.

¿Cómo funciona?

El componente se comunica en silencio con la API de Microsoft Graph, que es el motor oficial de SharePoint. Cuando configuras un sitio, una biblioteca y una carpeta, el componente consulta automáticamente la estructura de archivos disponible y te presenta opciones claras para interactuar con ellos.

Internamente, maneja procesos como la carga de archivos (individual o en lote), la descarga segura, la creación de carpetas, el movimiento o duplicado de elementos, y la generación de enlaces de compartición controlada. Al finalizar, devuelve un registro estructurado con los metadatos actualizados del archivo o carpeta, listo para ser usado en pasos siguientes de tu automatización.

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 Microsoft Shared Point 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 Drive Items: Lista archivos y carpetas disponibles en una biblioteca específica.
• Upload File: Sube un archivo individual a la carpeta seleccionada.
• Download File: Descarga un archivo seleccionado a tu entorno local o flujo de trabajo.
• Create Folder: Crea una nueva carpeta vacía dentro de la ruta indicada.
• Delete Item: Elimina permanentemente un archivo o carpeta del repositorio.
• Move Item: Mueve un archivo o carpeta a una ubicación diferente.
• Copy Item: Duplica un archivo o carpeta en otra ubicación específica.
• Share Item: Genera un enlace de compartición y envía invitaciones a usuarios o grupos.
• Search Files: Busca documentos por nombre, contenido o metadatos.
• Get File Metadata: Obtiene detalles técnicos del archivo (tamaño, fecha de creación, versión, etc.).
• Bulk Upload Files: Sube múltiples archivos simultáneamente de forma optimizada.

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 Files Data: Conjunto de archivos binarios para subir en grupo.
  • Visible en: Bulk Upload Files
• File Content: Contenido del archivo a subir (texto, binario o base64).
  • Visible en: Upload File
• Operation: Permite seleccionar qué acción ejecutar en este paso.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Document Library: ID de la biblioteca de documentos (drive) donde operar.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• File Name: Nombre base que se le asignará al archivo nuevo.
  • Visible en: Upload File, Create Folder
• File Types Filter: Extensiones de archivo para filtrar resultados (separadas por comas).
  • Visible en: Get Drive Items, Search Files
• Folder Name: Nombre de la nueva carpeta que se desea crear.
  • Visible en: Create Folder
• Folder Path: Ruta relativa dentro de la biblioteca donde se ejecutará la operación.
  • Visible en: Get Drive Items, Upload File, Create Folder, Search Files, Bulk Upload Files
• Item ID: Identificador único del archivo o carpeta objetivo.
  • Visible en: Download File, Delete Item, Move Item, Copy Item, Share Item, Get File Metadata
• Items Count: Límite máximo de elementos a recuperar en la consulta.
  • Visible en: Get Drive Items, Search Files
• Mapping Mode: Activa o desactiva el modo de mapeo dinámico.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• New Name: Nuevo nombre asignado al elemento durante una operación de movimiento o copia.
  • Visible en: Move Item, Copy Item
• Share Recipients: Direcciones de correo o grupos para invitar a la compartición.
  • Visible en: Share Item
• Search Query: Término de búsqueda principal para filtrar archivos.
  • Visible en: Search Files
• Share Message: Texto opcional que acompaña a la invitación de compartición.
  • Visible en: Share Item
• Share Role: Nivel de permisos que se otorgará al destinatario (lector, editor, etc.).
  • Visible en: Share Item
• Site ID: Identificador único del sitio de SharePoint de origen.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Target Parent ID: ID de la carpeta de destino para mover o copiar elementos.
  • Visible en: Move Item, Copy Item
• Mode: Define si los datos se ingresas manualmente o se seleccionan de opciones propuestas.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Site: Selecciona el sitio de SharePoint principal donde operar.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Library/Drive: Selecciona una biblioteca o unidad dentro del sitio elegido.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Path: Selecciona una ruta de carpeta o escríbela manualmente (ej. /Documentos/Informes).
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Search Items: Escribe un nombre o palabra clave y refresca la lista para filtrar resultados.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Item Type: Filtra visualmente por tipo de elemento (todos, solo archivos, solo carpetas).
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Items: Lista desplegable para seleccionar un elemento específico de la ruta actual.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files
• Depth Limit: Controla cuántos niveles de subcarpetas se mostrarán en las listas desplegables.
  • Visible en: Get Drive Items, Upload File, Download File, Create Folder, Delete Item, Move Item, Copy Item, Share Item, Search Files, Get File Metadata, Bulk Upload Files

Salidas

Al completar cualquier operación, el componente entrega un registro estructurado (Data) que puede ser conectado directamente a los siguientes pasos de tu automatización. Esta salida contiene metadatos esenciales como identificadores, rutas, tamaños y enlaces web, permitiéndote rastrear el estado del archivo o dirigirlo a otras acciones sin intervención manual.

Ejemplo de Respuesta JSONjson

{ “id”: “01AZJL5PNQYWPZK52FQKZV4FQZQZQZ”, “name”: “Reporte_Mensual_2024.pdf”, “size”: 3584000, “createdDateTime”: “2024-05-10T08:30:00Z”, “lastModifiedDateTime”: “2024-06-02T14:15:00Z”, “webUrl”: “https://contoso.sharepoint.com/sites/Ventas/Shared%20Documents/Reporte_Mensual_2024.pdf”, “file”: { “mimeType”: “application/pdf”, “hashes”: { “quickXorHash”: “abc123def456ghijklmnop” } }, “folder”: { “childCount”: 12, “parentReference”: { “name”: “Informes Mensuales”, “driveId”: “b!…” } }, “shared”: { “scope”: “organization”, “owners”: [ { “user”: { “displayName”: “Admin Principal”, “email”: “admin@empresa.com” } } ] } }

Conectividad

Este componente suele conectarse lógicamente a nodos de gestión de archivos, flujos de aprobación, distribución por correo o almacenamiento en la nube.

• Salidas hacia downstream: El objeto Data se conecta frecuentemente a componentes de transformación de datos, bases de datos locales, o sistemas de notificación para registrar el éxito de la operación.
• Entradas desde upstream: Recibe rutas, identificadores o conjuntos de archivos provenientes de componentes de extracción de datos, APIs externas o módulos de planificación de tareas, alimentando así las bibliotecas de SharePoint con nueva información automatizada.

Ejemplo de Uso

Escenario: Automatización de revisión de informes mensuales

1. Selecciona la operación Get Drive Items y elige el sitio y la carpeta Informes 2024.
2. Usa Item Type para filtrar solo archivos PDF y establece Depth Limit en 2.
3. Conecta la salida Items a un componente de validación de datos.
4. Si el archivo pasa la validación, cambia la operación a Share Item, ingresa los correos del equipo en Share Recipients, asigna el rol reader y añade un mensaje personalizado.
5. El flujo continúa automáticamente con la notificación y el registro de éxito, sin intervención manual.

Notas Importantes

🔒 Limit Shared Document Permissions 🟡 When sharing documents, only grant the minimum required permissions to users. Review SharePoint permission settings to avoid accidental exposure of sensitive data.

⚠️ Component is in Development 🔴 Because the component is marked as development, some features may not be fully stable or may change in future releases. Users may encounter unexpected behavior or bugs.

📋 Microsoft SharePoint Credentials Needed 🟡 To use this component, you must have a valid SharePoint account with appropriate permissions for the sites and libraries you intend to manage. Provide your credentials during configuration or ensure they are stored in your environment.

📋 Network Connectivity to SharePoint 🟡 The component communicates with SharePoint over the internet. Ensure that your network allows outbound HTTPS traffic to the SharePoint tenant and that any firewall or proxy settings are properly configured.

💡 Use Consistent Naming Conventions 🟢 Adopt clear and consistent file or folder names when uploading. This simplifies later searching, sharing, and automation tasks within SharePoint.

💡 Avoid Large Bulk Uploads 🟡 Uploading many large files simultaneously can exceed SharePoint’s throttling limits and result in failures. Consider batching uploads or using a dedicated bulk upload tool if you need to transfer large volumes.

ℹ️ Mapping Mode Enabled 🟢 Mapping mode automatically links input fields to SharePoint fields. Users should verify that the mappings match the target SharePoint list or library schema to avoid data mismatches.

Consejos y Mejores Prácticas

• Usa nombres de archivos descriptivos y consistentes para facilitar futuras búsquedas y automatizaciones.
• Al navegar por bibliotecas extensas, aumenta el Depth Limit con precaución, ya que consultar carpetas muy profundas puede ralentizar la respuesta.
• Si trabajas con flujos dinámicos, aprovecha el Mapping Mode para vincular salidas de un nodo con entradas de otro sin escribir valores fijos.
• Verifica siempre los permisos del sitio antes de ejecutar operaciones de escritura (subir, mover, eliminar) para evitar errores de acceso.
• Para búsquedas complejas, combina Search Query con File Types Filter y ajusta Items Count para obtener resultados más precisos y rápidos.

Consideraciones de Seguridad

• La credencial Microsoft Shared Point almacena claves de acceso sensibles. Guárdala en una sección segura de Nappai y limita su visibilidad solo a usuarios autorizados.
• Evita compartir enlaces externos si tus políticas de datos lo prohíben; utiliza siempre el rol reader o editor según la necesidad real del equipo.
• Revisa los registros de audit (lastModifiedDateTime, createdBy) en la salida del componente para mantener trazabilidad de cambios críticos.
• Si detectas errores de límite de tasa (429), reduce el volumen de operaciones simultáneas o introduce pausas controladas en tu flujo.