UnpublishDocument API¶

Sets the document at the specified path to an unpublished state. An unpublished document is not visible to regular users who only have read access -" it behaves as if no version has been officially released. This is the reverse of PublishDocument. Use this API to retract a previously published document while keeping all versions, metadata, and history intact.

Endpoint¶

/srv.asmx/UnpublishDocument

Methods¶

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

Parameters¶

Response¶

Success Response¶

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

Error Response¶

<response success="false" error="Document not found." />

Required Permissions¶

The calling user must have publish permission on the document or its containing folder.

Example¶

GET Request¶

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

POST Request¶

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&documentPath=/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:UnpublishDocument>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:documentPath>/Finance/Reports/Q1-2024-Report.pdf</tns:documentPath>
    </tns:UnpublishDocument>
  </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;
}

Takes the published version away from a document, so that readers get nothing until one is published again.

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

Afterwards GetDocument reports PublishedVersionNumber as 0. Unpublishing a document that has nothing published is a success, so this is safe to call blindly. PublishDocument puts one back.

Notes¶

• This API sets the publishing rule to UNPUBLISHED, hiding the document from read-only users.
• All document versions, metadata, and history are preserved -" unpublishing does not delete any data.
• If the document is already in an unpublished state, this call returns success without making any changes.
• To re-publish the document, use PublishDocument.

Related APIs¶

• PublishDocument - Set the published version of a document
• GetDocument - Get document properties including the current publishing status

Error Codes¶

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