SetDocumentRandDSchedule API¶

Assigns a Retention and Disposition (R&D) schedule to a document identified by path. The schedule controls how long the document must be retained and what happens when the retention period expires.

Endpoint¶

/srv.asmx/SetDocumentRandDSchedule

Methods¶

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

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 document, or membership of [R&D Managers], which stands in for the right on any document. Defining schedules themselves is for R&D Managers only. Up to 8.7 a schedule other than the folder's needed the right and the role.

Example¶

GET Request¶

GET /srv.asmx/SetDocumentRandDSchedule
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &Path=/Finance/Reports/Q1-2024.pdf
    &RDDefId=47
HTTP/1.1
Host: yourserver

POST Request¶

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

authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&Path=/Finance/Reports/Q1-2024.pdf&RDDefId=47

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 document, replacing whatever was there.

await call('SetDocumentRandDSchedule', {
  authenticationTicket: ticket,
  Path: '/Finance/Invoices/inv-1001.pdf',
  RDDefId: 18706
});

RDDefId="0" takes the schedule off, which is exactly what RemoveDocumentRandDSchedule sends internally. Any other id that no schedule has is refused 4041.

The retention and disposition dates are computed from the schedule when it is applied. A schedule triggered on create dates from the document's creation date; one triggered on cut off computes nothing until the item has a cut-off date.

Notes¶

• Assigning a schedule triggers the calculation of the document's retention end date and disposition date based on the schedule settings and the document's creation date or cutoff date. 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 the document already has a schedule assigned, it is replaced with the new one.
• To remove a schedule from a document without replacing it, use RemoveDocumentRandDSchedule.
• To assign a schedule to an entire folder hierarchy, use SetFolderRandDSchedule.

Related APIs¶

• GetDocumentRandDSchedule -" Get the R&D schedule currently assigned to a document.
• RemoveDocumentRandDSchedule -" Remove the R&D schedule from a document.
• SetFolderRandDSchedule -" Assign a schedule to a folder hierarchy.
• 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: