Importar incidencias desde Excel con Autodesk Issues API
El Excel de esta prueba tenía dos filas. Una acabó como incidencia en Autodesk; la otra quedó bloqueada porque le faltaba el título. Ese resultado pequeño permite comprobar algo que importa mucho más cuando la hoja crece: saber qué se va a enviar y qué ha ocurrido con cada fila. En esta quinta entrega de Issues Manager vamos a importar incidencias desde una plantilla Excel, conservando la revisión del formulario. La serie utiliza las APIs de Autodesk Forma y terminará ofreciendo estas mismas operaciones a un agente de IA mediante un servidor MCP.
Descarga la plantilla para el proyecto elegido
Partimos del servicio que ya crea y actualiza incidencias. Arranca la versión de este artículo siguiendo su README, entra con Autodesk y selecciona tu proyecto. Se mantienen la aplicación APS y el consentimiento de escritura de la entrega anterior; no hace falta añadir permisos nuevos.
Debajo del formulario encontrarás «Importar incidencias desde Excel». Pulsa «Descargar plantilla Excel» y trabaja sobre esa copia. Tiene una única hoja llamada Incidencias, con seis columnas en un orden fijo. Sustituye los datos sintéticos del ejemplo y comprueba que su tipo y estado existen en tu proyecto.
He limitado esta primera importación a 25 filas y 1 MiB. Quiero que el lote se pueda revisar completo antes de ejecutarlo y que un error en la hoja tenga un alcance manejable. El límite pertenece a nuestra aplicación; no es una cuota de Autodesk.
Qué poner en las seis columnas
titulo y descripcion contienen el texto. El título es obligatorio y admite hasta 100 caracteres; la descripción puede quedar vacía y admite hasta 1.000. Conserva los nombres y el orden de las columnas: cambiar «titulo» por «Incidencia» impide reconocer el archivo.
En tipo, copia una opción completa del selector, por ejemplo «General / General»: categoría y subtipo. También se admite el ID del subtipo. Si el nombre no encuentra una única opción activa, la fila queda bloqueada; no se elige una coincidencia aproximada.
estado utiliza el valor técnico permitido por Autodesk, como open o closed, aunque su interfaz muestre una traducción. En responsable puedes dejar la celda vacía o indicar el Autodesk ID, correo o nombre exacto de un miembro. Ante un homónimo, usa el correo o el ID. Después de resolver la identidad se comprueban las capacidades de asignación y, cuando corresponde, la empresa.
fecha_limite es opcional. Admite una fecha de Excel o texto YYYY-MM-DD, por ejemplo 2026-11-02. Se normaliza antes de preparar el envío y solo se incorpora si Autodesk permite ese campo. Un texto como 02/11/2026 se rechaza para evitar interpretarlo según una configuración regional distinta.
Introduce valores, no fórmulas. La lectura utiliza openpyxl con protección XML y rechaza macros, relaciones externas y celdas con fórmulas o errores. Si una columna depende de un cálculo, pega su resultado como valor en la copia que vas a importar.
Del Excel a una preparación por fila
Al pulsar «Preparar Excel · no envía incidencias», FastAPI lee el libro y conserva el número original de cada fila. Consulta los tipos activos y, si hay responsables, los miembros del proyecto. Así puede decir «falta el título en la fila 3» sin perder la relación con lo que tienes abierto en Excel.
En ImportService.prepare, los valores se convierten en el mismo PlanInput que utiliza el formulario. Este fragmento pertenece a esa función; antes ya se han resuelto el tipo y el responsable. No es un programa independiente.
request = PlanInput(
operation="create",
title=values["titulo"],
description=values["descripcion"],
status=values["estado"],
subtype_id=types[0].id,
assignee_id=assignee,
due_date=values["fecha_limite"] or None,
)
row.plan = self.issues.prepare(session, access, hub, project, request)
El Excel aporta datos y el servicio de incidencias conserva las reglas. Así no aparecen dos criterios de permiso distintos según rellenes una pantalla o una hoja. Un título vacío, un subtipo inactivo o una asignación no permitida se detectan antes de disponer de una fila lista para confirmar.
Revisa el lote antes de crear incidencias
La revisión muestra el proyecto, todas las filas y los campos exactos de las válidas. Las bloqueadas indican el motivo. Puedes corregir el archivo y preparar otra revisión, o confirmar únicamente las válidas; el botón indica cuántas enviará. Antes de marcar la aprobación, compara el proyecto y el contenido con tu hoja.
La prueba en Snowdon Towers utilizó una fila válida titulada «Prueba Código BIM · E05 · Excel», de tipo General / General, cerrada y sin responsable. Su descripción aclara que no representa un defecto real. La segunda tenía el título vacío deliberadamente. La aplicación mostró una creación pendiente y un bloqueo; solo después se aprobó el lote.
La revisión queda vinculada a la sesión, cifrada y con diez minutos de validez desde la primera preparación individual. Cambiar el archivo requiere preparar otro contenido. La aprobación corresponde a esos datos guardados, no a una hoja que se pueda sustituir mientras se está enviando.
Qué queda guardado cuando envías
Tras confirmar, la web envía las filas válidas de una en una. Cada una pasa por el ejecutor de E04, que comprueba los permisos actuales, reclama su preparación y realiza la petición. La respuesta se guarda por fila y, cuando Autodesk acepta la creación, se consulta de nuevo la incidencia para comparar los campos.
En la prueba, la fila 2 aparece como succeeded y «Relectura comprobada». El primer estado indica que Autodesk aceptó la escritura; la segunda indicación confirma esa consulta posterior. La fila 3 continúa bloqueada por falta de título. La numeración corresponde al Excel, cuya primera fila contiene las cabeceras.
Resultado real: una fila aceptada y releída; la fila sin título permanece bloqueada.
Autodesk muestra la incidencia #2, cerrada y sin responsable, con el título y la descripción previstos. La incidencia anterior permanece intacta. Cerrar no elimina y la importación tampoco activa su publicación.
Si una fila falla, consulta antes de repetir
Un lote no es una sola transacción. Si una fila se ha creado y otra falla, la primera permanece en el proyecto. El resultado permite distinguirlas; no se deshace lo aceptado para intentar que el conjunto parezca que no ha ocurrido.
Si pierdes la respuesta, pulsa «Consultar resultado del Excel guardado». Recupera lo persistido sin reenviar filas procesadas. La referencia también se recupera al volver al mismo proyecto en esta sesión del navegador. Las pendientes pueden enviarse con una nueva confirmación explícita mientras la revisión siga vigente.
Si una fila queda en ejecución o con resultado incierto, primero hay que recuperar su estado y contrastar Autodesk. Preparar de nuevo toda la hoja generaría planes distintos y podría duplicar las filas que ya se crearon. Por eso conservo el resultado de cada fila junto al lote.
La prueba real deja dos resultados visibles: una incidencia creada y una fila bloqueada antes del envío. Las pruebas automatizadas cubren además fórmulas, nombres ambiguos, caducidad y errores de respuesta. Para ampliar el tamaño de los lotes haría falta otra prueba de carga; esta importación comprueba el recorrido y sus validaciones.
Autodesk muestra la nueva incidencia #2 cerrada, junto a la incidencia #1 conservada de la entrega anterior.
Llévate el código de la serie
Suscríbete a la newsletter de Código BIM y te enviaré el repositorio con las instrucciones para elegir la versión de cada artículo. Un mismo recurso para seguir toda la serie, desde el login con Autodesk hasta el futuro servidor MCP.
El correo incluye el acceso a todas las versiones de la serie. Podrás darte de baja de la newsletter cuando quieras.
Siguiente paso: ofrecer estas operaciones desde MCP
El archivo ya termina en una revisión de operaciones y unos resultados por fila. Podemos cambiar la forma de aportar datos conservando el lugar donde se decide qué está permitido. Para una plantilla conocida ha bastado con leer columnas y aplicar reglas definidas; no ha hecho falta pedirle a una IA que interprete el Excel.
La siguiente entrega diseñará las herramientas MCP sobre esta API: consultar contexto, preparar operaciones y recuperar resultados. Más adelante se incorporará la autenticación de ese cliente. El agente llegará a un servicio que ya sabe validar y ejecutar, en lugar de recibir otra implementación distinta de las reglas.
Respuestas