UpdateDocumentProperties API¶

Updates the core properties of the specified document: display name, description, and update instructions. All three fields are optional -" only the fields provided are updated. This is the base version of the API; use UpdateDocumentProperties1 or UpdateDocumentProperties2 to also update source, language, author, and importance.

Endpoint¶

/srv.asmx/UpdateDocumentProperties

Methods¶

GET /srv.asmx/UpdateDocumentProperties?authenticationTicket=...&path=...&newDocumentName=...&newDescription=...&newUpdateInstructions=...
POST /srv.asmx/UpdateDocumentProperties (form data)
SOAP Action: http://tempuri.org/UpdateDocumentProperties

Parameters¶

Parameter	Type	Required	Description
`authenticationTicket`	string	Yes	Authentication ticket obtained from `AuthenticateUser`.
`path`	string	Yes	Full infoRouter path to the document (e.g. `/Finance/Reports/Q1-Report.pdf`), or a short document ID path (`~D{id}`).
`newDocumentName`	string	No	New display name for the document (without extension). Pass `null` or omit to leave unchanged. Maximum 128 characters.
`newDescription`	string	No	New description for the document. Pass `null` or omit to leave unchanged. Line endings are normalized automatically. Maximum 4000 characters; a longer value is refused with `4000`.
`newUpdateInstructions`	string	No	New update instructions for contributors. Pass `null` or omit to leave unchanged. Line endings are normalized automatically. Maximum 4000 characters; a longer value is refused with `4000`.

Response¶

Success Response¶

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

Error Response¶

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

Required Permissions¶

The calling user must have write (modify properties) permission on the document or its containing folder.

Example¶

GET Request¶

GET /srv.asmx/UpdateDocumentProperties
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &path=/Finance/Reports/Q1-2024-Report.pdf
  &newDocumentName=Q1+2024+Financial+Report
  &newDescription=Quarterly+financial+summary+for+Q1+2024
  &newUpdateInstructions=Update+by+end+of+following+quarter
HTTP/1.1

POST Request¶

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&path=/Finance/Reports/Q1-2024-Report.pdf
&newDocumentName=Q1 2024 Financial Report
&newDescription=Quarterly financial summary for Q1 2024
&newUpdateInstructions=Update by end of following quarter

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:UpdateDocumentProperties>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:path>/Finance/Reports/Q1-2024-Report.pdf</tns:path>
      <tns:newDocumentName>Q1 2024 Financial Report</tns:newDocumentName>
      <tns:newDescription>Quarterly financial summary for Q1 2024</tns:newDescription>
      <tns:newUpdateInstructions>Update by end of following quarter</tns:newUpdateInstructions>
    </tns:UpdateDocumentProperties>
  </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;
}

Renames a document and sets its description and update instructions.

// Read what is there, change one thing, write all three back.
const document = (await call('GetDocument', {
  authenticationTicket: ticket, Path: path,
  withPropertySets: false, withSecurity: false, withOwner: false, withVersions: false
})).querySelector('document');

await call('UpdateDocumentProperties', {
  authenticationTicket: ticket,
  Path: path,
  NewDocumentName: document.getAttribute('Name'),
  NewDescription: 'Quarterly results',
  NewUpdateInstructions: document.getAttribute('UpdateInstructions')
});

Which of the three to use¶

	Name, description, update instructions	Source, language, author	Importance
UpdateDocumentProperties	yes
UpdateDocumentProperties1	yes	yes
UpdateDocumentProperties2	yes	yes	yes

Each writes every field it takes, so a value left empty is cleared rather than left alone. Read the document with GetDocument first and send back what should survive. Using the wider variant to change one narrow field will empty the fields it adds.

NewDocumentName is nullable, so an empty one reaches the operation and is refused with 4000 "a document must have a name" rather than by model binding. A name carrying any of / \ : * ? " < > | # % & + or a tab is refused 4000 too - unlike creating a document, where such a name is silently cleaned up.

Notes¶

Passing null for any optional parameter leaves that field unchanged.
Line endings in newDescription and newUpdateInstructions are normalized to the server format.
To also update source, language, and author, use UpdateDocumentProperties1.
To also update importance, use UpdateDocumentProperties2.
Renaming a document via newDocumentName does not change its URL path -" the path uses the file name including extension.

UpdateDocumentProperties1 - Update properties including source, language, and author
UpdateDocumentProperties2 - Update properties including source, language, author, and importance
GetDocument - Get all current document properties

Error Codes¶

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

`errorCode`	When
`4010`	the ticket is expired or unknown, or there is no ticket at all
`4041`	no document at that path - including a folder path, and one the caller may not see
`4000`	`NewDocumentName` is empty or carries a character a document name may not
`4090`	a document of the new name is already in the folder
`4030`	the caller may not change this document
`HTTP 400`	a required string parameter was empty; refused by model binding, so there is no error document

Error	Description
`[900] Authentication failed`	Invalid or missing authentication ticket.
`[901] Session expired or Invalid ticket`	The ticket has expired or does not exist.
Document not found	The specified path does not resolve to an existing document.
Access denied	The user does not have write permission on the document.
`SystemError:...`	An unexpected server-side error occurred.