UpdateRandDSchedule API¶

Updates an existing Retention and Disposition (R&D) schedule definition. Optionally recalculates retention and disposition dates for all documents and folders currently using this schedule.

Endpoint¶

/srv.asmx/UpdateRandDSchedule

Methods¶

• GET /srv.asmx/UpdateRandDSchedule?authenticationTicket=...&RDdefId=...&ApplyToExistingDocumentFolders=...&NewRDDefXML=...
• POST /srv.asmx/UpdateRandDSchedule (form data)
• SOAP Action: http://tempuri.org/UpdateRandDSchedule

Parameters¶

NewRDDefXML Format¶

The XML must have a root element (element name is not significant) with the following attributes:

Response¶

Success Response¶

<response success="true" />

Error Response¶

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

Required Permissions¶

Retention & Disposition Manager or System Administrator. Regular users receive an access denied error.

Example¶

GET Request¶

GET /srv.asmx/UpdateRandDSchedule
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &RDdefId=47
    &ApplyToExistingDocumentFolders=true
    &NewRDDefXML=<RDSchedule+Name="10-Year+Finance"+.../>
HTTP/1.1
Host: yourserver

POST Request¶

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

authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&RDdefId=47&ApplyToExistingDocumentFolders=true&NewRDDefXML=<RDSchedule Name="10-Year Finance" Description="Updated to 10yr" RetentionType="2" RetentionTrigger="1" RetentionPeriodYears="10" RetentionPeriodMonths="0" RetentionPeriodDays="0" DispositionType="1" DispositionTrigger="3" DispositionPeriodYears="0" DispositionPeriodMonths="0" DispositionPeriodDays="0" CreateTask="true" SendEmail="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;
}

Rewrites a schedule in place, keeping its id. NewRDDefXML takes exactly the document CreateRandDSchedule describes and runs the same validation.

await call('UpdateRandDSchedule', {
  authenticationTicket: ticket,
  RDdefId: 18706,
  ApplyToExistingDocumentFolders: true,   // recompute the dates on everything already carrying it
  NewRDDefXML: `
    <RetentionDispositionSchedule
        Name="Seven year retention"
        Description="Keep for seven years, then destroy"
        RetentionType="1" RetentionTrigger="2" RetentionPeriodYears="7"
        DispositionType="1" DispositionTrigger="3" DispositionPeriodDays="1" />`
});

The id survives, and the schedule records who made the change - GetRandDScheduleInfo answers LastUpdatedByName and LastUpdatedOn, which a schedule that has never been updated leaves empty.

Notes¶

• Maximum lengths of the text attributes of RDDefXML: Name 128, Description 255, URL 255, ReferenceNumber 20, SourceAuthority 64, RecordsSeriesName 100, TransferAgency 100 characters. A longer value is refused with 4000.
• When ApplyToExistingDocumentFolders = true, all documents and folders currently assigned this schedule have their retention end dates and disposition dates recalculated immediately. 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. For large organizations with many affected objects this operation may take some time.
• When ApplyToExistingDocumentFolders = false, existing dates are left unchanged; only the schedule definition itself is updated.
• Changes that trigger recalculation include: RetentionType, RetentionTrigger, any RetentionPeriod values, DispositionType, DispositionTrigger, any DispositionPeriod values, and MoveFolderId.
• CreateTask and SendEmail are only meaningful when DispositionType > 0. When DispositionType = 0 (None), both are automatically forced to false regardless of the values supplied.
• If CreateTask or SendEmail are omitted from the XML, they default to true (and will then be subject to the DispositionType rule above).
• To get the schedule ID, call GetRandDSchedules.
• To view the full schedule definition before updating, call GetRandDScheduleInfo.

Related APIs¶

• CreateRandDSchedule -" Create a new R&D schedule definition.
• DeleteRandDSchedule -" Delete an R&D schedule definition.
• GetRandDSchedules -" List all R&D schedule definitions.
• GetRandDScheduleInfo -" Get full details of a specific schedule.

Error Codes¶

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