SetDocumentImportance API¶

Sets the importance level of the specified document. Importance is a metadata flag used to communicate the urgency or priority of a document to readers. The value can be one of five levels ranging from no marking through vital. Any authenticated user with write access to the document can update this flag.

Endpoint¶

/srv.asmx/SetDocumentImportance

Methods¶

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

Parameters¶

Response¶

Success Response¶

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

Error Response¶

<response success="false" error="the importance argument can be -1=NoMarkings; 0=Low; 1=Normal; 2=High; 3=Vital" />

Required Permissions¶

The calling user must be authenticated and have write (modify properties) permission on the document or its containing folder. No special administrator role is required.

Example¶

GET Request¶

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

POST Request¶

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&path=/Finance/Reports/Q1-2024-Report.pdf
&importance=3

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:SetDocumentImportance>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:path>/Finance/Reports/Q1-2024-Report.pdf</tns:path>
      <tns:importance>3</tns:importance>
    </tns:SetDocumentImportance>
  </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;
}

Sets how important a document is.

await call('SetDocumentImportance', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports/Q1.pdf',
  Importance: 2            // -1 NoMarkings, 0 Low, 1 Normal, 2 High, 3 Vital
});

GetDocument reads the value back as a name - NoMarkings, Low, Normal, High, Vital - rather than as the number that was sent.

A value outside that range is answered 5000, not 4000. The operation lets an ArgumentOutOfRangeException out rather than refusing the request, so a bad importance looks like a server fault. The message does name the five valid values. SetClassificationLevel, doing the same kind of job, refuses its bad values properly with 4000.

Notes¶

• The importance parameter must be exactly one of the five defined integer codes. Any other value (e.g. 4, -2) causes the API to return an error immediately without modifying the document.
• Use importance = -1 (NoMarkings) to clear any previously set importance level and return the document to a neutral state.
• The importance level is stored as document metadata and does not affect versioning, publishing, or workflow state.
• Use GetDocument to read the current Importance attribute of a document before calling this API.

Related APIs¶

• GetDocument - Get document properties including the current Importance attribute
• SetDocumentCompletionStatus - Set the completion status of a document
• UpdateDocumentProperties - Update multiple document properties in a single call

Error Codes¶

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