UploadDocumentWithHandler2 API¶

/srv.asmx/UploadDocumentWithHandler2

1. CreateUploadHandler        -' returns UploadHandler GUID + ChunkSize
2. UploadFileChunk            -' repeat until LastChunk=true
3. UploadDocumentWithHandler2 -' finalize with version comment and manual version number

<root success="true" DocumentId="12345" VersionId="1000003" />

<root success="false" error="Invalid upload handler." />

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&path=/Finance/Reports/Q1-2024-Report.pdf
&uploadHandler=a1b2c3d4-e5f6-7890-abcd-ef1234567890
&versionComments=Released for review
&mpVersionMajor=2
&mpVersionMinor=0
&mpVersionRevision=1

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:UploadDocumentWithHandler2>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:path>/Finance/Reports/Q1-2024-Report.pdf</tns:path>
      <tns:uploadHandler>a1b2c3d4-e5f6-7890-abcd-ef1234567890</tns:uploadHandler>
      <tns:versionComments>Released for review</tns:versionComments>
      <tns:mpVersionMajor>2</tns:mpVersionMajor>
      <tns:mpVersionMinor>0</tns:mpVersionMinor>
      <tns:mpVersionRevision>1</tns:mpVersionRevision>
    </tns:UploadDocumentWithHandler2>
  </soap:Body>
</soap:Envelope>

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

await call('UploadDocumentWithHandler2', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports/Q1.pdf',
  UploadHandler: handler,
  VersionComments: 'Release 2.1.3',
  MPVersionMajor: 2,
  MPVersionMinor: 1,
  MPVersionRevision: 3
});

// 1. open a handler and read back the chunk size the server chose
const opened = await call('CreateUploadHandler', {
  authenticationTicket: ticket, PreferedChunkSize: 1048576
});
const handler = opened.getAttribute('UploadHandler');
const chunkSize = Number(opened.getAttribute('ChunkSize'));

// 2. send the file a chunk at a time, each with its own CRC32
for (let offset = 0; offset < bytes.length; offset += chunkSize) {
  const chunk = bytes.slice(offset, offset + chunkSize);
  const last = offset + chunkSize >= bytes.length;

  let sent = await post('UploadFileChunk', {
    UploadHandler: handler,
    FileChunk: base64(chunk),
    ChunkHEXCRC: crc32Hex(chunk),        // uppercase hex, no padding
    LastChunk: String(last)
  });

  // a checksum mismatch asks for that chunk again rather than for the whole upload
  while (sent.getAttribute('tryagain') === 'true') {
    sent = await post('UploadFileChunk', { /* the same chunk */ });
  }
}

// 3. commit it - this consumes the handler
await call('UploadDocumentWithHandler', {
  authenticationTicket: ticket, Path: '/Finance/Reports/Q1.pdf', UploadHandler: handler
});