SetFolderRandDSchedule API¶

Assigns a Retention and Disposition (R&D) schedule to a folder identified by path. Optionally also assigns the schedule to all subfolders and/or all documents within the folder hierarchy.

Endpoint¶

/srv.asmx/SetFolderRandDSchedule

Methods¶

• GET /srv.asmx/SetFolderRandDSchedule?authenticationTicket=...&Path=...&RDDefId=...&includeFolders=...&includeDocuments=...
• POST /srv.asmx/SetFolderRandDSchedule (form data)
• SOAP Action: http://tempuri.org/SetFolderRandDSchedule

Parameters¶

Response¶

Success Response¶

<response success="true" />

Error Response¶

<response success="false" error="[901]Session expired or Invalid ticket" />

Required Permissions¶

Either the change retention period right on the folder, or membership of [R&D Managers], which stands in for the right on any folder. Defining schedules themselves is for R&D Managers only. Up to 8.7 the role did not count; the right was required. Each document under it is checked the same way; one the caller may not change is reported in the response and left as it was.

Example¶

GET Request -" assign to folder only¶

GET /srv.asmx/SetFolderRandDSchedule
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &Path=/Finance/Reports
    &RDDefId=47
    &includeFolders=false
    &includeDocuments=false
HTTP/1.1
Host: yourserver

GET Request -" assign to entire folder tree including documents¶

GET /srv.asmx/SetFolderRandDSchedule
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &Path=/Finance/Reports
    &RDDefId=47
    &includeFolders=true
    &includeDocuments=true
HTTP/1.1
Host: yourserver

POST Request¶

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

authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&Path=/Finance/Reports&RDDefId=47&includeFolders=true&includeDocuments=true

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;
}

Puts a schedule on a folder, and optionally on what is inside it.

await call('SetFolderRandDSchedule', {
  authenticationTicket: ticket,
  Path: '/Finance/Invoices',
  RDDefId: 18706,
  includeFolders: true,      // the subfolders, recursively
  includeDocuments: true     // the documents in them
});

With both flags false only the folder itself is touched. The answer wraps its log in a <Value> element, where the document form answers a bare success.

Notes¶

• Assigning a schedule to a folder triggers the calculation of retention and disposition dates for all affected folders and documents. Only the dates change in this call: open disposition tasks and disposition-status flags for this schedule are cleared. Items whose new disposition date is already past are picked up by the daily disposition job (up to about 24 hours later), which then creates the task or flag. Nothing is disposed by this call.
• If a folder or document already has a schedule assigned, it is replaced with the new one.
• To remove a schedule from a folder hierarchy, use RemoveFolderRandDSchedule.
• To assign a schedule to a single document, use SetDocumentRandDSchedule.

Related APIs¶

• GetFolderRandDSchedule -" Get the R&D schedule currently assigned to a folder.
• RemoveFolderRandDSchedule -" Remove the R&D schedule from a folder hierarchy.
• SetDocumentRandDSchedule -" Assign a schedule to a single document.
• GetRandDSchedules -" List all R&D schedule definitions with their IDs.
• CreateRandDSchedule -" Create a new R&D schedule definition.

Error Codes¶

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