UpdateFolderProperties API¶

Updates the name and/or description of the specified folder. The folder itself must already exist; only its metadata is changed.

Endpoint¶

/srv.asmx/UpdateFolderProperties

Methods¶

• GET /srv.asmx/UpdateFolderProperties?authenticationTicket=...&Path=...&NewFolderName=...&NewDescription=...
• POST /srv.asmx/UpdateFolderProperties (form data)
• SOAP Action: http://tempuri.org/UpdateFolderProperties

Parameters¶

Response¶

Success Response¶

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

Error Response¶

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

Required Permissions¶

The calling user must have write (modify) permission on the folder.

Example¶

GET Request¶

GET /srv.asmx/UpdateFolderProperties
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &Path=/Finance/Reports
  &NewFolderName=Financial Reports
  &NewDescription=All financial reports including quarterly and annual summaries
HTTP/1.1

POST Request¶

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&Path=/Finance/Reports
&NewFolderName=Financial Reports
&NewDescription=All financial reports including quarterly and annual summaries

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:UpdateFolderProperties>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:Path>/Finance/Reports</tns:Path>
      <tns:NewFolderName>Financial Reports</tns:NewFolderName>
      <tns:NewDescription>All financial reports including quarterly and annual summaries</tns:NewDescription>
    </tns:UpdateFolderProperties>
  </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 folder and sets its description. Leave NewDescription out to keep the description the folder has; send it empty to clear it. To change only the name, Rename is the simpler call.

// Change the name only: the description is kept.
await call('UpdateFolderProperties', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports',
  NewFolderName: 'Quarterly Reports'
});

It refuses a name that CreateFolder1 would have cleaned up. Creating a folder called Q3* silently produces Q3_; renaming an existing folder to Q3* is answered 4000 with a message naming the characters a folder may not carry. The two disagree, so a client that creates and renames with the same name-building code will find one path works and the other does not.

An empty NewFolderName, or one of nothing but spaces, is refused by model binding with HTTP 400. NewDescription sent empty clears the description; left out, it keeps it. (Before 9.0 leaving it out cleared it as well.)

Notes¶

• Renaming a folder changes the folder's path. Any references to the old path will need to be updated.
• The folder name is sanitized: carriage returns and line feeds are stripped.
• The description supports multi-line text; line ending characters are normalized.
• To change folder rules, use SetFolderRules.

Related APIs¶

• GetFolder - Retrieve current folder name and description
• SetFolderRules - Update folder behavior rules
• CreateFolder - Create a new folder

Error Codes¶

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