CreateRandDSchedule API¶

Creates a new Retention and Disposition (R&D) schedule definition. Once created, the schedule can be assigned to documents and folders via SetDocumentRandDSchedule and SetFolderRandDSchedule.

Endpoint¶

/srv.asmx/CreateRandDSchedule

Methods¶

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

Parameters¶

RDDefXML Format¶

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

Example XML:

<RDSchedule
  Name="Standard 7-Year Retention"
  Description="Retain documents for 7 years then destroy"
  ReferenceNumber="FIN-001"
  SourceAuthority="IRS"
  RetentionType="2"
  RetentionTrigger="1"
  RetentionPeriodYears="7"
  RetentionPeriodMonths="0"
  RetentionPeriodDays="0"
  DispositionType="1"
  DispositionTrigger="3"
  DispositionPeriodYears="0"
  DispositionPeriodMonths="0"
  DispositionPeriodDays="0"
  TransferAgency=""
  MoveFolderId="0"
  CreateTask="true"
  SendEmail="true"
/>

Response¶

Success Response¶

<response success="true">
  <RetentionDispositionSchedule DefId="47" />
</response>

• DefId: Auto-generated integer ID of the new schedule definition. Use this value when assigning the schedule to documents or folders.

Error Response¶

<response success="false" error="[error message]" />

Required Permissions¶

Any authenticated user. Anonymous access is not allowed.

Example¶

GET Request¶

GET /srv.asmx/CreateRandDSchedule
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &RDDefXML=<RDSchedule+Name="7-Year+Finance"+Description="Finance+documents+7yr".../>
HTTP/1.1
Host: yourserver

POST Request¶

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

authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&RDDefXML=<RDSchedule Name="7-Year Finance" Description="Finance documents 7yr" RetentionType="2" RetentionTrigger="1" RetentionPeriodYears="7" RetentionPeriodMonths="0" RetentionPeriodDays="0" DispositionType="1" DispositionTrigger="3" DispositionPeriodYears="0" DispositionPeriodMonths="0" DispositionPeriodDays="0"/>

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

Creates a schedule. Every value is an attribute of the root element, and the element's own name is never looked at.

const definition = `
<RetentionDispositionSchedule
    Name="Seven year retention"
    Description="Keep for seven years, then destroy"
    ReferenceNumber="FIN-001"
    SourceAuthority="IRS"
    RecordsSeriesName="Finance"
    RetentionType="1"          <!-- 1 is Temporary, 2 is Permanent -->
    RetentionTrigger="1"       <!-- 1 On create, 2 On cut off -->
    RetentionPeriodYears="7"
    DispositionType="1"        <!-- 1 Final disposition, 2 Transfer -->
    DispositionTrigger="3"     <!-- must be 3, On retention end, when retention is Temporary -->
    DispositionPeriodDays="1"
    CreateTask="false"
    SendEmail="false" />`;

const root = await call('CreateRandDSchedule', {
  authenticationTicket: ticket, RDDefXML: definition
});

const defId = root.querySelector('RetentionDispositionSchedule').getAttribute('DefId');

The rules the server enforces, in the order it checks them:

• Name and Description are both required. The name is at most 128 characters and takes letters, digits, _, -, ., ,, (, ) and spaces only.
• RetentionType and DispositionType cannot both be 0.
• Temporary retention (RetentionType="1") needs RetentionTrigger of 1 or 2 - 0, the default, is refused - and at least one of the three retention periods above zero.
• Permanent retention (RetentionType="2") forces the trigger and all three periods to zero, and refuses a disposition: a retention that never ends has nothing for a disposition to be triggered by. Until 9.0 the whole disposition half of the document was zeroed in silence and the call still reported success, so a caller who asked for one was never told it had gone away.
• A disposition needs at least one of its three periods above zero.
• DispositionTrigger="3", on retention end, needs a retention type other than 0.
• With Temporary retention and any disposition, DispositionTrigger must be 3. The refusal names the rule: "When 'Temporary retention' is selected, the required disposition trigger is 'Upon retention end'." It used to quote a stray minutes abbreviation instead.

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.
• RetentionType is 0 none, 1 temporary and 2 permanent - these two notes had the names the wrong way round until 9.0.
• When RetentionType = 2 (permanent), all period values are automatically reset to 0 and RetentionTrigger is set to On Create, and a disposition is refused: see below.
• When RetentionType = 1 (temporary), at least one of RetentionPeriodYears, RetentionPeriodMonths, or RetentionPeriodDays must be greater than 0.
• 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).
• The returned DefId is needed for SetDocumentRandDSchedule, SetFolderRandDSchedule, GetRandDScheduleInfo, UpdateRandDSchedule, and DeleteRandDSchedule.

Related APIs¶

• GetRandDSchedules -" List all defined R&D schedule definitions.
• GetRandDScheduleInfo -" Get full details of a specific schedule.
• UpdateRandDSchedule -" Update an existing schedule definition.
• DeleteRandDSchedule -" Delete a schedule definition.
• SetDocumentRandDSchedule -" Assign a schedule to a document.
• SetFolderRandDSchedule -" Assign a schedule to a folder.

Error Codes¶

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