Skip to content

Commit 3e11538

Browse files
author
Cristiano Betta
authored
Add explicit classification and shared link docs (#542)
1 parent 7549076 commit 3e11538

File tree

3 files changed

+411
-7
lines changed

3 files changed

+411
-7
lines changed

‎docs/usage/classifications.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
Classifications
2+
===============
3+
4+
Classifications are a type of metadata that allows users and applications
5+
to define and assign a content classification to files and folders.
6+
7+
Classifications use the metadata APIs to add and remove classifications, and
8+
assign them to files. For more details on metadata templates please see the
9+
[metadata documentation](./metadata.md).
10+
11+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
12+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
13+
14+
15+
- [Add initial classifications](#add-initial-classifications)
16+
- [List all classifications](#list-all-classifications)
17+
- [Add another classification](#add-another-classification)
18+
- [Update a classification](#update-a-classification)
19+
- [Delete a classification](#delete-a-classification)
20+
- [Delete all classifications](#delete-all-classifications)
21+
- [Add classification to file](#add-classification-to-file)
22+
- [Update classification on file](#update-classification-on-file)
23+
- [Get classification on file](#get-classification-on-file)
24+
- [Remove classification from file](#remove-classification-from-file)
25+
- [Add classification to folder](#add-classification-to-folder)
26+
- [Update classification on folder](#update-classification-on-folder)
27+
- [Get classification on folder](#get-classification-on-folder)
28+
- [Remove classification from folder](#remove-classification-from-folder)
29+
30+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
31+
32+
Add initial classifications
33+
---------------------------
34+
35+
If an enterprise does not already have a classification defined, the first classification(s)
36+
can be added with the
37+
`client.create_metadata_template(display_name, fields, template_key=None, hidden=False, scope='enterprise')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_metadata_template)
38+
method.
39+
40+
<!-- sample post_metadata_templates_schema classifications -->
41+
```python
42+
from boxsdk.object.metadata_template import MetadataField, MetadataFieldType
43+
44+
fields = [
45+
MetadataField(MetadataFieldType.ENUM, 'Classification', key='Box__Security__Classification__Key', options=['Top Secret'])
46+
]
47+
48+
template = client.create_metadata_template('Classification', fields, template_key='securityClassification-6VMVochwUWo')
49+
```
50+
51+
List all classifications
52+
------------------------
53+
54+
To retrieve a list of all the classifications in an enterprise call the
55+
[`client.metadata_template(scope, template_key)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.metadata_template)
56+
method to get the classifications template, which will contain a list of all the
57+
classifications.
58+
59+
<!-- sample get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema -->
60+
```python
61+
template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo').get()
62+
```
63+
64+
Add another classification
65+
--------------------------
66+
67+
To add another classification, call the
68+
[`template.start_update()`][start_update] API to start making changes to the
69+
template, and then call the [`template.update_info(updates)`][update_info]
70+
with the changes to apply to the template.
71+
72+
<!-- sample put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema add -->
73+
```python
74+
template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo')
75+
updates = template.start_update()
76+
updates.add_enum_option('Box__Security__Classification__Key', 'Sensitive')
77+
updated_template = template.update_info(updates)
78+
```
79+
80+
[start_update]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.start_update
81+
[update_info]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.update_info
82+
83+
Update a classification
84+
-----------------------
85+
86+
To update a classification, call the
87+
[`template.start_update()`][start_update] API to start making changes to the
88+
template, and then call the [`template.update_info(updates)`][update_info]
89+
with the classification to change on the template.
90+
91+
<!-- sample put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema update -->
92+
```python
93+
template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo')
94+
updates = template.start_update()
95+
updates.edit_enum_option('Box__Security__Classification__Key', 'Sensitive', 'Very Sensitive')
96+
updated_template = template.update_info(updates)
97+
```
98+
99+
Delete a classification
100+
-----------------------
101+
102+
To delete a classification, call the
103+
[`template.start_update()`][start_update] API to start making changes to the
104+
template, and then call the [`template.update_info(updates)`][update_info]
105+
with the classification to remove from the template.
106+
107+
<!-- sample put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema delete -->
108+
```python
109+
template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo')
110+
updates = template.start_update()
111+
updates.remove_enum_option('Box__Security__Classification__Key', 'Sensitive')
112+
updated_template = template.update_info(updates)
113+
```
114+
115+
Delete all classifications
116+
--------------------------
117+
118+
To remove all classifications in an enterprise, call the
119+
[`template.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete)
120+
method with the name of the classification metadata template.
121+
122+
<!-- sample delete_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema -->
123+
```python
124+
client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo').delete()
125+
```
126+
127+
Add classification to file
128+
--------------------------
129+
130+
To add a classification to a file, call
131+
[`file.metadata(scope='global', template='properties')`][set-metadata]
132+
with the name of the classification template, as well as the details of the classification
133+
to add to the file.
134+
135+
<!-- sample post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
136+
```python
137+
classification = {
138+
'Box__Security__Classification__Key': 'Sensitive',
139+
}
140+
applied_metadata = client.file(file_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification)
141+
```
142+
143+
[set-metadata]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata
144+
145+
Update classification on file
146+
-----------------------------
147+
148+
To update a classification on a file, call
149+
[`file.metadata(scope='global', template='properties')`][update-metadata]
150+
with the name of the classification template, as well as the details of the classification
151+
to add to the file.
152+
153+
<!-- sample put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
154+
```python
155+
classification = {
156+
'Box__Security__Classification__Key': 'Sensitive',
157+
}
158+
applied_metadata = client.file(file_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification)
159+
```
160+
161+
[update-metadata]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata
162+
163+
Get classification on file
164+
--------------------------
165+
166+
Retrieve the classification on a file by calling
167+
[`file.metadata(scope='global', template='properties').get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.get)
168+
on a file.
169+
170+
<!-- sample get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
171+
```python
172+
metadata = client.file(file_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').get()
173+
```
174+
175+
Remove classification from file
176+
-------------------------------
177+
178+
A classification can be removed from a file by calling
179+
[`file.metadata(scope='global', template='properties').delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.delete).
180+
181+
<!-- sample delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
182+
```python
183+
client.file(file_id='11111').metadata(scope='securityClassification-6VMVochwUWo', template='myMetadata').delete()
184+
```
185+
186+
187+
188+
Add classification to folder
189+
--------------------------
190+
191+
To add a classification to a folder, call
192+
[`folder.metadata(scope='global', template='properties')`][set-metadata]
193+
with the name of the classification template, as well as the details of the classification
194+
to add to the folder.
195+
196+
<!-- sample post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
197+
```python
198+
classification = {
199+
'Box__Security__Classification__Key': 'Sensitive',
200+
}
201+
applied_metadata = client.folder(folder_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification)
202+
```
203+
204+
[set-metadata]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata
205+
206+
Update classification on folder
207+
-----------------------------
208+
209+
To update a classification on a folder, call
210+
[`folder.metadata(scope='global', template='properties')`][update-metadata]
211+
with the name of the classification template, as well as the details of the classification
212+
to add to the folder.
213+
214+
<!-- sample put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
215+
```python
216+
classification = {
217+
'Box__Security__Classification__Key': 'Sensitive',
218+
}
219+
applied_metadata = client.folder(folder_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification)
220+
```
221+
222+
[update-metadata]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata
223+
224+
Get classification on folder
225+
--------------------------
226+
227+
Retrieve the classification on a folder by calling
228+
[`folder.metadata(scope='global', template='properties').get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.get)
229+
on a folder.
230+
231+
<!-- sample get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
232+
```python
233+
metadata = client.folder(folder_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').get()
234+
```
235+
236+
Remove classification from folder
237+
-------------------------------
238+
239+
A classification can be removed from a folder by calling
240+
[`folder.metadata(scope='global', template='properties').delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.delete).
241+
242+
<!-- sample delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo -->
243+
```python
244+
client.folder(folder_id='11111').metadata(scope='securityClassification-6VMVochwUWo', template='myMetadata').delete()
245+
```

‎docs/usage/files.md‎

Lines changed: 89 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@ file's contents, upload new versions, and perform other common file operations
3535
- [Lock a File](#lock-a-file)
3636
- [Unlock a File](#unlock-a-file)
3737
- [Create a Shared Link](#create-a-shared-link)
38+
- [Find a File for a Shared Link](#find-a-file-for-a-shared-link)
39+
- [Create a Shared Link](#create-a-shared-link-1)
40+
- [Update a Shared Link](#update-a-shared-link)
41+
- [Get a Shared Link](#get-a-shared-link)
42+
- [Remove a Shared Link](#remove-a-shared-link)
3843
- [Get an Embed Link](#get-an-embed-link)
3944
- [Get File Representations](#get-file-representations)
4045
- [Get Thumbnail](#get-thumbnail)
@@ -629,16 +634,99 @@ A shared link for a file can be generated by calling
629634
[`file.get_shared_link(access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None, password=None)`][get_shared_link].
630635
This method returns a `unicode` string containing the shared link URL.
631636

632-
<!-- sample put_files_id_shared_link_create -->
637+
<!-- sample put_files_id add_shared_link -->
633638
```python
634639
file_id = '11111'
635640

636641
url = client.file(file_id).get_shared_link()
637642
print('The file shared link URL is: {0}'.format(url))
638643
```
639644

645+
[get_shared_link]:
646+
https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_shared_link
647+
648+
Find a File for a Shared Link
649+
-----------------------------
650+
651+
To find a file given a shared link, use the
652+
[`client.get_shared_item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html?highlight=get_shared_item#boxsdk.client.client.Client.get_shared_item)
653+
method.
654+
655+
<!-- sample get_shared_items -->
656+
```python
657+
file = client.get_shared_item('https://app.box.com/s/gjasdasjhasd', password='letmein')
658+
```
659+
660+
Create a Shared Link
661+
--------------------
662+
663+
A shared link for a file can be generated by calling
664+
[`file.get_shared_link(access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None, password=None)`][get_shared_link].
665+
This method returns a `unicode` string containing the shared link URL.
666+
667+
<!-- sample put_files_id add_shared_link -->
668+
```python
669+
file_id = '11111'
670+
671+
url = client.file(file_id).get_shared_link(access='open', allow_download=False)
672+
print('The file shared link URL is: {0}'.format(url))
673+
```
674+
640675
[get_shared_link]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_shared_link
641676

677+
Update a Shared Link
678+
--------------------
679+
680+
A shared link for a file can be updated by calling
681+
[`file.get_shared_link(access=None, etag=None, unshared_at=None,
682+
allow_download=None, allow_preview=None, password=None)`][update_shared_link]
683+
with an updated list of properties.
684+
685+
This method returns a `unicode` string containing the shared link URL.
686+
687+
<!-- sample put_files_id update_shared_link -->
688+
```python
689+
file_id = '11111'
690+
691+
url = client.file(file_id).get_shared_link(access='open', allow_download=True)
692+
print('The file shared link URL is: {0}'.format(url))
693+
```
694+
695+
[update_shared_link]:
696+
https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_shared_link
697+
698+
Get a Shared Link
699+
--------------------
700+
701+
To check for an existing shared link on a file, simply call
702+
`file.shared_link`
703+
704+
This method returns a `unicode` string containing the shared link URL.
705+
706+
<!-- sample get_files_id get_shared_link -->
707+
```python
708+
file_id = '11111'
709+
shared_link = client.file(file_id).shared_link
710+
url = shared_link['download_url']
711+
```
712+
713+
[remove_shared_link]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_shared_link
714+
715+
Remove a Shared Link
716+
--------------------
717+
718+
A shared link for a file can be removed calling
719+
[`file.remove_shared_link(etag=None)`][remove_shared_link].
720+
721+
<!-- sample put_files_id remove_shared_link -->
722+
```python
723+
file_id = '11111'
724+
client.file(file_id).remove_shared_link()
725+
```
726+
727+
[remove_shared_link]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_shared_link
728+
729+
642730
Get an Embed Link
643731
-----------------
644732

0 commit comments

Comments
 (0)