Excel

Bienvenido al componente Excel dentro del dashboard de Nappai. Este componente actúa como un puente amigable para trabajar directamente con tus archivos de Excel almacenados en OneDrive o SharePoint. Su propósito principal es facilitarte la lectura, escritura y organización de datos en tus hojas de cálculo, eliminando la necesidad de abrir manualmente cada archivo. Puedes automatizar flujos de trabajo para extraer información, actualizar registros, gestionar tablas estructuradas o configurar gráficos directamente desde la nube, manteniendo tus datos siempre sincronizados y listos para el análisis.

¿Cómo funciona?

Internamente, este componente se comunica de manera segura con el servicio oficial Microsoft Graph API. Cuando lo ejecutas dentro de un flujo de automatización, Nappai envía una solicitud autenticada que navega por la estructura de tus carpetas en la nube, identifica el libro de Excel y la hoja específicos, y lee o escribe datos en las celdas que indicas. Todo el proceso de descubrimiento de archivos, validación de rangos y manipulación de datos se realiza de forma silenciosa y automatizada, permitiendo que tus flujos avanzen sin interrupciones manuales ni copias de seguridad adicionales.

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 Microsoft Excel y guarda los campos requeridos (Client ID, Client Secret, Tenant ID y Microsoft Excel Scope).
En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

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:

Operation: Selecciona el tipo de acción principal que deseas realizar en el componente.
Mode: Define si los datos se ingresarán de forma manual o se seleccionarán de opciones prepropuestas por el sistema.
Drive ID: Identificador de la unidad de almacenamiento en OneDrive o SharePoint donde se encuentra el archivo. Si se deja vacío, se usará la unidad predeterminada.
Select Folder Path: Campo requerido para elegir la carpeta raíz donde buscarás tus archivos de Excel.
Folder Path: Ruta específica de una carpeta que contiene los archivos Excel. Si se deja en blanco, el sistema buscará en la carpeta “raíz” por defecto.
Workbook ID: Identificador único del libro de Excel que deseas manipular. Es esencial para dirigir las operaciones al archivo correcto.
Select Workbook: Permite seleccionar de una lista los libros de Excel disponibles en tu OneDrive predeterminado.
Worksheet Name: Nombre alfanumérico de la hoja de cálculo que contiene los datos (ej. “Hoja1”).
Worksheet ID: Identificador único de la hoja específica dentro del libro seleccionado.
Worksheet: Muestra y permite seleccionar las hojas disponibles en un documento de Excel de OneDrive o SharePoint.
Range Address: Dirección de las celdas en formato Excel (ej. A1:C10) que delimitará el área de lectura o escritura.
Range Values: Valores en formato de tabla bidimensional que se actualizarán en el rango de celdas especificado.
Table Name: Nombre de una tabla estructurada dentro de la hoja de Excel.
Table ID: Identificador único de la tabla estructurada que deseas consultar o modificar.
Table: Lista las tablas existentes para que puedas seleccionar la que necesitas gestionar.
Table Range: Rango de celdas que define el área de una nueva tabla (ej. A1:D10).
Table Row Values: Valores para una nueva fila en una tabla, ingresados de forma separada por comas.
Row Index: Número de fila (empezando desde 0) utilizado para eliminar o dirigir operaciones a una línea específica.
Chart Type: Tipo de gráfico que deseas crear o actualizar (ej. ColumnClustered, Line, Pie).
Chart Data Range: Rango de celdas que proporcionará los datos necesarios para dibujar el gráfico.
Shallow Search: Opción que indica si la búsqueda debe limitarse solo a la carpeta indicada o incluir todas las subcarpetas de forma recursiva.
Documents Count: Número máximo de documentos o hojas que se recuperarán en las búsquedas (por defecto: 50).

Salidas

El componente devuelve un objeto Data que contiene la información resultante de la operación. Dependiendo de la configuración, esta salida puede incluir metadatos del libro, datos extraídos en formato de tabla, información de gráficos configurados o un estatus de operación exitosa. Esta salida está diseñada para ser enlazada directamente con otros nodos del flujo, facilitando transformaciones posteriores, exportaciones a bases de datos o la generación de reportes visuales.

Ejemplo de Respuesta JSONjson

{ “data”: [ [“Proyecto”, “Fecha Inicio”, “Presupuesto”], [“Alpha”, “2023-10-01”, 15000], [“Beta”, “2023-10-05”, 23000], [“Gamma”, “2023-10-12”, 18500] ], “success_status”: true, “metadata”: { “workbook_id”: “01ABCDEF123456789”, “worksheet_name”: “Hoja1”, “range_address”: “A1:C4” } }

Conectividad

La salida Data de este componente suele conectarse lógicamente a nodos de transformación o limpieza de datos (para formatear la información extraída y estandarizar columnas), nodos de almacenamiento en bases de datos o APIs externas (para persistir los registros automatizados), o nodos de visualización y reportes (para alimentar dashboards gráficos). En flujos de escritura, la conexión típica se dirige a nodos de confirmación o envío de notificaciones para validar que los cambios se guardaron correctamente en la nube.

Ejemplo de Uso

Imagina que necesitas extraer mensualmente los registros de ventas de un archivo de Excel en SharePoint para actualizar tu tabla de ventas en Nappai. Al configurar este componente:

Seleccionas el Drive ID y la Folder Path donde está el archivo.
Ingresas el Workbook ID o seleccionas el archivo desde Select Workbook.
Especificas el Range Address (ej. “A2:D100”) para leer solo los datos relevantes y omites los encabezados.
Al ejecutar el flujo, el componente extrae esos datos y los envía como Data al siguiente nodo, listo para ser filtrado, calculado o guardado automáticamente sin intervención manual.

Consejos y Mejores Prácticas

Utiliza el campo Shallow Search como true cuando necesites velocidad y solo busques archivos en la carpeta principal; desactívalo si tus archivos están organizados en varias subcarpetas.
Mantén los nombres de hojas y tablas consistentes para evitar errores de selección en flujos repetitivos.
Si trabajas con rangos dinámicos, asegura que las fórmulas o scripts que los generen utilicen la sintaxis estándar de Excel (letras de columna + números de fila).
Valida siempre que el Mode seleccionado coincida con tu flujo: usa opciones prepropuestas para mayor estabilidad en automatizaciones críticas.
Aprovecha el Modo de Mapeo para conectar salidas de otros componentes directamente, evitando la duplicación manual de datos entre nodos.

Consideraciones de Seguridad

La autenticación se maneja de forma segura a través de Microsoft Entra y las credenciales Microsoft Excel requieren permisos delegados adecuados.
Almacenar los datos extraídos en flujos automatizados debe seguir las políticas de privacidad de tu organización, especialmente si contienen información sensible de clientes o empleados.
Revisa periódicamente los permisos asignados a la credencial para garantizar el principio de mínimo privilegio, limitando el acceso solo a los archivos y rangos estrictamente necesarios.
Mantén actualizada la credencial en el panel de Nappai para evitar interrupciones en los flujos de automatización por expiración de tokens.