GetAccessListHistory API¶

Returns the current access list plus the historical access list records for a document or folder at the specified path.

Endpoint¶

/srv.asmx/GetAccessListHistory

Methods¶

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

Parameters¶

Response¶

Success Response¶

The response contains the current access list followed by zero or more historical access list entries, each as a separate <AccessList> element ordered from newest to oldest.

<response success="true">
  <!-- Current access list -->
  <AccessList DateApplied="2024-06-15T10:30:00" AppliedBy="admin" InheritedSecurity="false">
    <Anonymous Right="0" Description="No Access" />
    <DomainMembers Right="2" Description="Read" />
    <UserGroup DomainName="Finance" GroupName="Managers" Right="6" Description="Full Control" />
    <User DomainName="Finance" UserName="jsmith" Right="5" Description="Change" />
  </AccessList>
  <!-- Historical access list (previous version) -->
  <AccessList DateApplied="2024-01-10T08:00:00" AppliedBy="manager1" InheritedSecurity="false">
    <DomainMembers Right="4" Description="Add &amp; Read" />
    <UserGroup DomainName="Finance" GroupName="Managers" Right="6" Description="Full Control" />
  </AccessList>
</response>

Error Response¶

<response success="false" error="[ErrorCode] Error message" />

Access List Element Attributes¶

Access List Child Elements¶

Right Values¶

Required Permissions¶

Read security access list permission (ActionId 26) on the target document or folder; or, without it, an administrator, a member of [Audit Managers], or a manager of the item's library. Up to 8.7 the role could not stand in for the permission, because the current list was read first.

GetAccessList, the current list alone, still needs the permission.

Example¶

GET Request¶

GET /srv.asmx/GetAccessListHistory
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &Path=/Finance/Reports/Q4Report.pdf
HTTP/1.1

POST Request¶

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&Path=/Finance/Reports/Q4Report.pdf

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:GetAccessListHistory>
      <tns:AuthenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:AuthenticationTicket>
      <tns:Path>/Finance/Reports/Q4Report.pdf</tns:Path>
    </tns:GetAccessListHistory>
  </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;
}

Reports the current access list and the ones that came before it, as repeated <AccessList> elements.

const root = await call('GetAccessListHistory', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports'
});

const [current, ...previous] = root.querySelectorAll('AccessList');

for (const old of previous) {
  console.log(old.getAttribute('DateApplied'), old.getAttribute('AppliedBy'));
}

The first <AccessList> is the one in force; the rest are history, each with the DateApplied and AppliedBy of the change that replaced it. From 9.0 an item that has never been given a list of its own answers with the changes of the folders it has been under, each with InheritedSecurity="true", since those were its lists; until 9.0 such an item answered with one element, exactly as GetAccessList does, unless its library logged security changes.

An access list is one <AccessList> element carrying the entries as children, and three attributes about the list itself: InheritedSecurity (true while the item has no list of its own), DateApplied and AppliedBy. A folder that has never been given a list inherits one and says so, with DateApplied empty.

Each entry carries a Right and a Description - the number and the name of the same thing, the name in the caller's language. The four kinds of entry are <Anonymous>, <DomainMembers>, <UserGroup> and <User>.

Notes¶

• The first <AccessList> element in the response is always the current access list.
• Subsequent <AccessList> elements are historical records from previous security changes.
• If there are no historical records, only the current access list is returned.
• From 9.0 the history is always kept, and an item that inherits has the changes of the folders it followed for its history, read as described under GetSecurityChangeLog. The SecurityChange policy's LogAction no longer decides whether anything is recorded.
• To retrieve only the current access list (without history), use GetAccessList.
• Global user groups have an empty DomainName attribute.

Related APIs¶

• GetAccessList - Get only the current access list
• SetAccessList - Set the access list for a document or folder
• ApplyInheritedAccessList - Revert to inherited security
• GetOwner - Get the owner of a document or folder

Error Codes¶

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