Collection Updates by Other Services

Description

This section covers the process for executing “concurrent” updates when new documents need to be added to an existing collection or when metadata changes should be propagated to Dossier Organizer. These updates are typically triggered by backend services interacting with Dossier Organizer collections.

Since these updates may conflict with end users currently performing work on a collection, they require special handling.

---

Collection Updates Process

1. Attempt to Save or Add to a Collection

Whenever a backend service attempts to update a collection (either by adding a new document or modifying metadata), the first step is trying to save the updated collection via the PUT /api/v1/collections/{collectionID} endpoint.

• If successful, the update is completed, and no further steps are required.
• If an error occurs, the collection may be locked, or there could be a version conflict. If the collection is currently locked by another user, an HTTP 409 Conflict status will be received. If this is the case, you can request the lock as described in the next step.

2. Handling Errors and Acquiring a Lock

1. Request a lock:
   Typically, explicit lock requests are only needed when a user is working directly with the collection. If a service performs an update on an unlocked collection, the backend will automatically acquire a lock for the duration of the update and release it immediately after.

   However, if the collection is already locked by another client or service, and a service still needs to proceed with an update, it can trigger a user prompt by contesting the lock. The service should send a POST request to the /api/v1/locks/{scope}/contest endpoint to initiate this contestation process.

2. Release the lock:
   In case of a lock request by a service or another client, the client holding the lock will be prompted to release the lock: After releasing the lock, the requesting (or any other service) can acquire the lock and perform changes on the collection. If the user denies the request to release the lock, he can proceed with his work on the collection and save the collection whenever he is finished.

3. Retry the operation:
   After acquiring the lock, attempt to save the changes again. If the lock is held by another process or user, you should poll the update operation to allow time for the user to respond to the lock contestation prompt. If the user decides to keep the lock, it is recommended to save the operation and retry at a later time, once the lock becomes available.

Best Practices

Aggregate updates:
Instead of performing several fine-grained updates on the same collection, it is recommended to aggregate changes into a single update operation. This reduces the chances of conflicts and improves overall efficiency by generating fewer meaningless versions.

---