UpdateDocumentProperties1 API¶

Updates the core properties of the specified document: display name, description, update instructions, source, language, and author. All fields are optional -" only the fields provided are updated. This is an extended version of UpdateDocumentProperties that adds source, language, and author fields. To also update importance, use UpdateDocumentProperties2.

Endpoint¶

/srv.asmx/UpdateDocumentProperties1

Methods¶

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

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. Pass `null` or omit to leave unchanged. Maximum 128 characters.
`newDescription`	string	No	New description for the document. Line endings are normalized automatically. Maximum 4000 characters; a longer value is refused with `4000`.
`newUpdateInstructions`	string	No	New update instructions for contributors. Line endings are normalized automatically. Maximum 4000 characters; a longer value is refused with `4000`.
`newDocumentSource`	string	No	New source value (e.g. originating organization, system, or URL). Line endings are normalized automatically. Maximum 50 characters; a longer value is refused with `4000`.
`newDocumentLanguage`	string	No	New language tag for the document (e.g. `en`, `en-US`, `fr`). Line endings are normalized automatically. Maximum 20 characters; a longer value is refused with `4000`.
`newDocumentAuthor`	string	No	New author name for the document. Line endings are normalized automatically. Maximum 50 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/UpdateDocumentProperties1
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &path=/Finance/Reports/Q1-2024-Report.pdf
  &newDocumentName=Q1+2024+Financial+Report
  &newDescription=Quarterly+financial+summary
  &newUpdateInstructions=Update+quarterly
  &newDocumentSource=Finance+Department
  &newDocumentLanguage=en-US
  &newDocumentAuthor=Jane+Smith
HTTP/1.1

POST Request¶

POST /srv.asmx/UpdateDocumentProperties1 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
&newUpdateInstructions=Update quarterly
&newDocumentSource=Finance Department
&newDocumentLanguage=en-US
&newDocumentAuthor=Jane Smith

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:UpdateDocumentProperties1>
      <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</tns:newDescription>
      <tns:newUpdateInstructions>Update quarterly</tns:newUpdateInstructions>
      <tns:newDocumentSource>Finance Department</tns:newDocumentSource>
      <tns:newDocumentLanguage>en-US</tns:newDocumentLanguage>
      <tns:newDocumentAuthor>Jane Smith</tns:newDocumentAuthor>
    </tns:UpdateDocumentProperties1>
  </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;
}

UpdateDocumentProperties with three more fields: the document's source, its language and its author.

await call('UpdateDocumentProperties1', {
  authenticationTicket: ticket,
  Path: path,
  NewDocumentName: 'Q1.pdf',
  NewDescription: 'Quarterly results',
  NewUpdateInstructions: '',
  NewDocumentSource: 'Finance system export',
  NewDocumentLanguage: 'en',
  NewDocumentAuthor: 'J Smith'
});

They read back from GetDocument as Source, Language and Author.

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 on the document.
Line endings in text fields are normalized to the server format.
To also update the document importance level, use UpdateDocumentProperties2.
The base version UpdateDocumentProperties only updates name, description, and update instructions.

UpdateDocumentProperties - Update name, description, and update instructions only
UpdateDocumentProperties2 - Update all properties including 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.