apidocs

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

Parameter	Type	Required	Description
`authenticationTicket`	string	Yes	Authentication ticket obtained from `AuthenticateUser`.
`RDDefXML`	string	Yes	XML string defining the schedule. See format below.

`RDDefXML` Format

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

Attribute	Type	Max Length	Required	Description
`Name`	string	128	Yes	Schedule name.
`Description`	string	255	Yes	Schedule description.
`URL`	string	255	No	External documentation URL.
`ReferenceNumber`	string	20	No	Regulatory reference or citation number.
`SourceAuthority`	string	64	No	Name of the regulatory authority (e.g., `NARA`).
`RecordsSeriesName`	string	100	No	Records series name.
`RetentionType`	int	-“	Yes	`0` = None, `1` = Permanent, `2` = Temporary.
`RetentionTrigger`	int	-“	Yes for Temporary	`0` = Custom Date Entry, `1` = On Create, `2` = On Cutoff. Required when `RetentionType=2`.
`RetentionPeriodYears`	int	-“	Yes for Temporary	Years to retain. Must be > 0 combined with months/days when `RetentionType=2`.
`RetentionPeriodMonths`	int	-“	Yes for Temporary	Additional months to retain.
`RetentionPeriodDays`	int	-“	Yes for Temporary	Additional days to retain.
`DispositionType`	int	-“	Yes	`0` = None, `1` = Final Disposition, `2` = Transfer to External Agency.
`DispositionTrigger`	int	-“	Yes if DispositionType > 0	`0` = Custom Date Entry, `1` = On Create, `2` = On Cutoff, `3` = On Retention End.
`DispositionPeriodYears`	int	-“	No	Years after retention trigger.
`DispositionPeriodMonths`	int	-“	No	Additional months.
`DispositionPeriodDays`	int	-“	No	Additional days.
`TransferAgency`	string	100	Yes if DispositionType=2	Agency name for the transfer destination.
`MoveFolderId`	int	-“	No	Folder ID for transfer destination folder.
`CreateTask`	boolean	-“	No	`true` to create a workflow task when disposition is triggered. Defaults to `true` if omitted; automatically forced to `false` when `DispositionType=0`.
`SendEmail`	boolean	-“	No	`true` to send an email notification when disposition is triggered. Defaults to `true` if omitted; automatically forced to `false` when `DispositionType=0`.

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

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

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

Error Response

<root 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"/>

Notes

When RetentionType = 1 (Permanent), all period values are automatically reset to 0 and RetentionTrigger is set to On Create.
When RetentionType = 2 (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.

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

Error	Description
`[900]`	Authentication failed -“ invalid credentials.
`[901]`	Session expired or invalid authentication ticket.
Invalid XML	The `RDDefXML` is malformed or missing required attributes.
Invalid retention period	`RetentionType=2` but no period values > 0.
Missing transfer agency	`DispositionType=2` but `TransferAgency` is empty.