Skip to content

Commit b4e768b

Browse files
arjankowskiarjankowski
authored
docs: Add documentation for retention policy (#888)
1 parent b668888 commit b4e768b

File tree

1 file changed

+325
-0
lines changed

1 file changed

+325
-0
lines changed

‎docs/usage/retention-policies.md‎

Lines changed: 325 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,325 @@
1+
Retention Policies
2+
======
3+
4+
A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console.
5+
6+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
7+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
8+
9+
10+
- [Create Retention Policy](#create-retention-policy)
11+
- [Update Retention Policy](#update-retention-policy)
12+
- [Get Retention Policy](#get-retention-policy)
13+
- [Get Retention Policies](#get-retention-policies)
14+
- [Create Retention Policy Assignment](#create-retention-policy-assignment)
15+
- [Get Retention Policy Assignment](#get-retention-policy-assignment)
16+
- [Get Retention Policy Assignments](#get-retention-policy-assignments)
17+
- [Delete Retention Policy Assignment](#delete-retention-policy-assignment)
18+
- [Get File Version Retention](#get-file-version-retention)
19+
- [Get File Version Retentions](#get-file-version-retentions) (will be deprecated in the future, use [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) and [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) instead)
20+
- [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment)
21+
- [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment)
22+
23+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
24+
25+
26+
## Create Retention Policy
27+
28+
To create a retention policy, call
29+
[`client.retentionPolicy.create(name:type:length:dispositionAction:canOwnerExtendRetention:areOwnersNotified:customNotificationRecipients:retentionType:completion:)`][create-retention-policy].
30+
31+
You can create either a `indefinite` retention policy, or a `finite`.
32+
To create a `indefinite` retention policy, you must set a `type` to `.indefinite` and a `dispositionAction` to `.removeRetention`.
33+
34+
<!-- sample post_retention_policies -->
35+
```swift
36+
client.retentionPolicy.create(
37+
name: "Test Indefinite Policy Name",
38+
type: .indefinite,
39+
dispositionAction: .removeRetention
40+
) { result in
41+
guard case let .success(retentionPolicy) = result else {
42+
print("Error creating retention policy")
43+
return
44+
}
45+
46+
print("Retention policy: \(retentionPolicy.id) was created")
47+
}
48+
```
49+
50+
To create a `finite` retention policy, you must set `type` to `.finite`,
51+
set amount of time in days to apply the retention policy (`length`) and a `dispositionAction`.
52+
The disposition action can be `.permanentlyDelete` or `.removeRetention`.
53+
54+
```swift
55+
client.retentionPolicy.create(
56+
name: "Test Finite Policy Name",
57+
type: .finite,
58+
length: 60,
59+
dispositionAction: .permanentlyDelete
60+
) { result in
61+
guard case let .success(retentionPolicy) = result else {
62+
print("Error creating retention policy")
63+
return
64+
}
65+
66+
print("Retention policy: \(retentionPolicy.id) was created")
67+
}
68+
```
69+
70+
[create-retention-policy]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6create4name4type6length17dispositionAction014canOwnerExtendC017areOwnersNotified28customNotificationRecipients13retentionType10completionySS_AA0c6PolicyV0OSiSgAA011DispositionK0OSbSgASSayAA4UserCGSgAA0cV0OSgys6ResultOyAA0cX0CAA0A8SDKErrorCGctF
71+
72+
## Update Retention Policy
73+
74+
To update a retention policy, call
75+
[`client.retentionPolicy.update(policyId:name:dispositionAction:status:setRetentionTypeToNonModifiable:length:completion:)`][update-retention-policy].
76+
77+
<!-- sample put_retention_policies_id -->
78+
```swift
79+
client.retentionPolicy.update(policyId: "1234", name: "New Policy Name") { result in
80+
guard case let .success(retentionPolicy) = result else {
81+
print("Error updating a retention policy")
82+
return
83+
}
84+
85+
print("Updated retention policy: \(retentionPolicy.id)")
86+
}
87+
```
88+
89+
[update-retention-policy]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6update8policyId4name17dispositionAction6status03setC19TypeToNonModifiable6length10completionySS_SSSgAA011DispositionK0OSgAA0C12PolicyStatusOSgSbSiSgys6ResultOyAA0cU0CAA0A8SDKErrorCGctF
90+
91+
## Get Retention Policy
92+
93+
To retrieve information about a retention policy, call
94+
[`client.retentionPolicy.get(policyId:completion:)`][get-retention-policy] with the ID of the retention policy.
95+
96+
<!-- sample get_retention_policies_id -->
97+
```swift
98+
client.retentionPolicy.get(policyId: "1234") { result in
99+
guard case let .success(retentionPolicy) = result else {
100+
print("Error getting retention policy")
101+
return
102+
}
103+
104+
print("Retention policy: \(retentionPolicy.id)")
105+
}
106+
```
107+
108+
[get-retention-policy]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC3get8policyId10completionySS_ys6ResultOyAA0C6PolicyCAA0A8SDKErrorCGctF
109+
110+
## Get Retention Policies
111+
112+
To retrieve all retention policies for an enterprise, call
113+
[`client.retentionPolicy.list(name:type:createdByUserId:marker:limit:)`][get-retention-policies]. This method will return an iterator, which is used to get the policies. As you can see in the method signature, it is possible to specify filter for the name, type and created user of the retention policy. All of mentioned fields are optional and if not set, all retention policies will be returned. You can also set a number of items per single response by setting a limit.
114+
115+
<!-- sample get_retention_policies -->
116+
```swift
117+
let iterator = client.retentionPolicy.list(type: .indefinite)
118+
iterator.next { results in
119+
switch results {
120+
case let .success(page):
121+
for policy in page.entries {
122+
print("Retention policy \(policy.id)")
123+
}
124+
125+
case let .failure(error):
126+
print(error)
127+
}
128+
}
129+
```
130+
131+
[get-retention-policies]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC4list4name4type15createdByUserId6marker5limitAA14PagingIteratorCyAA0C11PolicyEntryCGSSSg_AA0cQ4TypeOSgA2OSiSgtF
132+
133+
## Create Retention Policy Assignment
134+
135+
To create new retention policy assignment call [`client.retentionPolicy.assign(policyId:assignedContentId:assignContentType:filterFields:completion:)`][create-assignment] method to assign the policy. Retention policy can be assigned to a specific folder, to a metadata template or to the entire enterprise.
136+
137+
<!-- sample post_retention_policy_assignments -->
138+
```swift
139+
client.retentionPolicy.assign(policyId: "12345", assignedContentId: "1111", assignContentType: .folder) { result in
140+
guard case let .success(retentionPolicyAssignment) = result else {
141+
print("Error creating retention policy assignment")
142+
return
143+
}
144+
145+
print("Retention policy assignment: \(retentionPolicyAssignment.id) was created")
146+
}
147+
```
148+
149+
[create-assignment]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6assign8policyId015assignedContentH00fJ4Type12filterFields10completionySS_SSAA0c20PolicyAssignmentItemK0OSayAA19MetadataFieldFilterVGSgys6ResultOyAA0coP0CAA0A8SDKErrorCGctF
150+
151+
## Get Retention Policy Assignment
152+
153+
To retrieve information about a retention policy assignment, call
154+
[`client.retentionPolicy.getAssignment(assignmentId:completion:)`][get-assignment] with the ID of the assignment.
155+
156+
<!-- sample get_retention_policy_assignments_id -->
157+
```swift
158+
client.retentionPolicy.getAssignment(assignmentId: "123456") { result in
159+
guard case let .success(retentionPolicyAssignment) = result else {
160+
print("Error getting retention policy assignment")
161+
return
162+
}
163+
164+
print("Retention policy assignment: \(retentionPolicyAssignment.id)")
165+
}
166+
```
167+
168+
[get-assignment]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC13getAssignment12assignmentId10completionySS_ys6ResultOyAA0c6PolicyG0CAA0A8SDKErrorCGctF
169+
170+
## Get Retention Policy Assignments
171+
172+
To get a list of all retention policy assignments associated with a specified retention policy, call
173+
[`client.retentionPolicy.listAssignments(policyId:type:marker:limit:fields)`][get-all-assignments].
174+
This method will return an iterator, which is used to get the assignments.
175+
176+
<!-- sample get_retention_policies_id_assignments -->
177+
```swift
178+
let iterator = client.retentionPolicy.listAssignments(policyId:"12345")
179+
iterator.next { results in
180+
switch results {
181+
case let .success(page):
182+
for assignment in page.entries {
183+
print("Retention policy assignment\(assignment.id)")
184+
}
185+
186+
case let .failure(error):
187+
print(error)
188+
}
189+
}
190+
```
191+
192+
You can also filter assignments by setting `type` parameter to one of values: `.folder`, `.metadataTemplate` or `.enterprise`:
193+
194+
```swift
195+
let iterator = client.retentionPolicy.listAssignments(policyId:"12345", type: .folder)
196+
iterator.next { results in
197+
switch results {
198+
case let .success(page):
199+
for assignment in page.entries {
200+
print("Retention policy assignment\(assignment.id)")
201+
}
202+
203+
case let .failure(error):
204+
print(error)
205+
}
206+
}
207+
```
208+
209+
[get-all-assignments]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC15listAssignments8policyId4type6marker5limit6fieldsAA14PagingIteratorCyAA0C16PolicyAssignmentCGSS_AA0cpQ8ItemTypeOSgSSSgSiSgSaySSGSgtF
210+
211+
## Delete Retention Policy Assignment
212+
213+
To remove a retention policy assignment applied to content, call
214+
[`client.retentionPolicy.deleteAssignment(assignmentId:completion:)`][delete-assignment] with the ID of the assignment.
215+
216+
<!-- sample delete_retention_policy_assignments_id -->
217+
```swift
218+
client.retentionPolicy.deleteAssignment(assignmentId: "123456") { result in
219+
guard case let .success = result else {
220+
print("Error deleting retention policy assignment")
221+
return
222+
}
223+
224+
print("Retention policy assignment was deleted")
225+
}
226+
```
227+
228+
[delete-assignment]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC16deleteAssignment12assignmentId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF
229+
230+
## Get File Version Retention
231+
232+
A file version retention is a record for a retained file version. To get information for a specific file version retention record, call
233+
[`client.files.getVersionRetention(retentionId:completion:)`][get-file-version-retention] with the ID of the file version retention.
234+
235+
236+
<!-- sample get_file_version_retentions_id -->
237+
```swift
238+
client.files.getVersionRetention(retentionId: "123456"){ result in
239+
guard case let .success(retention) = result else {
240+
print("Error getting file version retention")
241+
return
242+
}
243+
244+
print("File version retention: \(retention.id)")
245+
}
246+
```
247+
248+
[get-file-version-retention]: https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC19getVersionRetention11retentionId10completionySS_ys6ResultOyAA04FilefG0CAA0A8SDKErrorCGctF
249+
250+
## Get File Version Retentions
251+
252+
To retrieves all file version retentions for the given enterprise, call
253+
[`client.files.listVersionRetentions(fileId:fileVersionId:policyId:dispositionAction:dispositionBefore:dispositionAfter:limit:marker:)`][get-all-file-version-retentions].
254+
This method will return an iterator, which is used to get the file version retentions.
255+
256+
<!-- sample get_file_version_retentions -->
257+
```swift
258+
let iterator = client.files.listVersionRetentions()
259+
iterator.next { results in
260+
switch results {
261+
case let .success(page):
262+
for retention in page.entries {
263+
print("File version retention \(retention.id)")
264+
}
265+
266+
case let .failure(error):
267+
print(error)
268+
}
269+
}
270+
```
271+
272+
[get-all-file-version-retentions]: https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC21listVersionRetentions6fileId0hfI006policyI017dispositionAction0K6Before0K5After5limit6markerAA14PagingIteratorCyAA04FileF9RetentionCGSSSg_A2rA011DispositionL0OSg10Foundation4DateVSgAYSiSgARtF
273+
274+
## Get Files Under Retention For Assignment
275+
276+
To get all files under retention for assignment
277+
policy, call the [`client.retentionPolicy.listFilesUnderRetentionForAssignment(retentionPolicyAssignmentId:limit:marker:)`][get-files-under-retention-for-assignment] method.
278+
This method will return an iterator, which is used to get the [`File`][file] objects under retention.
279+
280+
<!-- sample get_retention_policy_assignments_id_files_under_retention -->
281+
```swift
282+
let iterator = client.retentionPolicy.listFilesUnderRetentionForAssignment(retentionPolicyAssignmentId: "123456")
283+
iterator.next { results in
284+
switch results {
285+
case let .success(page):
286+
for file in page.entries {
287+
print("File \(file.name ?? "")")
288+
}
289+
290+
case let .failure(error):
291+
print(error)
292+
}
293+
}
294+
```
295+
296+
[get-files-under-retention-for-assignment]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC014listFilesUnderC13ForAssignment015retentionPolicyJ2Id5limit6markerAA14PagingIteratorCyAA4FileCGSS_SiSgSSSgtF
297+
[file]: https://opensource.box.com/box-ios-sdk/Classes/File.html
298+
299+
Get File Versions Under Retention For Assignment
300+
------------------------------------------------
301+
302+
To get all file versions under retention placed in the file objects for a retention policy assignment, call the
303+
[`client.retentionPolicy.listFileVersionsUnderRetentionForAssignment(retentionPolicyAssignmentId:limit:marker:)`][get-file-versions-under-retention-for-assignment] method.
304+
This method will return an iterator, which is used to get the [`FileVersion`][file-version] object nested in [`File`][file] object.
305+
306+
307+
<!-- sample get_retention_policy_assignments_id_file_versions_under_retention -->
308+
```swift
309+
let iterator = client.retentionPolicy.listFileVersionsUnderRetentionForAssignment(retentionPolicyAssignmentId: "123456")
310+
iterator.next { results in
311+
switch results {
312+
case let .success(page):
313+
for file in page.entries {
314+
print("File version \(file.fileVersion?.id ?? "")")
315+
}
316+
317+
case let .failure(error):
318+
print(error)
319+
}
320+
}
321+
```
322+
323+
[get-file-versions-under-retention-for-assignment]: https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC021listFileVersionsUnderC13ForAssignment015retentionPolicyK2Id5limit6markerAA14PagingIteratorCyAA0G0CGSS_SiSgSSSgtF
324+
[file-version]: https://opensource.box.com/box-ios-sdk/Classes/FileVersion.html
325+
[file]: https://opensource.box.com/box-ios-sdk/Classes/File.html

0 commit comments

Comments
 (0)