UnLock API¶

Unlocks (checks in) a document or all documents in a folder at the specified path. When force is true, the calling user can unlock a document currently locked by another user -" this is an administrative action that discards the other user's in-progress changes. When force is false, only the user who locked the document can unlock it.

Endpoint¶

/srv.asmx/UnLock

Methods¶

• GET /srv.asmx/UnLock?authenticationTicket=...&path=...&force=...
• POST /srv.asmx/UnLock (form data)
• SOAP Action: http://tempuri.org/UnLock

Parameters¶

Response¶

Success Response¶

<response success="true" error="" />

Error Response¶

<response success="false" error="The document is not locked by you." />

Required Permissions¶

• Normal unlock (force=false): The calling user must be the same user who locked the document.
• Force unlock (force=true): The calling user must have administrator or domain manager rights.

Example¶

GET Request¶

GET /srv.asmx/UnLock
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &path=/Finance/Reports/Q1-2024-Report.pdf
  &force=false
HTTP/1.1

POST Request¶

POST /srv.asmx/UnLock HTTP/1.1
Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&path=/Finance/Reports/Q1-2024-Report.pdf
&force=false

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:UnLock>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:path>/Finance/Reports/Q1-2024-Report.pdf</tns:path>
      <tns:force>false</tns:force>
    </tns:UnLock>
  </soap:Body>
</soap:Envelope>

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Releases a checkout taken with Lock.

await call('Lock', { authenticationTicket: ticket, Path: path });
try {
  // ... upload a new version ...
} finally {
  await call('UnLock', { authenticationTicket: ticket, Path: path, force: false });
}

force decides whose lock may be broken, not whether a missing one is ignored. Unlocking a document that is not checked out is refused 4000 whichever way force is set - so this is not safe to call blindly the way the other "remove" operations are. force=true is what breaks a checkout somebody else holds, and needs the rights to do so.

An unticketed caller is refused 4010 before the document is read, so nothing about its state is disclosed.

Notes¶

• Force unlock discards changes: When force=true, any in-progress changes the locking user has made to their local copy are permanently lost. Use with caution.
• If the path points to a folder, all documents locked within that folder are unlocked in one call (subject to the force permission rule).
• Use Lock to lock a document and GetCheckedoutDocuments to list all currently locked documents.

Related APIs¶

• Lock - Lock (check out) a document or all documents in a folder
• GetCheckedoutDocuments - Get the list of documents currently checked out by the authenticated user
• IsLockPossible - Check whether a document can be locked

Error Codes¶

The errorCode values this operation returns, checked against a running server: