diff --git a/amps/ags/rm-community/rm-community-rest-api-explorer/src/main/webapp/definitions/gs-core-api.yaml b/amps/ags/rm-community/rm-community-rest-api-explorer/src/main/webapp/definitions/gs-core-api.yaml index 41c728fc7e..6ab10c5079 100644 --- a/amps/ags/rm-community/rm-community-rest-api-explorer/src/main/webapp/definitions/gs-core-api.yaml +++ b/amps/ags/rm-community/rm-community-rest-api-explorer/src/main/webapp/definitions/gs-core-api.yaml @@ -40,6 +40,8 @@ tags: description: Retrieve and manage unfiled record folders - name: holds description: Retrieve and manage holds + - name: retention-schedules + description: Perform retention schedule specific operations paths: ## GS sites @@ -2634,7 +2636,194 @@ paths: description: Unexpected error schema: $ref: '#/definitions/Error' + ##retention-schedule + '/record-categories/{recordCategoryId}/retention-schedules': + post: + tags: + - retention-schedules + summary: Create a retention schedule + description: | + Create a retention schedule. + + For example, using the following JSON body will create a retention schedule: + ```JSON + { + "authority": "Retention Authority", + "instructions": "Retention Instructions", + "isRecordLevel": false + } + ``` + operationId: createRetentionSchedule + parameters: + - $ref: '#/parameters/recordCategoryIdParam' + - in: body + name: retentionNodeBodyCreate + description: | + The retention schedule information to create. + schema: + $ref: '#/definitions/RetentionNodeBodyCreate' + consumes: + - application/json + produces: + - application/json + responses: + '201': + description: Successful response + schema: + $ref: '#/definitions/RetentionScheduleResponse' + '400': + description: | + Invalid parameter: value of recordCategoryId is invalid + '401': + description: Authentication failed + '403': + description: Current user does not have permission to create retention schedule + '404': + description: recordCategoryId does not exist + '409': + description: Retention schedule already exist for the given recordCategoryId + default: + description: Unexpected error + schema: + $ref: '#/definitions/Error' + get: + tags: + - retention-schedules + summary: Get the retention schedule for a record category + description: | + Get the retention schedule for a record category. + + You can use the **include** parameter (include=actions) to return additional information. + + operationId: getRetentionScheduleList + parameters: + - $ref: '#/parameters/recordCategoryIdParam' + - $ref: '#/parameters/retentionScheduleIncludeParam' + - $ref: '#/parameters/skipCountParam' + - $ref: '#/parameters/maxItemsParam' + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: Successful response + schema: + $ref: '#/definitions/RetentionScheduleResponseList' + '400': + description: | + Invalid parameter: value of recordCategoryId is invalid + '401': + description: Authentication failed + '403': + description: Current user does not have permission to get retention schedule + '404': + description: recordCategoryId does not exist + default: + description: Unexpected error + schema: + $ref: '#/definitions/Error' + '/retention-schedules/{retentionScheduleId}/retention-steps': + post: + tags: + - retention-schedules + summary: Create a step in the retention schedule + description: | + Create a step in the retention schedule. + + Order of steps: + * "**retain**" or "**cutoff**" should be first + * can't use "**cutoff**" after "**transfer**" or "**accession**" + * only the "**transfer**" action is allowed multiple times + * no steps are allowed after "**destroy**" + + For example, the following JSON body will create a step in the retention schedule: + ```JSON + { + "name":"accession", + "periodAmount": 2, + "period":"month", + "periodProperty":"cm:created", + "combineDispositionStepConditions": false, + "events":["versioned"], + "eligibleOnFirstCompleteEvent": true, + "description":"Step Description" + } + ``` + operationId: createRetentionScheduleAction + parameters: + - $ref: '#/parameters/retentionScheduleIdParam' + - in: body + name: nodeBodyCreate + description: | + The retention schedule steps information to create. + required: true + schema: + $ref: '#/definitions/RetentionStepNodeBodyCreate' + consumes: + - application/json + produces: + - application/json + responses: + '201': + description: Successful response + schema: + $ref: '#/definitions/RetentionStepNodeBodyResponse' + '400': + description: | + Invalid parameter: value of retentionScheduleId is invalid + Invalid parameter (e.g. event, period, periodProperty) + '401': + description: Authentication failed + '403': + description: Current user does not have permission to create retention schedule step + '404': + description: retentionScheduleId does not exist + '409': + description: | + * Invalid Step - Can't use Cut Off after Transfer or Accession + * Invalid Step - Destroy action already completed. Can't do any other Action + * Invalid Step - This step already exists. You can’t create this step [Transfer action is allowed many times] + '422': + description: Cut Off or Retain should be the first step + default: + description: Unexpected error + schema: + $ref: '#/definitions/Error' + get: + tags: + - retention-schedules + summary: Get the list of steps in the retention schedule + description: | + Get the list of steps in the retention schedule. + operationId: getRetentionScheduleActionList + parameters: + - $ref: '#/parameters/retentionScheduleIdParam' + - $ref: '#/parameters/skipCountParam' + - $ref: '#/parameters/maxItemsParam' + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: Successful response + schema: + $ref: '#/definitions/RetentionStepsNodeBodyResponse' + '400': + description: | + Invalid parameter: value of retentionScheduleId is invalid + '401': + description: Authentication failed + '403': + description: Current user does not have permission to get retention schedule steps + '404': + description: retentionScheduleId does not exist + default: + description: Unexpected error + schema: + $ref: '#/definitions/Error' parameters: ## File plans filePlanEntryIncludeParam: @@ -3100,6 +3289,22 @@ parameters: If true, then a name clash will cause an attempt to auto rename by finding a unique name using an integer suffix. required: false type: boolean + ## RetentionSchedule + retentionScheduleIdParam: + name: retentionScheduleId + in: path + description: + The identifier of a retention schedule. + required: true + type: string + retentionScheduleIncludeParam: + name: include + in: query + description: | + Returns additional information about the retention schedule actions. Any optional field from the response model can be requested. For example: + * actions + required: false + type: string definitions: FilePlanComponentBodyUpdate: type: object @@ -4258,6 +4463,225 @@ definitions: type: array items: $ref: '#/definitions/HoldBulkStatusEntry' + RetentionNodeBodyCreate: + type: object + properties: + authority: + type: string + description: | + Authority name for the retention schedule. + instructions: + type: string + description: | + Required instructions for the retention schedule. + isRecordLevel: + type: boolean + default: false + description: | + This field is used to specify whether the retention schedule needs to be applied in the folder level or record level. + True will cause the the retention schedule to apply to records and false will cause the retention schedule to apply to record folders. + This cannot be changed once items start being managed by the retention schedule. + RetentionScheduleResponse: + type: object + properties: + id: + type: string + parentId: + type: string + authority: + type: string + instructions: + type: string + isRecordLevel: + type: boolean + unpublishedUpdates: + type: boolean + RetentionScheduleResponseList: + type: object + properties: + list: + type: object + properties: + pagination: + $ref: '#/definitions/Pagination' + entries: + type: array + items: + $ref: '#/definitions/FullRetentionScheduleResponse' + FullRetentionScheduleResponse: + type: object + properties: + id: + type: string + parentId: + type: string + authority: + type: string + instructions: + type: string + isRecordLevel: + type: boolean + unpublishedUpdates: + type: boolean + actions: + type: array + items: + $ref: '#/definitions/Actions' + Actions: + type: object + properties: + id: + type: string + name: + type: string + periodAmount: + type: integer + period: + type: string + periodProperty: + type: string + combineDispositionStepConditions: + type: boolean + default: false + eligibleOnFirstCompleteEvent: + type: boolean + default: true + description: + type: string + retainRecordMetadataAfterDestruction: + type: boolean + location: + type: string + events: + type: array + items: + type: string + index: + type: integer + RetentionStepNodeBodyCreate: + type: object + properties: + name: + type: string + description: | + The valid names are: + * retain + * cutoff + * accession + * transfer + * destroy + periodAmount: + type: integer + description: | + This property is only applicable for the following period values. + * day + * month + * quarter + * week + * duration + * year + period: + type: string + description: | + Valid values for the period. + * day = Day + * fmend = End Of Financial Month + * fqend = End Of Financial Quarter + * fyend = End Of Financial Year + * immediately = Immediately + * monthend = End Of Month + * quarterend = End Of Quarter + * yearend = End Of Year + * month = Month + * none = None + * quarter = Quarter + * week = Week + * duration = XML Duration + * year = Year + + If you provide XML Duration for the period value, you need to specify a time interval using XML syntax. + The syntax should take the form of: + P = Period (required) + nY = Number of years + nM = Number of months + nD = Number of days + T = Start time of a time section (required if specifying hours, minutes, or seconds) + nH = Number of hours + nM = Number of minutes + nS = Number of seconds + For example, ‘P2M10D’ represents two months and ten days. + periodProperty: + type: string + default: cm:created + description: | + Valid values for the periodProperty property + * cm:created = Created Date (defult value) + * rma:cutOffDate = Cut Off Date + * rma:dispositionAsOf = Retention Action + combineDispositionStepConditions: + type: boolean + description: | + This property is only valid for **accession** step. + This is used to specify whether to combine the period condition and events for the step execution or only consider one of them. + For example: + **periodCondition**: After a period of 2 months + **eventsCondition**: Case Closed event + This flag can be used to consider only (**periodCondition** or **eventsCondition**) or both of them at once. + events: + type: array + items: + type: string + description: | + Valid values for the events property + * case_closed = Case Closed + * abolished = Abolished + * re_designated = Redesignated + * no_longer_needed = No Longer Needed + * superseded = Superseded + * versioned = Versioned + * study_complete = Study Complete + * training_complete = Training Complete + * related_record_trasfered_inactive_storage = Related Record Transferred to Inactive Storage + * obsolete = Obsolete + * all_allowances_granted_are_terminated = All Allowances Granted are Terminated + * WGI_action_complete = WGI Action Complete + * separation = Separation + * case_complete = Case Complete + * declassification_review = Declassification Review + eligibleOnFirstCompleteEvent: + type: boolean + description: | + * false = When all events have happened + * true = Whichever event is earlier + description: + type: string + description: | + This property is used to provide the step description. + retainRecordMetadataAfterDestruction: + type: boolean + description: | + This property is used to retain the metadata after record destruction. + location: + type: string + description: | + This property is only valid for transfer step + RetentionStepNodeBodyResponse: + type: object + properties: + actions: + $ref: '#/definitions/Actions' + RetentionStepsNodeBodyResponse: + type: object + properties: + list: + type: object + properties: + pagination: + $ref: '#/definitions/Pagination' + entries: + type: array + items: + $ref: '#/definitions/RetentionStepNodeBodyResponse' ## RequestBodyFile: type: object