SetFolderRules API¶

Sets the rules (policies) for the specified folder using an XML rules definition. Rules control allowed file types, checkout/checkin policies, document and folder deletion permissions, and other folder behaviors. Optionally applies the rules to the entire subfolder tree.

Endpoint¶

/srv.asmx/SetFolderRules

Methods¶

• GET /srv.asmx/SetFolderRules?authenticationTicket=...&Path=...&xmlRules=...&ApplyToTree=...
• POST /srv.asmx/SetFolderRules (form data)
• SOAP Action: http://tempuri.org/SetFolderRules

Parameters¶

xmlRules Format¶

The xmlRules parameter must be a valid XML string with <Rules> as the root element and <Rule> child elements, each with Name and Value attributes.

<Rules>
  <Rule Name="ALLOWABLEFILETYPES" Value="*" />
  <Rule Name="NEWFOLDERS" Value="allows" />
  <Rule Name="FOLDERDELETES" Value="allows" />
  <Rule Name="CHECKOUTS" Value="allows" />
  <Rule Name="CHECKINS" Value="allows" />
  <Rule Name="DOCUMENTDELETES" Value="allows" />
  <Rule Name="NEWDOCUMENTS" Value="allows" />
  <Rule Name="CLASSIFIEDDOCUMENTS" Value="allows" />
  <Rule Name="AUTOPROMPTPROPERTYSETNAME" Value="" />
</Rules>

Available Rule Names and Values¶

Note: Rule names are case-insensitive, but values are not: only the exact lower-case word disallows disallows an action. DISALLOWS or Disallows reads as allows. Only rules present in xmlRules are updated; omitted rules retain their current values, and a rule name the server does not know is ignored without an error.

Response¶

Success Response¶

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

Error Response¶

<response success="false" error="Target folder cannot be found" errorcode="4041" />

Required Permissions¶

The calling user must have folder manager or domain manager rights to modify folder rules.

Example¶

POST Request (restrict to PDF only, disallow deletions)¶

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&Path=/Finance/Reports
&xmlRules=<Rules><Rule Name="ALLOWABLEFILETYPES" Value=".pdf"/><Rule Name="DOCUMENTDELETES" Value="disallows"/></Rules>
&ApplyToTree=false

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:SetFolderRules>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:Path>/Finance/Reports</tns:Path>
      <tns:xmlRules><![CDATA[<Rules><Rule Name="ALLOWABLEFILETYPES" Value=".pdf"/></Rules>]]></tns:xmlRules>
      <tns:ApplyToTree>false</tns:ApplyToTree>
    </tns:SetFolderRules>
  </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 folder rules. Only the rules named in xmlRules are changed; the rest keep their values, so this is a partial update and <Rules /> is a valid no-op.

await call('SetFolderRules', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports',
  xmlRules:
    '<Rules>' +
      '<Rule Name="Checkouts" Value="disallows" />' +
      '<Rule Name="AllowableFileTypes" Value="pdf,docx" />' +
    '</Rules>',
  ApplyToTree: false
});

ApplyToTree=true writes the same rules down the whole subtree, not just the folder named. AllowableFileTypes comes back from GetFolderRules upper case, without dots and in alphabetical order, so pdf,docx reads back as DOCX,PDF.

A value it cannot use is accepted and ignored. <Rule Name="Checkins" Value="perhaps" /> is answered success="true" and the rule keeps the value it had. Nothing reports the mistake, so read the rules back if it matters. A Name the operation does not recognise is ignored the same way. This is unlike SetFolderAIPreferences, which refuses an unusable value with 4000 and names the ones it takes.

Notes¶

• Rule names are case-insensitive; values are not. Only the exact word disallows disallows.
• Only the rules present in xmlRules are updated; rules not mentioned retain their current values. An unknown rule name is ignored.
• Setting ApplyToTree=true recursively applies the specified rules to all subfolders.
• Use GetFolderRules to read the current rules first. It returns every rule in the form this API takes, so a caller can read them, change one and write them all back.
• A property set name that matches no property set is ignored, and the call still reports success: the folder keeps the property set it prompted for before. Check the name with GetPropertySetDefinitions first.
• ALLOWABLEFILETYPES values are tidied up before they are stored: dots and spaces are dropped and the extensions are upper-cased and sorted, so .pdf , docx comes back from GetFolderRules as DOCX,PDF.
• Rules are enforced from the moment they are written: with NEWFOLDERS set to disallows, CreateFolder in that folder is refused.

Related APIs¶

• GetFolderRules - Retrieve the current rules for a folder
• GetFolder - Get folder properties including rules (when WithRules=true)

Error Codes¶

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

Sending xmlRules that is not well-formed answers with the error above. Older servers answered it with HTTP 500 and a stack trace.