Lock API¶

Locks (checks out) the document at the specified path, so that other users cannot create new versions of it until the lock is released with UnLock.

It does not lock a folder. A folder path is accepted and answered success, but nothing is locked - see the JavaScript section below.

Terminology note: "Lock" and "Check Out" are synonymous in infoRouter. The terms are used interchangeably throughout the system.

Endpoint¶

/srv.asmx/Lock

Methods¶

• GET /srv.asmx/Lock?AuthenticationTicket=...&Path=...

• POST /srv.asmx/Lock (form data)

• SOAP Action: http://tempuri.org/Lock

Parameters¶

Response¶

Document path -" Success¶

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

Document path -" Failure¶

<response success="false" error="Document is checked out by John Smith." />

Folder path -" All documents locked successfully¶

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

Folder path -" One or more documents could not be locked¶

When a folder path is given and at least one document fails, the response contains a <log> entry per failed document with its name and the reason:

<response success="false" error="[log]">

  <log>

    <item>Q1-2024-Report.pdf</item>

    <error>Document is checked out by John Smith.</error>

  </log>

  <log>

    <item>Budget-2024.xlsx</item>

    <error>Completed documents cannot be checked out.</error>

  </log>

</response>

Required Permissions¶

The calling user must have checkout (lock) permission on the document or its containing folder. Domain managers and document owners typically have this right by default.

For folder bulk operations, each individual document is checked independently. Documents the user cannot lock are reported in the log; documents the user can lock are locked regardless.

Example¶

GET Request -" single document¶

GET /srv.asmx/Lock

  ?AuthenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

  &Path=/Finance/Reports/Q1-2024-Report.pdf

HTTP/1.1

GET Request -" all documents in a folder¶

GET /srv.asmx/Lock

  ?AuthenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

  &Path=/Finance/Reports

HTTP/1.1

POST Request¶

POST /srv.asmx/Lock HTTP/1.1

Content-Type: application/x-www-form-urlencoded

AuthenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

&Path=/Finance/Reports/Q1-2024-Report.pdf

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

               xmlns:tns="http://tempuri.org/">

  <soap:Body>

    <tns:Lock>

      <tns:AuthenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:AuthenticationTicket>

      <tns:Path>/Finance/Reports/Q1-2024-Report.pdf</tns:Path>

    </tns:Lock>

  </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;
}

Locks (checks out) a document, so that nobody else may create a version of it until UnLock releases it.

await call('Lock', { authenticationTicket: ticket, Path: '/Finance/Reports/Q1.pdf' });

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

A folder path is accepted, reports success, and locks nothing. It can be "locked" twice over, which a real lock would not allow; IsLockPossible on the same path answers 4041 "path not found"; and a subfolder can still be created inside afterwards. Lock documents one at a time.

A successful lock carries no errorCode at all, where most operations report errorCode="0". Unlocking something that is not locked is refused with 4000 rather than ignored.

Notes¶

• Document path: Locks the single document. Returns success="true" or success="false" with an error message.

• Folder path: Attempts to lock every document directly inside the folder. Returns success="true" if all succeeded, or a <log>-based response listing every document that failed and why.

• Shortcut documents (.LNK) are automatically resolved to their target document before locking.

• The same permission and state conditions enforced by IsLockPossible apply here. Use IsLockPossible first if you want to surface errors without attempting the operation.

• Locking does not create a new version -" it marks the document as checked out by the current user, preventing others from uploading new versions until the lock is released.

• After locking, upload a new version with UploadDocument or UploadDocumentWithHandler, then release the lock with UnLock. To cancel without creating a new version, call UnLock with no upload.

Related APIs¶

• UnLock - Release a lock (check in) on a document or all documents in a folder

• IsLockPossible - Check whether the current user can lock a document before attempting

• GetCheckedoutDocuments - Get the list of documents currently locked by the current user

• GetDocument - Get document properties including CheckoutBy and CheckoutDate

• UploadDocument - Upload a new version of a locked document

Error Codes¶

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