
Los desarrolladores de FileMaker que construyen integraciones se hacen siempre la misma pregunta: ¿puedo bloquear un registro a través de la Data API o OData y que ese bloqueo sea visible para todos los que usan la base de datos? La respuesta corta es no. Los bloqueos nativos pertenecen a los clientes interactivos y las APIs son sin estado. Pero la necesidad es real, especialmente a medida que interfaces más ricas se trasladan a los WebViewers y la UI tiene que coordinarse con la base de datos mediante guiones.
Este artículo describe un bloqueo suave basado en concesiones que funciona en FileMaker Pro, Go, WebDirect, WebViewers y clientes API. Es mi comprensión actual, y agradezco correcciones y enfoques alternativos.
JSON( key = value, … ), LockResult( … ), LockTTL( … ), LockToken( ), IsServiceAccount( ) y Lock_Config( … ). No son funciones integradas de FileMaker. JSON() es simplemente un envoltorio ligero sobre JSONSetElement() que construye un objeto a partir de pares nombre/valor, y las demás son pequeñas funciones personalizadas que tú defines. Adapta los pasos y la sintaxis a tu propia solución.1. Por qué los bloqueos nativos no cruzan la barrera #
El bloqueo nativo de registros pertenece a un cliente que tiene un registro en modo edición, y dura solo mientras dure la edición. La Data API y OData son sin estado: cada petición es independiente, un guion ejecutado a través de una API termina cuando devuelve, y ninguna API tiene un endpoint de bloqueo. FileMaker tampoco tiene una forma integrada de avisar a los clientes conectados de que un registro se ha bloqueado o desbloqueado.
Por tanto, un guion del lado del servidor no puede mantener un bloqueo nativo entre peticiones, ni poner un campo en modo edición en nombre de un usuario de API. Lo que sí puede hacer un guion es mantener un bloqueo nativo durante su propia duración. Eso es inútil como bloqueo en sí, pero es exactamente lo que necesitamos como un mutex breve que hace atómicas las transiciones de bloqueo (sección 4).
2. Principios de diseño #
- Una tabla aparte. El estado del bloqueo vive en su propia tabla
Locks, nunca como campos del registro de datos. Los heartbeats escritos en el registro de datos incrementarían sumodId(rompiendo la concurrencia optimista), colisionarían con los editores (error 301) y contaminarían las marcas de modificación, los registros de auditoría y los disparadores. - Concesiones, no bloqueos. Un bloqueo es una concesión con una caducidad que el titular sigue renovando. Un cliente caído simplemente deja de renovar.
- Un solo reloj, y es el del servidor. Todo el temporizado usa los milisegundos UTC del servidor. Los relojes de los clientes nunca se comparan. Esto solo se cumple si todos los guiones de bloqueo se ejecutan en el servidor (ver la nota al inicio de la sección 4).
- Un token de propiedad. Al adquirir se devuelve un token secreto. Renovar, liberar y cada escritura deben presentarlo, de modo que un cliente que se durmió más allá de su concesión no pueda actuar sobre un bloqueo que ya no posee. La fila también lleva un número de generación monótono, que es el valor a usar si un sistema externo necesita un número de fencing real.
- Transiciones atómicas. Cada cambio de estado ocurre mientras la fila del bloqueo está abierta (bloqueada de forma nativa) dentro de un único guion. Dos guiones no pueden entrelazar su lectura-verificación-escritura sobre la misma fila de bloqueo.
- Imposición por privilegios. Se deniegan las escrituras directas en las tablas protegidas. Las escrituras pasan por guiones que verifican el bloqueo.
- Dos capas. El bloqueo suave evita la edición concurrente.
modIdatrapa lo que aún se escape.
Una consecuencia merece mencionarse pronto: una concesión que ha caducado pero que nadie ha tomado sigue siendo válida, porque el token demuestra que nadie más adquirió el bloqueo entretanto. La caducidad solo decide cuándo otros pueden tomar el relevo. Nada en este diseño (incluida la limpieza, sección 4.7) puede borrar el token de una concesión caducada, o esta propiedad se pierde. Solo una liberación explícita o una toma de relevo lo rota o lo borra.
3. La tabla Locks #
Una fila por registro bloqueable, creada perezosamente en el primer uso.
| Campo | Tipo | Notas |
|---|---|---|
id | Text | Clave primaria, auto-introducida Get ( UUID ) |
lock_key | Text | target_table & "|" & target_uuid. Único, validado “Always” (ver abajo) |
target_table | Text | Nombre lógico de la tabla bloqueada |
target_uuid | Text | UUID estable del registro bloqueado (nunca el ID interno del registro) |
owner_id | Text | Identidad de cuenta o usuario. Vacío significa libre |
owner_name | Text | Nombre visible para banners |
owner_client | Text | pro, go, webdirect, webviewer, api |
lock_token | Text | Secreto aleatorio por adquisición, nunca devuelto por Status. Ver sección 4.2 |
generation | Number | +1 en cada adquisición. Monótono, útil en registros y para fencing externo |
acquired_ms, renewed_ms, expires_ms | Number | Valores de Get ( CurrentTimeUTCMilliseconds ). El UTC numérico evita la ambigüedad del horario de verano |
renew_count | Number | Heartbeats en la concesión actual |
expire_logged_gen | Number | La generación para la que la limpieza ya registró EXPIRE, para que se registre una sola vez |
El lock_key único convierte una carrera de creación en el error 504 (valor no único), que los guiones tratan como “otro la creó primero, búscala de nuevo”. Pon la validación del campo en Always: FileMaker solo valida los cambios producidos por guiones (Set Field, importaciones) cuando la opción es “Always”, no cuando es “Only during data entry”. Sin ella, el 504 nunca se dispara y las filas duplicadas son posibles.
Añade una pequeña tabla LockLog (ts_ms, lock_key, event, owner_id, generation, detail). Eventos: ACQUIRE, REACQUIRE, TAKEOVER, DENIED, RELEASE, EXPIRE, FORCE_RELEASE, WRITE_OK, WRITE_REJECTED. Cuesta casi nada y ahorra horas cuando alguien pregunta por qué un registro estaba bloqueado.
4. Los guiones #
Todos los guiones toman un parámetro JSON, devuelven JSON mediante Exit Script y tienen activado Ejecutar guion con privilegios de acceso total.
| |
| Código | Significado |
|---|---|
| GRANTED, RENEWED, RELEASED, STATUS | Éxito |
| DENIED | Lo tiene otro usuario. data incluye owner, since, expires |
| LOST | El token ya no es válido (liberado o tomado por otro) |
| BUSY | Contención en la fila del bloqueo. Reintentar en breve |
| IN_USE | El registro de datos está bloqueado de forma nativa por un editor (error 301) |
| CONFLICT | modId o los valores esperados ya no coinciden |
| INVALID, NOT_FOUND, ERROR | Entrada incorrecta, registro inexistente o un error inesperado de FileMaker (en data) |
Dos funciones personalizadas mantienen los guiones cortos y consistentes: LockTTL ( raw ) devuelve 90 cuando está vacío, o el valor acotado entre 30 y 600 segundos, y LockToken ( ) devuelve Get ( UUID ) & Get ( UUID ).
4.1 Lock_Open_Row (subguion) #
Encuentra la fila del bloqueo, la crea si está permitido y la deja abierta en la sesión actual. Todo lo demás se apoya en esto. Cambia el layout de la sesión del servidor en la que se ejecuta, lo cual es inofensivo allí pero es otra razón por la que estos guiones nunca deben ejecutarse en la ventana de un usuario.
| |
4.2 Lock_Acquire #
Aquí importan dos detalles. Primero, captura en variables cada valor que devuelvas antes de registrar. El registro puede mover la sesión a otro layout, tras lo cual las referencias Locks:: pueden volver vacías. Segundo, la regla de identidad: usa la cuenta autenticada, y acepta un usuario del parámetro solo para cuentas de servicio conocidas (sección 5).
| |
Una nueva adquisición del mismo usuario desde otra sesión se concede y rota el token, así que la sesión anterior verá LOST en su siguiente heartbeat. Si prefieres que haya una sola sesión por usuario de forma estricta, guarda y compara también un id de sesión.
Get ( UUID )no está documentada como una fuente criptográficamente segura, por eso el token concatena dos. Eso basta para coordinar clientes cooperantes, pero el bloqueo suave no es una frontera de seguridad (sección 5). Si el token debe resistir a un atacante decidido, genéralo en tu backend a partir de una fuente aleatoria adecuada.
4.3 Lock_Renew #
| |
4.4 Lock_Release #
| |
4.5 Lock_Status #
Solo lectura, usado para banners y vistas de lista. Toma una lista de registros para que una pantalla de lista cueste una sola llamada, y nunca devuelve el token.
| |
4.6 Record_Update_Guarded #
Esta es la única forma en que los clientes API escriben en una tabla protegida. Comprueba el token, el modId y, opcionalmente, los valores originales de los campos que se están cambiando. La fila del bloqueo debe permanecer bloqueada durante toda la escritura, para que nadie pueda tomar el relevo, renovar o liberar en medio. Hay dos formas de conseguirlo. Ambas son correctas sobre el papel, y ambas deberían probarse en condiciones de carrera (sección 11) antes de confiar en ellas.
Variante A: dos ventanas. La fila del bloqueo permanece abierta en la primera ventana, y el registro de datos se edita en una segunda.
| |
Variante B: un bloque de transacción (Open Transaction y Commit Transaction, disponibles desde FileMaker 19.6). Los registros modificados dentro del bloque se mantienen hasta el commit, así que tocar la fila del bloqueo dentro del bloque la mantiene bloqueada mientras se escribe el registro de datos, todo en una sola ventana y sin depender del comportamiento de la segunda ventana. Una escritura exitosa también puede extender la concesión. La fila debe encontrarse antes del bloque, porque la creación y su commit no pueden ocurrir dentro de él.
| |
Las transacciones tienen sus propias reglas: no pueden anidarse (los subguiones cuentan), algunos errores revierten todo el bloque automáticamente, y un Find dentro del bloque ve los datos tal como estaban antes del bloque. Lee la documentación de Claris para tu versión antes de construir sobre esto.
En cualquier caso, en cualquier camino de fallo, cierra la ventana y revierte los registros abiertos antes de salir. La lista de permitidos importa: sin ella este guion es un endpoint de escritura genérico.
4.7 Lock_Cleanup y Lock_Force_Release #
Lock_Cleanup se ejecuta como guion programado del servidor cada pocos minutos. Takeover y Status ya evalúan la caducidad desde expires_ms, así que la limpieza no borra nada. Solo produce registros ordenados y poda datos antiguos. Nunca debe borrar lock_token ni owner_id en una fila caducada: eso convertiría una concesión que sigue siendo legítimamente del titular en LOST, lo que contradice la sección 2.
| |
Lock_Force_Release es para administradores: borra la fila (incluido el token) y registra FORCE_RELEASE con el nombre real de la cuenta de Get ( AccountName ). Restringe quién puede ejecutarlo con privilegios de ejecución de guion (solo conjuntos de privilegios de administrador). No confíes en una comprobación de Get ( PrivilegeSetName ) dentro del guion: en un guion que se ejecuta con privilegios de acceso total, esa función puede informar del conjunto de acceso total en lugar del del llamador. Cada llamada de soporte por un bloqueo atascado termina aquí, así que constrúyelo desde el primer día.
5. Imposición #
Un bloqueo suave es consultivo a menos que el servidor rechace las escrituras que lo omiten. Para las cuentas de API:
- Registros: solo lectura en las tablas protegidas, sin edición, creación ni borrado. Las escrituras pasan por
Record_Update_Guarded. - Locks y LockLog: sin acceso directo. Esto también mantiene
lock_tokenalejado de otros clientes, ya que un token legible es un secreto portador. Recuerda que la URL de la Data API necesita un layout. Usa un layout de utilidad vacío (por ejemploAPI_Utility, basado en una tabla de utilidad de un solo registro) para las llamadas a guiones, nunca un layout sobreLocks. - Guiones: acceso de ejecución solo a los guiones
Lock_*y a los escritores protegidos. - Identidad: usa
Get ( AccountName )como propietario cuando cada persona tiene una cuenta de FileMaker. Si un backend de confianza llama con una única cuenta de servicio compartida, lista esa cuenta enIsServiceAccount ( ). Solo entonces se honra el parámetrouser, y el bloqueo es exactamente tan fiable como ese backend.
Cualquier cosa con acceso total, como herramientas de administración y guiones del servidor, puede seguir eludiendo el bloqueo. Lo mismo ocurre con usuarios de FileMaker Pro cuyo conjunto de privilegios permite editar: a menos que también bloquees la edición en el layout (sección 6), un usuario de Pro puede escribir directamente en el registro. Trata el bloqueo suave como una herramienta de coordinación para clientes cooperantes, no como una frontera de seguridad.
6. Clientes FileMaker Pro, Go y WebDirect #
El bloqueo nativo sigue protegiendo a los usuarios de Pro que editan al mismo tiempo, pero los clientes API no pueden ver un bloqueo nativo hasta que su escritura choca con el error 301. Para que los usuarios de Pro participen como ciudadanos de primera clase, haz que también tomen un bloqueo suave. Cada llamada pasa por Perform Script on Server.
| Disparador | Acción |
|---|---|
| OnRecordLoad | Lock_Status para el registro. Establece $$LOCKED_BY_OTHER y el texto del banner |
| Botón Editar (o primera entrada en campo) | Lock_Acquire, guarda $$TOKEN. Si DENIED, mantén solo lectura y muestra quién lo tiene |
| OnTimer, cada 30 s | Titular: Lock_Renew. Si LOST, revierte las ediciones locales y avisa. No titular: Lock_Status para refrescar el banner |
| Save, OnRecordRevert, OnLayoutExit, OnWindowClose | Confirma si hace falta, luego Lock_Release |
| OnRecordCommit | Una última comprobación de renovación. Si LOST, devuelve False para cancelar el commit |
Una ventana solo tiene un temporizador, así que este único guion hace tanto el heartbeat como el sondeo, y puede actuar como dispatcher si el layout ya usa un temporizador. Oculta los controles de edición o bloquea la entrada en campos (OnObjectEnter devolviendo False cuando $$LOCKED_BY_OTHER = 1) y muestra un banner como “Bloqueado por María desde las 10:42”. El sondeo aún añade hasta un intervalo de temporizador de latencia.
Go. Una app en segundo plano es suspendida por el sistema operativo, así que su temporizador se detiene y la concesión caducará. Está bien, porque es el mismo camino que un cliente caído. Al volver al primer plano, llama primero a Lock_Renew. Si la concesión caducó pero nadie la tomó, el token sigue funcionando. Si devuelve LOST, trata la edición como obsoleta exactamente igual que con cualquier otro cliente.
WebDirect. Se aplican los mismos disparadores y el mismo temporizador. No cuentes con los disparadores de cierre cuando un usuario simplemente cierra la pestaña del navegador o la sesión expira. El TTL también es la red de seguridad aquí.
7. Clientes API y WebViewer #
Una llamada a guión independiente a través de la Data API tiene este aspecto (el parámetro va codificado en URL en la práctica, y scriptResult vuelve como una cadena que parseas una segunda vez). Es un GET con efectos secundarios, así que envía Cache-Control: no-store, y ten en cuenta que los parámetros muy largos chocan con los límites de longitud de URL.
| |
Los mismos guiones funcionan a través de OData. Un guion se llama con un POST a Script.<name>, el parámetro va en un único campo scriptParameterValue (se acepta un objeto JSON), y el resultado de salida del guion vuelve como resultParameter dentro de scriptResult. OData ejecuta el guion en el servidor, y solo admite guiones que no necesitan interacción del usuario, que es exactamente lo que son estos. Evita caracteres especiales y dígitos iniciales en los nombres de guion.
| |
Reglas para una UI de navegador o WebViewer:
- Heartbeat a TTL/3 (30 s para un TTL de 90 s), y renueva también inmediatamente en
visibilitychange, porque los navegadores limitan los temporizadores en pestañas en segundo plano. - Mantén el token en memoria por pestaña. Dos pestañas del mismo usuario son dos sesiones, y la segunda toma el relevo de la primera.
- Al salir de la página, envía un
Lock_Releasede mejor esfuerzo confetchykeepalive: true, desdepagehideyvisibilitychange(unloadno es fiable, especialmente en móvil).navigator.sendBeaconno puede establecer la cabecera Authorization que necesita la Data API, así que úsalo solo contra tu propio backend. El TTL es la red de seguridad de todos modos. - Un WebViewer dentro de una ventana de FileMaker no debería llamar a la API directamente. Haz que la página llame a un guion de FileMaker mediante
FileMaker.PerformScript, que usa la sesión y la identidad del propio usuario, y deja que los disparadores del layout liberen el bloqueo cuando cambie el layout, porque los eventos unload propios de la página pueden no dispararse entonces. - Una sesión de Data API caducada (por ejemplo error 952, token inválido) no es un bloqueo perdido. Vuelve a autenticarte y renueva. Si la concesión caducó sin ser tocada, el token sigue funcionando.
- En LOST, congela el formulario, mantén los cambios del usuario visibles y ofrece recargar el registro. Nunca reintentes una escritura en silencio.
- En BUSY, reintenta con un backoff corto aleatorio.
8. Concurrencia optimista #
Como el tráfico de bloqueo vive en su propia tabla, el modId del registro de datos solo cambia cuando el propio registro se modifica, así que es una versión fiable. (Las importaciones, los guiones del servidor y cualquier otra cosa que escriba el registro también lo incrementarán, que es lo que quieres.) La Data API lo devuelve con cada registro, y un PATCH que incluya un modId obsoleto falla con el error 306. Úsalo de dos formas:
- PATCH simple en tablas sin requisito de bloqueo: envía el
modIdque leíste, y ante un 306 recarga y reintenta. - Escrituras protegidas: envía el
modIdy el token juntos.
modId es grueso: cualquier cambio en el registro, incluso un campo no relacionado, provoca un conflicto. El objeto expected en Record_Update_Guarded es la opción más fina. El cliente envía los valores originales de los campos que está cambiando, y el guion rechaza la escritura solo si esos campos concretos cambiaron, así que las ediciones que no se solapan se fusionan.
Dos límites de alcance para documentar en tu solución: los portales y los registros relacionados tienen su propio modId, y un bloqueo en un padre no cubre a sus hijos por sí solo. Para bloquear un documento completo, haz que la clave del bloqueo sea el registro raíz, y deja que los escritores protegidos de las tablas hijas acepten el token de la raíz.
Para OData, el comportamiento de ETag e If-Match en el endpoint de FileMaker es algo que conviene probar contra tu versión de servidor antes de confiar en él. Si no está disponible, llama al guion protegido.
9. Modos de fallo #
| Situación | Resultado |
|---|---|
| El cliente duerme más allá de su TTL, nadie más tocó el registro | Renovar y escribir siguen funcionando (el token coincide, y la limpieza nunca lo borra). modId protege contra datos obsoletos |
| Alguien tomó el relevo entretanto | Renovar y las escrituras protegidas devuelven LOST |
| El titular liberó explícitamente, un cliente obsoleto actúa después | LOST: la liberación borra el token |
| El cliente se cae, o Go se suspende, o se cierra una pestaña de WebDirect | La concesión caduca tras el TTL y la siguiente adquisición toma el relevo |
| El guion del servidor muere a mitad de la transición | La sesión se cierra, la fila abierta se libera y los cambios no confirmados se descartan |
| FileMaker Server se reinicia | Las filas persisten y las concesiones caducan con normalidad |
| Se restaura una copia de seguridad | La tabla Locks también retrocede. Los clientes reciben LOST en su siguiente heartbeat y vuelven a adquirir. Borra la tabla tras una restauración |
| El reloj del servidor salta (reanudación de VM, paso de NTP) | Las concesiones se acortan o alargan. Mantén los TTL en 30 s o más y usa ajuste gradual de NTP. El peor caso es una toma de relevo temprana, que el antiguo titular ve como LOST |
| La sesión de Data API caduca | Vuelve a autenticarte y renueva. La concesión no se ve afectada |
| Usuario de Pro editando de forma nativa | Las escrituras API reciben IN_USE hasta que termine la edición |
| Usuario de Pro que elude la UI con privilegios de edición | No se previene. Ver sección 5 |
| Bloqueo atascado | Lock_Force_Release |
Los pasos de transacción (Open Transaction y Commit Transaction, FileMaker 19.6 en adelante) encajan bien dentro de Record_Update_Guarded (Variante B en la sección 4.6), y para escrituras de varios registros en general. Aún así no pueden abarcar varias peticiones de API, así que no sustituyen a la concesión.
10. Cuando un bloqueo suave no basta #
FileMaker no envía cambios de bloqueo a los clientes, así que todos los enfoques anteriores tienen latencia de sondeo, y la tabla de bloqueos es un punto caliente bajo alta contención. Si necesitas notificación instantánea a usuarios de WebViewer o un volumen de bloqueos alto, hay dos direcciones.
- Push desde FileMaker. Los webhooks de OData (registrados a través de la API de OData, disponibles desde FileMaker Server 22.0.4) pueden notificar a un servicio externo cuando cambian los registros de una tabla. Apuntados a la tabla Locks, un pequeño relay puede repartir los cambios a los navegadores por WebSocket o server-sent events. Consulta la documentación de webhooks para tu versión de servidor sobre lo que admite.
- Sacar la coordinación fuera. Usa un servicio externo, por ejemplo Redis con
SET key value NX PX ttly pub/sub, o un pequeño servicio delante. Los guiones de FileMaker lo llaman entonces medianteInsert from URL. Las contrapartidas son una dependencia extra y una segunda fuente de verdad que debe ser alcanzable desde cada escritor.
Para la mayoría de soluciones, el diseño basado en tabla de aquí es suficiente.
11. Lista de verificación de pruebas #
Un diseño como este solo es tan bueno como sus pruebas de carrera. Ejecútalas con varias sesiones concurrentes, no a mano:
- Dos clientes adquieren el mismo bloqueo libre al mismo instante: exactamente uno recibe GRANTED.
- Dos guiones crean la fila del bloqueo para un registro que no tiene ninguna: existe una sola fila después (esto falla en silencio si la validación de
lock_keyno está en “Always”). - Renovar tras una toma de relevo devuelve LOST. Renovar tras una concesión caducada pero no tomada tiene éxito, incluso después de que
Lock_Cleanupse haya ejecutado. - Una escritura protegida con un token obsoleto devuelve LOST, y una escritura que corre con una toma de relevo nunca aterriza después de que la toma esté confirmada.
- Una escritura protegida mientras un usuario de Pro tiene el registro abierto devuelve IN_USE.
- Una escritura con un
modIdobsoleto, y una escritura con camposexpectedcambiados, devuelven CONFLICT. Las ediciones no solapadas a través deexpectedse fusionan. - Mata el guion del servidor a mitad de la escritura: no queda ninguna fila de bloqueo abierta ni ningún dato cambiado.
Lock_Force_Releasefalla para una cuenta no administradora.- Ejecuta cada guion
Lock_*desde un cliente Pro sin Perform Script on Server: se rechaza.
Conclusión #
Sigues sin poder activar un bloqueo nativo de FileMaker desde la Data API o OData, pero puedes conseguir edición coordinada entre todos los clientes con unos cuantos ingredientes: una tabla Locks dedicada, concesiones renovadas contra el reloj del servidor, un token de propiedad verificado en cada escritura, transiciones de bloqueo hechas atómicas por un bloqueo nativo mantenido dentro del guion, privilegios que obligan a escribir a través de esos guiones, y modId como segunda línea de defensa. Constrúyelo como coordinación, haz que el servidor lo imponga, prueba las carreras y registra todo.