Data Management webhooks: sigue la versión correcta

El panel dice «actualizado», el archivo conserva el nombre y el informe corresponde a otra versión. La interfaz está perfectamente tranquila porque nadie le ha pedido guardar una referencia que pueda contradecirla. Yo no añadiría otra luz verde hasta resolver ese detalle. Sincronizar Data Management exige identificar qué cambió, qué se procesó y qué resultado está viendo el usuario; un webhook avisa, pero no hace ese trabajo por nosotros.

Combinar Data Management y webhooks permite reaccionar a cambios documentales, pero exige distinguir recursos y estados. Seguiremos un ejemplo hipotético: una aplicación mantiene el seguimiento de modelos compartidos y prepara una revisión para cada versión relevante. El objetivo es poder explicar qué documento conocemos, qué versión hemos recuperado y qué resultado sigue pendiente, sin confundir un aviso recibido con una sincronización terminada.

El documento y su versión responden a preguntas diferentes

La presentación oficial de APS Data Management describe el acceso a proyectos, carpetas, ítems y versiones. Para entender nuestro caso basta con una distinción: el ítem permite seguir el documento a lo largo del tiempo, mientras una versión identifica un estado concreto de ese documento. La carpeta ayuda a situarlo en la organización del proyecto. Reducir todo a «archivo» puede resultar cómodo en una conversación y problemático en una base de datos.

Imagina que «ARQ_Modelo.rvt» conserva su nombre durante varias entregas. Un informe sobre una versión anterior sigue siendo válido como registro de aquel análisis, pero no demuestra que se haya revisado la que acaba de aparecer. El seguimiento necesita relacionar el informe con la versión concreta, además de con el documento. Un enlace que abre siempre lo último puede ocultar esa diferencia: el informe permanece viejo mientras su acceso parece haberse puesto al día por arte de interfaz.

Guarda identificadores con su contexto de proyecto y origen, y trata nombres y rutas como información que puede cambiar. Una relación estable permite actualizar la presentación sin perder la referencia utilizada para analizar. No deduzcas la identidad únicamente porque dos recursos compartan nombre. La existencia de dos carpetas llamadas «Compartido» demuestra que los humanos sabemos repetir convenciones, no que se refieran al mismo ámbito.

La referencia de consulta de una versión de Autodesk permite consultar el recurso específico mediante proyecto e identificador de versión. La aplicación debe seguir las relaciones y formatos documentados; no construir a mano una supuesta versión a partir del nombre visible o de una parte de la URL. Los identificadores largos resultan antipáticos para leer, pero ofrecen una precisión que «el modelo de arquitectura, el bueno» todavía no ha conseguido.

En el panel de nuestro ejemplo separaríamos versión remota conocida, versión recuperada y versión analizada. Durante el procesamiento pueden ser distintas sin que exista un fallo. Mostrar esa diferencia evita que el usuario interprete una espera normal como pérdida de datos y, sobre todo, que considere revisado lo que únicamente se ha detectado. La palabra «actualizado» necesita un complemento: actualizado respecto de qué y hasta cuándo.

Elige una suscripción que corresponda al trabajo

Un webhook comunica eventos disponibles en un servicio y dentro de un alcance definido. Para Data Management, la configuración suele referirse a recursos como carpetas; la guía de campos de Webhooks explica sistema, evento, alcance y otros campos de la suscripción. Hay que consultar qué evento corresponde al cambio que interesa, con qué permisos y en qué entorno puede utilizarse.

En el ejemplo, queremos atender versiones relevantes para coordinación. Eso exige acordar qué recurso o condición del proceso representa ese momento. Que aparezca una versión en una carpeta no convierte automáticamente su contenido en aprobado para todos los usos. La organización puede emplear otras etapas o validaciones que la aplicación tendrá que interpretar de forma explícita. El proveedor comunica un cambio; el significado operativo pertenece al flujo acordado.

Conserva qué suscripción vigila qué recurso, quién es responsable de ella y a qué entorno envía avisos. Recibir eventos de pruebas y de producción en la misma entrada sin distinguirlos puede crear resultados difíciles de explicar. Tampoco conviene ampliar el alcance por comodidad si después solo se utiliza una parte pequeña. Una integración con muchos avisos irrelevantes consume recursos y dificulta detectar el cambio que sí importaba.

La suscripción y el acceso posterior a la API no son lo mismo. El proceso que recupera metadatos o descarga información necesita una identidad con permisos suficientes sobre el recurso. Si el acceso se pierde, el estado debe reflejar esa condición. Un webhook auténtico no concede una autorización adicional para continuar, del mismo modo que recibir una dirección no demuestra que tengas permiso para abrir cualquier puerta de ese edificio.

Cuando cambie el alcance del proyecto, revisa la suscripción y retira lo que ya no corresponda. Vigila también el estado y las condiciones de entrega que documenta el servicio. Si el panel sigue mostrando una lista antigua mientras han dejado de llegar avisos, su apariencia normal puede esconder una integración detenida. Conviene que el sistema sepa explicar la última comprobación, no solo la última vez que alguien guardó un dato.

El aviso inicia una consulta sobre el recurso correcto

El receptor debería verificar autenticidad y formato, relacionar la petición con una suscripción conocida y conservar duraderamente el trabajo antes de aceptarlo. La explicación general de este recorrido está en BIM y webhooks. Aquí nos interesa lo que sucede después: transformar ese aviso en una consulta capaz de recuperar el recurso al que se refiere, sin sustituirlo accidentalmente por otro más reciente.

Supongamos que llegan dos versiones mientras la cola está ocupada. Si cada tarea pide simplemente «lo último», ambas podrían analizar la segunda y dejar la primera sin explicar. Eso quizá sea aceptable si la política decide procesar solo la versión vigente, pero debe quedar registrado como una decisión, no como un resultado accidental. Si necesitas historia, conserva la anunciada y vincula cada análisis con ella; si descartas trabajo todavía no empezado, explica qué lo ha sustituido.

La API aporta metadatos y relaciones que completan el contexto. Puede devolver una condición de acceso o un recurso que ya no está disponible cuando intentas consultarlo. Es importante distinguir esos casos de una desaparición confirmada. Borrar de inmediato todos los registros locales por una denegación puede destruir la explicación de análisis anteriores sin haber demostrado que el documento haya sido eliminado.

Para cada resultado, conserva lo necesario para localizar la versión y la regla utilizada. Una clave de trabajo puede combinar proyecto, versión y clase o versión del análisis, según la política de la aplicación. Así puedes reconocer un proceso ya registrado y decidir si corresponde recuperarlo, omitirlo o volver a evaluar con otra regla. Esta es una propuesta de diseño; la protección frente a concurrencia debe implementarse y probarse en el almacenamiento real.

Protege también los efectos externos. El proceso podría haber publicado el informe antes de fallar al actualizar su estado. Al reintentarlo, debería poder localizar ese informe en lugar de generar otro idéntico o duplicar incidencias. Deduplicar la recepción ayuda, pero no cubre por sí solo todos los puntos donde puede repetirse un efecto. Los fallos tienen la mala costumbre de aparecer justo entre las dos instrucciones que habíamos imaginado inseparables.

Un inventario periódico permite descubrir qué falta

El webhook aporta rapidez para enterarse de un cambio. Una reconciliación puede aportar una comprobación periódica de que los recursos relevantes tienen el seguimiento esperado. En nuestro caso, recorrería el alcance acordado mediante la API y compararía versiones conocidas con trabajos y resultados locales. Una ausencia podría producir una tarea recuperable utilizando las mismas reglas de identidad que el procesamiento habitual.

La referencia de carpetas de Data Management ayuda a entender sus recursos y relaciones. El recorrido de inventario debe seguir los contratos de consulta, paginación y límites que correspondan. No necesita descargar todos los modelos cada vez: primero puede revisar metadatos y profundizar cuando encuentre diferencias que requieran trabajo. La frecuencia depende del volumen, las cuotas y la demora admisible.

La comparación también puede detectar estados intermedios que llevan demasiado tiempo pendientes. Si un análisis está registrado pero no tiene resultado, pediría saber en qué etapa se detuvo y cómo retomarlo sin duplicar trabajo; si la versión ni siquiera se conoce, hay que investigar su descubrimiento. No son el mismo pendiente y no los agruparía bajo un «procesando» indefinido. Quien mantiene la integración necesita seguir el recorrido desde el aviso hasta el informe. Quien espera el resultado necesita reconocer su documento y entender qué falta, sin estudiar los nombres internos de nuestras excepciones.

No ordenes la historia documental únicamente por la fecha en que llegó cada mensaje. Una versión puede recibirse tarde o acabar de procesarse después de otra. Utiliza la identidad y los metadatos que la API permita contrastar, y evita que un resultado antiguo sustituya engañosamente al actual. El informe debe declarar qué analizó aunque siga siendo accesible junto a uno más reciente.

El panel puede mostrar la última reconciliación y qué tramo del proceso está pendiente. «Sin diferencias detectadas hasta esta comprobación» es una afirmación más útil que una luz verde eterna. También permite distinguir silencio normal de una suscripción que necesita atención. Los sistemas que solo informan cuando todo va bien suelen exigir una investigación desproporcionada para descubrir cuándo dejaron de mirar.

Mantén un seguimiento proporcionado a lo que necesitas

Antes de construir una réplica documental completa, decide qué información exige tu proceso. Para un informe ocasional quizá baste con consultar la versión solicitada. Para muchos modelos y seguimiento continuo puede compensar mantener relaciones y estados locales. Copiar cada propiedad y todos los archivos añade almacenamiento, permisos y mantenimiento que tal vez no aporten nada a la tarea.

La copia local tampoco debería convertirse en un acceso alternativo para usuarios que ya no pueden consultar el origen. Define quién puede ver resultados y datos recuperados, qué se conserva y durante cuánto tiempo. Una credencial de servicio con acceso amplio requiere que tu aplicación aplique las restricciones de su propio flujo. Tener el archivo disponible en el servidor no responde por sí solo a quién debe poder descargarlo.

La prueba debe recorrer situaciones que amenacen la coherencia: versiones consecutivas, avisos repetidos, pérdida de acceso y una interrupción del receptor. Después comprueba qué recupera el inventario y qué muestra el panel. Estos son ensayos propuestos para una implementación; el artículo no relata una sincronización ejecutada. Una prueba de transiciones con datos de ejemplo ayuda, pero la concurrencia y los permisos necesitan contrastarse con los componentes reales.

Cuando el proceso funciona, el resultado más valioso es poder responder con precisión qué se ha revisado y qué falta. El mismo nombre de archivo puede seguir apareciendo cada semana sin que la aplicación pierda la referencia del trabajo realizado. Ahí la combinación de API, avisos y reconciliación empieza a tener sentido: cada pieza aporta una evidencia distinta.

Antes de añadir otro estado de éxito, exige que cada informe identifique la versión que lo produjo. Prueba una actualización durante el procesamiento y una notificación repetida: el panel debe conservar una explicación coherente. «Actualizado» sin una revisión a la que referirse es una opinión del diseñador de la interfaz. El usuario necesita información un poco menos sentimental.