↓Ir al contenido
Ilustración isométrica de flujos de trabajo de desarrollo en FileMaker — una base de datos FM en el centro conectada a clientes, servidores y dispositivos
Un bloqueo suave basado en concesiones que funciona en FileMaker Pro, Go, WebDirect, WebViewers y clientes API.

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.

Aviso: los guiones de FileMaker de este artículo son pseudocódigo, simplificado para mayor claridad. También usan pseudo funciones personalizadas como 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 #

Bloqueo suave en 4 pasos
Abre el mapa interactivo para explorar los detalles

  1. 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 su modId (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.
  2. 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.
  3. 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).
  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.
  5. 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.
  6. Imposición por privilegios. Se deniegan las escrituras directas en las tablas protegidas. Las escrituras pasan por guiones que verifican el bloqueo.
  7. Dos capas. El bloqueo suave evita la edición concurrente. modId atrapa 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.

CampoTipoNotas
idTextClave primaria, auto-introducida Get ( UUID )
lock_keyTexttarget_table & "|" & target_uuid. Único, validado “Always” (ver abajo)
target_tableTextNombre lógico de la tabla bloqueada
target_uuidTextUUID estable del registro bloqueado (nunca el ID interno del registro)
owner_idTextIdentidad de cuenta o usuario. Vacío significa libre
owner_nameTextNombre visible para banners
owner_clientTextpro, go, webdirect, webviewer, api
lock_tokenTextSecreto aleatorio por adquisición, nunca devuelto por Status. Ver sección 4.2
generationNumber+1 en cada adquisición. Monótono, útil en registros y para fencing externo
acquired_ms, renewed_ms, expires_msNumberValores de Get ( CurrentTimeUTCMilliseconds ). El UTC numérico evita la ambigüedad del horario de verano
renew_countNumberHeartbeats en la concesión actual
expire_logged_genNumberLa 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 #

Secuencia de bloqueo de registros
Abre el mapa interactivo para explorar los detalles

Todos los guiones toman un parámetro JSON, devuelven JSON mediante Exit Script y tienen activado Ejecutar guion con privilegios de acceso total.

1
{ "ok": 1, "code": "GRANTED", "message": "", "data": { ... } }
CódigoSignificado
GRANTED, RENEWED, RELEASED, STATUSÉxito
DENIEDLo tiene otro usuario. data incluye owner, since, expires
LOSTEl token ya no es válido (liberado o tomado por otro)
BUSYContención en la fila del bloqueo. Reintentar en breve
IN_USEEl registro de datos está bloqueado de forma nativa por un editor (error 301)
CONFLICTmodId o los valores esperados ya no coinciden
INVALID, NOT_FOUND, ERROREntrada 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# Lock_Open_Row   param: { key, table, id, create }
Set Error Capture [ On ]
Set Variable [ $p ; Get ( ScriptParameter ) ]
Set Variable [ $key ; JSONGetElement ( $p ; "key" ) ]
Set Variable [ $create ; GetAsNumber ( JSONGetElement ( $p ; "create" ) ) ]
Go to Layout [ "Locks" ]
Set Variable [ $try ; 0 ]
Loop
  Set Variable [ $try ; $try + 1 ]
  Exit Loop If [ $try > 6 ]
  Enter Find Mode [ Pause: Off ]
  Set Field [ Locks::lock_key ; "==" & $key ]
  Perform Find [ ]
  If [ Get ( LastError ) = 401 ]                # no row yet
    If [ not $create ]
      Exit Script [ "MISSING" ]
    End If
    New Record/Request
    Set Field [ Locks::lock_key ; $key ]
    Set Field [ Locks::target_table ; JSONGetElement ( $p ; "table" ) ]
    Set Field [ Locks::target_uuid ; JSONGetElement ( $p ; "id" ) ]
    Commit Records/Requests [ No dialog ]
    If [ Get ( LastError ) ≠ 0 ]                # 504: another script created it first
      Revert Record/Request [ No dialog ]
    End If
  Else
    Open Record/Request
    If [ Get ( LastError ) = 0 ]
      Exit Script [ "OK" ]
    End If
    # 301: another script holds the row right now (milliseconds)
    Pause/Resume Script [ Duration (seconds): 0.15 ]
  End If
End Loop
Exit Script [ "BUSY" ]

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).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# Lock_Acquire   param: { table, id, user, name, client, ttl }
Set Error Capture [ On ]
Set Variable [ $in ; Get ( ScriptParameter ) ]
Set Variable [ $table ; JSONGetElement ( $in ; "table" ) ]
Set Variable [ $id ; JSONGetElement ( $in ; "id" ) ]
Set Variable [ $user ; Case ( IsServiceAccount ( Get ( AccountName ) ) ;
                         JSONGetElement ( $in ; "user" ) ;
                         Get ( AccountName ) ) ]
Set Variable [ $ttl ; LockTTL ( JSONGetElement ( $in ; "ttl" ) ) ]
If [ IsEmpty ( $table ) or IsEmpty ( $id ) or IsEmpty ( $user ) ]
  Exit Script [ LockResult ( 0 ; "INVALID" ; "table, id and user are required" ; "" ) ]
End If
Set Variable [ $key ; $table & "|" & $id ]

Perform Script [ "Lock_Open_Row" ; Parameter: JSON ( key = $key, table = $table, id = $id, create = 1 ) ]
If [ Get ( ScriptResult ) ≠ "OK" ]
  Exit Script [ LockResult ( 0 ; "BUSY" ; "Lock table busy, retry" ; "" ) ]
End If

# The row is open, so these values are current and nobody else can change them
Set Variable [ $now ; Get ( CurrentTimeUTCMilliseconds ) ]
Set Variable [ $held ; not IsEmpty ( Locks::owner_id ) and Locks::expires_ms > $now ]

If [ $held and Locks::owner_id ≠ $user ]
  Set Variable [ $out ; LockResult ( 0 ; "DENIED" ; "Locked by another user" ;
      JSON ( owner = Locks::owner_name, since = Locks::acquired_ms, expires = Locks::expires_ms ) ) ]
  Set Variable [ $gen ; Locks::generation ]
  Revert Record/Request [ No dialog ]
  Perform Script [ "Lock_Log" ; Parameter: JSON ( key = $key, event = "DENIED", owner = $user, generation = $gen ) ]
  Exit Script [ $out ]
End If

Set Variable [ $event ; Case ( IsEmpty ( Locks::owner_id ) ; "ACQUIRE" ;
                               Locks::owner_id = $user ; "REACQUIRE" ;
                               "TAKEOVER" ) ]
Set Variable [ $token ; LockToken ( ) ]
Set Variable [ $gen ; Locks::generation + 1 ]
Set Variable [ $exp ; $now + $ttl * 1000 ]
Set Field [ Locks::owner_id ; $user ]
Set Field [ Locks::owner_name ; JSONGetElement ( $in ; "name" ) ]
Set Field [ Locks::owner_client ; JSONGetElement ( $in ; "client" ) ]
Set Field [ Locks::lock_token ; $token ]                    # a new token invalidates any previous holder
Set Field [ Locks::generation ; $gen ]
Set Field [ Locks::acquired_ms ; $now ]
Set Field [ Locks::renewed_ms ; $now ]
Set Field [ Locks::expires_ms ; $exp ]
Set Field [ Locks::renew_count ; 0 ]
Commit Records/Requests [ No dialog ]
If [ Get ( LastError ) ≠ 0 ]
  Set Variable [ $err ; Get ( LastError ) ]
  Revert Record/Request [ No dialog ]
  Exit Script [ LockResult ( 0 ; "ERROR" ; "Commit failed" ; JSON ( error = $err ) ) ]
End If
Perform Script [ "Lock_Log" ; Parameter: JSON ( key = $key, event = $event, owner = $user, generation = $gen ) ]
Exit Script [ LockResult ( 1 ; "GRANTED" ; "" ;
    JSON ( token = $token, generation = $gen, expires = $exp, ttl = $ttl ) ) ]

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 #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Lock_Renew   param: { table, id, token, ttl }
Set Error Capture [ On ]
Set Variable [ $in ; Get ( ScriptParameter ) ]
Set Variable [ $key ; JSONGetElement ( $in ; "table" ) & "|" & JSONGetElement ( $in ; "id" ) ]
Set Variable [ $token ; JSONGetElement ( $in ; "token" ) ]
Set Variable [ $ttl ; LockTTL ( JSONGetElement ( $in ; "ttl" ) ) ]
Perform Script [ "Lock_Open_Row" ; Parameter: JSON ( key = $key, create = 0 ) ]
Set Variable [ $r ; Get ( ScriptResult ) ]
If [ $r = "BUSY" ]
  Exit Script [ LockResult ( 0 ; "BUSY" ; "Lock table busy, retry" ; "" ) ]
End If
If [ $r = "MISSING" or IsEmpty ( $token ) or Locks::lock_token ≠ $token ]
  If [ $r = "OK" ]
    Revert Record/Request [ No dialog ]
  End If
  Exit Script [ LockResult ( 0 ; "LOST" ; "Lock was released or taken over" ; "" ) ]
End If
# A matching token proves nobody took over, even if the lease has lapsed
Set Variable [ $now ; Get ( CurrentTimeUTCMilliseconds ) ]
Set Variable [ $exp ; $now + $ttl * 1000 ]
Set Field [ Locks::renewed_ms ; $now ]
Set Field [ Locks::expires_ms ; $exp ]
Set Field [ Locks::renew_count ; Locks::renew_count + 1 ]
Commit Records/Requests [ No dialog ]
Exit Script [ LockResult ( 1 ; "RENEWED" ; "" ; JSON ( expires = $exp ) ) ]

4.4 Lock_Release #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Lock_Release   param: { table, id, token }
Set Error Capture [ On ]
Set Variable [ $in ; Get ( ScriptParameter ) ]
Set Variable [ $key ; JSONGetElement ( $in ; "table" ) & "|" & JSONGetElement ( $in ; "id" ) ]
Set Variable [ $token ; JSONGetElement ( $in ; "token" ) ]
Perform Script [ "Lock_Open_Row" ; Parameter: JSON ( key = $key, create = 0 ) ]
Set Variable [ $r ; Get ( ScriptResult ) ]
If [ $r = "MISSING" ]
  Exit Script [ LockResult ( 1 ; "RELEASED" ; "Nothing to release" ; "" ) ]     # idempotent
End If
If [ $r = "BUSY" ]
  Exit Script [ LockResult ( 0 ; "BUSY" ; "Lock table busy, retry" ; "" ) ]
End If
If [ IsEmpty ( $token ) or Locks::lock_token ≠ $token ]
  Revert Record/Request [ No dialog ]                       # never touch someone else's lock
  Exit Script [ LockResult ( 0 ; "LOST" ; "Not the current holder" ; "" ) ]
End If
Set Variable [ $gen ; Locks::generation ]
Set Variable [ $owner ; Locks::owner_id ]
Set Field [ Locks::owner_id ; "" ]                          # also clear owner_name, owner_client,
Set Field [ Locks::lock_token ; "" ]                        # acquired_ms, renewed_ms, expires_ms
Commit Records/Requests [ No dialog ]                       # generation is kept
Perform Script [ "Lock_Log" ; Parameter: JSON ( key = $key, event = "RELEASE", owner = $owner, generation = $gen ) ]
Exit Script [ LockResult ( 1 ; "RELEASED" ; "" ; "" ) ]

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.

1
2
3
4
5
6
7
8
9
# Lock_Status   param: { items: [ { table, id }, ... ] }
Set Variable [ $now ; Get ( CurrentTimeUTCMilliseconds ) ]
For each item:
  Find Locks::lock_key == table & "|" & id            # no Open Record needed
  If found and owner_id is not empty and expires_ms > $now
    append { id, locked = 1, owner = owner_name, client = owner_client, since = acquired_ms, expires = expires_ms }
  Else
    append { id, locked = 0 }
Exit Script [ LockResult ( 1 ; "STATUS" ; "" ; $array ) ]

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# Record_Update_Guarded   param: { table, id, token, modId, fields: {…}, expected: {…} }
Set Variable [ $cfg ; Lock_Config ( $table ) ]     # layout, uuid field, allow-list of writable fields
Open the lock row (create = 0) in this window
If [ missing or Locks::lock_token ≠ $token ]
  Revert Record/Request ; Log WRITE_REJECTED
  Exit Script [ LockResult ( 0 ; "LOST" ; "Lock is not held by this token" ; "" ) ]
End If
# The lock row stays open for the whole write.
# Use a second window for the data record. Changing layout in this window would commit the lock row.
New Window [ Name: "data" ]
Go to Layout [ $cfg.layout ]
Find where $cfg.uuidField == $id          # 401 -> NOT_FOUND
Open Record/Request
If [ Get ( LastError ) = 301 ]
  Close Window ; Revert the lock row
  Exit Script [ LockResult ( 0 ; "IN_USE" ; "Someone is editing this record" ; "" ) ]
End If
If [ not IsEmpty ( $modId ) and Get ( RecordModificationCount ) ≠ $modId ]
  → CONFLICT, with the current modId in data
End If
For each key in JSONListKeys ( $expected ):
  If GetField ( key ) ≠ expected value → CONFLICT, listing the field names
For each key in JSONListKeys ( $fields ):
  If key is not in $cfg.allowed → INVALID
  Set Field By Name ( $table & "::" & key ; JSONGetElement ( $fields ; key ) )
Commit Records/Requests [ No dialog ]
If [ Get ( LastError ) ≠ 0 ] → Revert, ERROR with the error code (validation errors included)
Set Variable [ $newMod ; Get ( RecordModificationCount ) ]
Close Window ; Revert the lock row (nothing changed in it) ; Log WRITE_OK
Exit Script [ LockResult ( 1 ; "OK" ; "" ; JSON ( modId = $newMod ) ) ]

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Same parameters as Variant A
Perform Script [ "Lock_Open_Row" ; … create = 0 ]        # find (and open) the row, outside the block
Check token → LOST                                        # Revert Record/Request before exiting
Open Transaction [ ]
  Set Field [ Locks::renewed_ms ; $now ]                  # touch the row so it is part of the transaction
  Go to Layout [ $cfg.layout ] ; Find ; Open Record/Request    # 301 → revert the transaction, IN_USE
  Check modId and expected → revert the transaction, CONFLICT
  Set the allowed fields
Commit Transaction [ ]
Get ( LastError ) ≠ 0 → ERROR (the transaction was not committed)

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.

1
2
3
4
5
6
7
Find Locks where owner_id is not empty and expires_ms < Get ( CurrentTimeUTCMilliseconds ) - 10000
                 and expire_logged_gen ≠ generation
Loop: Open Record/Request
      re-check that it is still expired and the generation is unchanged (a renewal or takeover may have arrived)
      → Set expire_logged_gen = generation, Commit, Log EXPIRE
Delete LockLog rows older than 30 days
Optionally delete Locks rows that are free (owner_id empty) and idle for 90 days; they are re-created lazily

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_token alejado 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 ejemplo API_Utility, basado en una tabla de utilidad de un solo registro) para las llamadas a guiones, nunca un layout sobre Locks.
  • 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 en IsServiceAccount ( ). Solo entonces se honra el parámetro user, 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.

DisparadorAcción
OnRecordLoadLock_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 sTitular: Lock_Renew. Si LOST, revierte las ediciones locales y avisa. No titular: Lock_Status para refrescar el banner
Save, OnRecordRevert, OnLayoutExit, OnWindowCloseConfirma si hace falta, luego Lock_Release
OnRecordCommitUna ú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.

1
2
GET /fmi/data/vLatest/databases/CRM/layouts/API_Utility/script/Lock_Acquire
    ?script.param={"table":"Invoices","id":"3F2A…","name":"Maria","client":"webviewer","ttl":90}

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.

1
2
3
4
POST /fmi/odata/v4/CRM/Script.Lock_Acquire
{ "scriptParameterValue": { "table": "Invoices", "id": "3F2A…", "name": "Maria", "client": "api", "ttl": 90 } }

→ { "scriptResult": { "code": 0, "resultParameter": "{\"ok\":1,\"code\":\"GRANTED\", …}" } }

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_Release de mejor esfuerzo con fetch y keepalive: true, desde pagehide y visibilitychange (unload no es fiable, especialmente en móvil). navigator.sendBeacon no 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 modId que leíste, y ante un 306 recarga y reintenta.
  • Escrituras protegidas: envía el modId y 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ónResultado
El cliente duerme más allá de su TTL, nadie más tocó el registroRenovar y escribir siguen funcionando (el token coincide, y la limpieza nunca lo borra). modId protege contra datos obsoletos
Alguien tomó el relevo entretantoRenovar y las escrituras protegidas devuelven LOST
El titular liberó explícitamente, un cliente obsoleto actúa despuésLOST: la liberación borra el token
El cliente se cae, o Go se suspende, o se cierra una pestaña de WebDirectLa concesión caduca tras el TTL y la siguiente adquisición toma el relevo
El guion del servidor muere a mitad de la transiciónLa sesión se cierra, la fila abierta se libera y los cambios no confirmados se descartan
FileMaker Server se reiniciaLas filas persisten y las concesiones caducan con normalidad
Se restaura una copia de seguridadLa 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 caducaVuelve a autenticarte y renueva. La concesión no se ve afectada
Usuario de Pro editando de forma nativaLas escrituras API reciben IN_USE hasta que termine la edición
Usuario de Pro que elude la UI con privilegios de ediciónNo se previene. Ver sección 5
Bloqueo atascadoLock_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 ttl y pub/sub, o un pequeño servicio delante. Los guiones de FileMaker lo llaman entonces mediante Insert 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:

  1. Dos clientes adquieren el mismo bloqueo libre al mismo instante: exactamente uno recibe GRANTED.
  2. 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_key no está en “Always”).
  3. 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_Cleanup se haya ejecutado.
  4. 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.
  5. Una escritura protegida mientras un usuario de Pro tiene el registro abierto devuelve IN_USE.
  6. Una escritura con un modId obsoleto, y una escritura con campos expected cambiados, devuelven CONFLICT. Las ediciones no solapadas a través de expected se fusionan.
  7. Mata el guion del servidor a mitad de la escritura: no queda ninguna fila de bloqueo abierta ni ningún dato cambiado.
  8. Lock_Force_Release falla para una cuenta no administradora.
  9. 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.