DownloadDocumentVersion API¶

Downloads a specific version of a document and returns its content as a raw byte array. Use this when you need a particular historical version rather than the latest. For large files, use the chunked download workflow (GetDownloadHandlerByVersion -' DownloadFileChunk -' DeleteDownloadHandler) instead.

Endpoint¶

/srv.asmx/DownloadDocumentVersion

Methods¶

• GET /srv.asmx/DownloadDocumentVersion?authenticationTicket=...&Path=...&VersionNumber=...

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

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

Parameters¶

Response¶

Success Response¶

The response body contains the raw binary content of the specified document version.

• REST (GET/POST): Returns application/json - a JSON string holding the content as base64, not raw bytes. await response.json() gives the base64; decode it before use.

• SOAP: Returns a base64-encoded byte array within the SOAP response envelope.

Error Response¶

On any error (authentication failure, document not found, version not found, offline document, or download failure), an empty byte array is returned. There is no XML error message. The caller must check whether the returned byte array is empty to detect failure.

Required Permissions¶

Any authenticated user with read access to the document may call this API.

Example¶

GET Request¶

GET /srv.asmx/DownloadDocumentVersion

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

  &Path=/MyLibrary/Reports/Report.pdf

  &VersionNumber=3000000

HTTP/1.1

POST Request¶

POST /srv.asmx/DownloadDocumentVersion HTTP/1.1

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

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

&Path=/MyLibrary/Reports/Report.pdf

&VersionNumber=3000000

SOAP Request¶

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

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

  <soap:Body>

    <tns:DownloadDocumentVersion>

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

      <tns:Path>/MyLibrary/Reports/Report.pdf</tns:Path>

      <tns:VersionNumber>3000000</tns:VersionNumber>

    </tns:DownloadDocumentVersion>

  </soap:Body>

</soap:Envelope>

SOAP Response (success)¶

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

  <soap:Body>

    <DownloadDocumentVersionResponse xmlns="http://tempuri.org/">

      <DownloadDocumentVersionResult>JVBERi0xLjQK...</DownloadDocumentVersionResult>

    </DownloadDocumentVersionResponse>

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

The download operations do not answer XML, and over REST they do not answer raw bytes either. They are declared to return byte[], and the REST stack serialises that as application/json: the body is a JSON string whose contents are base64. Decode it before writing anything to disk.

async function download(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const base64 = await response.json();            // a JSON string, not an object

  if (base64 === '') throw new Error('empty - see below');

  return Uint8Array.from(atob(base64), c => c.charCodeAt(0));
}

A failure is reported on the HTTP response. The body of a byte-returning operation has no room for an error document, so it is still the empty answer - but the REST response carries the HTTP status the error code bands to (404 for a missing document, 403 for a refusal, and so on) and two headers beside it:

Until 9.0 every failure was "" with HTTP 200 and nothing else, so a document that is not there, a path naming a folder, a version nobody has, a refusal and a file that really is empty were all the same answer. A SOAP caller still gets the empty array and no status: there is nowhere in a SOAP envelope to put one.

const bytes = await download('DownloadDocumentVersion', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports/Q1.pdf',
  VersionNumber: 1000000        // 0 means the published version
});

VersionNumber is in the large-integer scheme - version 1 is 1000000 - and 0 means whichever version is published. A version number nothing uses comes back as the empty string like any other failure.

Notes¶

• A version number below 1,000,000 is multiplied by 1,000,000 before the lookup, so 2 means major version 2 rather than the document's second version. infoRouter packs a major, a minor and a revision into one integer as major * 1000000 + minor * 1000 + revision. The first version of a document is 1000000 and the second is 1000001; 2000000 is major version 2, not the second version. Values between 1 and 999,999 are rejected. Use GetDocumentVersions to read the numbers a document actually has rather than computing them.

• If the document is in Offline state, an empty byte array is returned.

• On any error, the response is an empty byte array with no accompanying error message. Use GetDocumentVersions to verify the version exists before downloading if you need explicit error details.

• To download the latest version without specifying a version number, use DownloadDocument.

• For large files, prefer the chunked download workflow to avoid memory and timeout issues: GetDownloadHandlerByVersion -' DownloadFileChunk -' DeleteDownloadHandler.

Related APIs¶

• DownloadDocument - Download the latest version of a document

• GetDocumentVersions - List all versions of a document (use to retrieve valid VersionNumber values)

• GetDownloadHandlerByVersion - Prepare a specific document version for chunked download

• DownloadFileChunk - Download a chunk of a file using a handler

• DeleteDownloadHandler - Clean up a download handler after use

Error Codes¶

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

All of them on the HTTP response rather than in the body; see above.