SetDocumentSummary API¶

Stores (inserts or updates) a document's summary in the DOCSUMMARY table. This is the explicit counterpart to GetDocumentSummary: it writes the summary text you provide directly to the database and does not call the infoRouter Connect service.

A document has one summary, however many versions it has. versionNumber says which version the text describes and is recorded on the row as provenance - it does not make a second summary. Calling this again overwrites what is stored, whatever version either call named.

Typical uses: - Persist a summary produced by your own pipeline or an external Connect call. - Correct or replace an auto-generated summary. - Pre-seed a summary so that GetDocumentSummary serves it without queueing any work.

Writing a summary protects it¶

Every stored summary records who wrote it. A summary written through this API is stamped with the calling user, and the server never overwrites it: regeneration only ever replaces a summary the system produced itself.

That matters when a folder has automatic summarization switched on, or when a new version is published. A summary the system generated is replaced freely; one a person wrote through this API stays as it is until a person changes it again.

The same applies to a summary stored before 9.0, when nothing recorded an author. Those carry no stamp, and an unstamped summary is left alone rather than assumed to be regenerable.

Endpoint¶

/srv.asmx/SetDocumentSummary

Methods¶

• GET /srv.asmx/SetDocumentSummary?authenticationTicket=...&path=...&versionNumber=...&summary=...
• POST /srv.asmx/SetDocumentSummary (form data)
• SOAP Action: http://tempuri.org/SetDocumentSummary

For anything but very short summaries, use POST (or SOAP). Summary text can be large and is unsuitable for a URL query string.

Parameters¶

Version Number Format¶

infoRouter uses a large-integer version numbering scheme where version numbers pack a major, a minor and a revision into one integer as major * 1000000 + minor * 1000 + revision, so the first version is 1000000 and the second is 1000001 - not 2000000, which would be major version 2. Pass 0 to target the published version, or the latest version when the document has never been published.

Behavior¶

1. Version resolution - versionNumber=0 resolves to the published version, or to the latest version when the document has never been published. Only a document with no versions at all is an error. The resolved number is what gets recorded.
2. Shortcut / URL documents - rejected with an error (they cannot hold a summary).
3. Write security - the caller must have 'Add/Change Meta data' access (see Required Permissions).
4. Offline documents - rejected with an error (content temporarily inaccessible).
5. Upsert - the summary is inserted if the document has none, or updated (overwritten) if it does. The recorded version is set to the one this call resolved.

Response¶

Success Response¶

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

Error Response¶

<response success="false" error="[901] Session expired or Invalid ticket" />

Required Permissions¶

The calling user must have 'Add/Change Meta data' access (IrAction.MetaDataAddChange) to the document - the same privilege required to modify other document metadata. Read-only users cannot store a summary.

Example¶

Request (POST)¶

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301&path=/Finance/Reports/Q1-2024-Report.pdf&versionNumber=0&summary=Q1+2024+financial+report+covering+revenue+and+expenses.

Request (SOAP)¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:SetDocumentSummary>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:path>/Finance/Reports/Q1-2024-Report.pdf</tns:path>
      <tns:versionNumber>0</tns:versionNumber>
      <tns:summary>Q1 2024 financial report covering revenue and expenses.</tns:summary>
    </tns:SetDocumentSummary>
  </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;
}

Writes the summary of a document by hand, or takes one back.

await call('SetDocumentSummary', {
  authenticationTicket: ticket,
  path: '/Finance/Reports/Q1.pdf',
  versionNumber: 0,           // 0 means the published version
  summary: 'Quarterly results, revenue up 4%.'
});

An empty summary is a summary. Sending one clears what is there, which is how a person takes back a summary they do not want - most likely one infoRouter Connect produced. That is deliberate: refusing an empty value would make "delete this summary" impossible over REST, where an empty form field arrives as null.

A summary written this way records who wrote it and which version it is of, both readable from GetDocumentSummary on the <Value> element.

Notes¶

• Insert-or-update semantics: the first call for a document inserts its single row; every later call overwrites it, including one naming a different version.
• Storing a value here also prevents GetDocumentSummary from generating one, since it serves the stored value.
• versionNumber=0 records the published version, or the latest version when the document has never been published.
• Version numbers between 1 and 999,999 are rejected. Use 0 or the modern format (e.g. 1000000 for version 1).
• Both full infoRouter paths and short document ID paths (~D{id} / ~D{id}.ext) are accepted.
• Summaries cannot be stored on shortcut or URL documents.
• The summary text is trimmed to the maximum database string length before storage.
• This API does not call the Connect service; it only writes to the database.

Error Codes¶

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

Related APIs¶

• GetDocumentSummary - Retrieve a document's summary
• GetDocumentAbstract1 - Get the full-text index abstract (auto-generated from the search index)
• GetDocument - Get full document metadata and properties