feat: Update retention_policies and retention_policy_assignments (#…

…803)

* feat: Update `retention_policies` and `retention_policy_assignments`

boxsdk/client/client.py

@@ -862,7 +862,8 @@ def create_retention_policy(
             can_owner_extend_retention: Optional[bool] = None,
             are_owners_notified: Optional[bool] = None,
             custom_notification_recipients: Iterable['User'] = None,
-            retention_type: Optional[str] = None
+            retention_type: Optional[str] = None,
+            description: Optional[str] = None,
     ) -> 'RetentionPolicy':
         """
         Create a retention policy for the given enterprise.
@@ -888,6 +889,8 @@ def create_retention_policy(
             -   `non_modifiable`: You can modify the retention policy only in a limited way: add a folder,
                 lengthen the duration, retire the policy, change the disposition action or notification settings.
                 You cannot perform other actions, such as deleting the assignment or shortening the policy duration.
+        :param description:
+            The additional text description of the retention policy.
         :return:
             The newly created Retention Policy
         """
@@ -910,6 +913,8 @@ def create_retention_policy(
             retention_attributes['custom_notification_recipients'] = user_list
         if retention_type is not None:
             retention_attributes['retention_type'] = retention_type
+        if description is not None:
+            retention_attributes['description'] = description
         box_response = self._session.post(url, data=json.dumps(retention_attributes))
         response = box_response.json()
         return self.translator.translate(

boxsdk/object/retention_policy.py

@@ -26,14 +26,18 @@ def get_url(self, *args: Any) -> str:
     def assign(
             self,
             assignee: Union['Folder', 'Enterprise', 'MetadataTemplate'],
-            fields: Iterable[str] = None
+            fields: Iterable[str] = None,
+            start_date_field: Optional[str] = None,
     ) -> 'RetentionPolicyAssignment':
         """Assign a retention policy to a Box item
 
         :param assignee:
             The item to assign the retention policy on.
         :param fields:
             List of fields to request.
+        :param start_date_field:
+            The date the retention policy assignment begins.
+            If the assigned_to type is metadata_template, this field can be a date field's metadata attribute key id.
         :returns:
             A :class:`RetentionPolicyAssignment` object.
         """
@@ -48,6 +52,8 @@ def assign(
         params = {}
         if fields is not None:
             params['fields'] = ','.join(fields)
+        if start_date_field is not None:
+            body['start_date_field'] = start_date_field
         response = self._session.post(url, data=json.dumps(body), params=params).json()
         return self.translator.translate(
             session=self._session,

test/integration_new/object/retention_policy_assignement_itest.py

@@ -5,6 +5,7 @@
 from test.integration_new.context_managers.box_retention_policy import BoxRetentionPolicy
 from test.integration_new.context_managers.box_test_file import BoxTestFile
 from test.integration_new.context_managers.box_test_folder import BoxTestFolder
+from test.integration_new.context_managers.box_metadata_template import BoxTestMetadataTemplate
 
 
 RETENTION_POLICY_ASSIGNMENT_TESTS_DIRECTORY_NAME = 'retention-policy-assignment-integration-tests'
@@ -34,3 +35,18 @@ def test_delete_retention_policy_assignment(parent_folder, small_file_path):
 
             with pytest.raises(BoxAPIException):
                 retention_policy_assignment.get()
+
+
+def test_retention_policy_assignement_to_metadata_template():
+    with BoxTestMetadataTemplate(display_name="test_template") as metadata_template:
+        with BoxRetentionPolicy(disposition_action='permanently_delete', retention_length=1) as retention_policy:
+            retention_policy_assignment = retention_policy.assign(metadata_template, start_date_field='upload_date')
+
+            assignment = retention_policy_assignment.get()
+            assert assignment.id is not None
+            assert assignment.start_date_field == 'upload_date'
+
+            retention_policy_assignment.delete()
+
+            with pytest.raises(BoxAPIException):
+                retention_policy_assignment.get()

test/integration_new/object/retention_policy_itest.py

@@ -0,0 +1,40 @@
+from test.integration_new import util
+from test.integration_new import CLIENT
+
+
+def test_create_metedata_template_with_fields():
+    policy_name = 'Test Retention Policy ' + util.random_name()
+    disposition_action = 'permanently_delete'
+    retention_length = '1'
+    retention_type = 'modifiable'
+    policy_description = 'Test Retention Policy'
+
+    retention_policy = CLIENT.create_retention_policy(
+        policy_name=policy_name,
+        disposition_action=disposition_action,
+        retention_length=retention_length,
+        retention_type=retention_type,
+        description=policy_description
+    )
+
+    try:
+        assert retention_policy.policy_name == policy_name
+        assert retention_policy.disposition_action == disposition_action
+        assert retention_policy.retention_length == retention_length
+        assert retention_policy.retention_type == retention_type
+        assert retention_policy.description == policy_description
+
+        new_policy_name = 'Test Retention Policy ' + util.random_name()
+        new_policy_description = 'Test Retention Policy Updated'
+        retention_policy.update_info(data={
+            'policy_name': new_policy_name,
+            'description': new_policy_description
+        })
+
+        retention_policy = CLIENT.retention_policy(retention_id=retention_policy.object_id).get()
+        assert retention_policy.policy_name == new_policy_name
+        assert retention_policy.description == new_policy_description
+    finally:
+        retention_policy.update_info(data={
+            'status': 'retired'
+        })

test/unit/client/test_client.py

@@ -894,6 +894,7 @@ def test_create_retention_policy(mock_client, mock_box_session, mock_user_list):
     policy_name = 'Test Retention Policy'
     policy_type = 'finite'
     disposition_action = 'remove_retention'
+    policy_description = 'Test Retention Policy'
     expected_url = f'{API.BASE_API_URL}/retention_policies'
     expected_data = {
         'policy_name': policy_name,
@@ -912,7 +913,8 @@ def test_create_retention_policy(mock_client, mock_box_session, mock_user_list):
                 'id': mock_user_list[1].object_id,
             },
         ],
-        'retention_type': 'modifiable'
+        'retention_type': 'modifiable',
+        'description': policy_description,
     }
     mock_policy = {
         'type': 'retention_policy',
@@ -933,7 +935,8 @@ def test_create_retention_policy(mock_client, mock_box_session, mock_user_list):
                 'id': mock_user_list[1].object_id,
             },
         ],
-        'retention_type': 'modifiable'
+        'retention_type': 'modifiable',
+        'description': policy_description,
     }
     mock_box_session.post.return_value.json.return_value = mock_policy
     policy = mock_client.create_retention_policy(
@@ -943,7 +946,8 @@ def test_create_retention_policy(mock_client, mock_box_session, mock_user_list):
         can_owner_extend_retention=True,
         are_owners_notified=False,
         custom_notification_recipients=mock_user_list,
-        retention_type='modifiable'
+        retention_type='modifiable',
+        description=policy_description,
     )
     mock_box_session.post.assert_called_once_with(expected_url, data=json.dumps(expected_data))
     assert policy.object_id == mock_policy['id']
@@ -953,13 +957,15 @@ def test_create_retention_policy(mock_client, mock_box_session, mock_user_list):
     assert policy.can_owner_extend_retention == mock_policy['can_owner_extend_retention']
     assert policy.are_owners_notified == mock_policy['are_owners_notified']
     assert policy.retention_type == mock_policy['retention_type']
+    assert policy.description == mock_policy['description']
     assert isinstance(policy, RetentionPolicy)
 
 
 def test_create_infinte_retention_policy(mock_client, mock_box_session):
     policy_name = 'Test Retention Policy'
     policy_type = 'indefinite'
     disposition_action = 'remove_retention'
+    policy_description = 'Test Retention Policy'
     expected_url = f'{API.BASE_API_URL}/retention_policies'
     expected_data = {
         'policy_name': policy_name,
@@ -968,6 +974,7 @@ def test_create_infinte_retention_policy(mock_client, mock_box_session):
         'can_owner_extend_retention': False,
         'are_owners_notified': False,
         'retention_type': 'non_modifiable',
+        'description': policy_description,
     }
     mock_policy = {
         'type': 'retention_policy',
@@ -978,6 +985,7 @@ def test_create_infinte_retention_policy(mock_client, mock_box_session):
         'can_owner_extend_retention': False,
         'are_owners_notified': False,
         'retention_type': 'non_modifiable',
+        'description': policy_description,
     }
     mock_box_session.post.return_value.json.return_value = mock_policy
     policy = mock_client.create_retention_policy(
@@ -986,7 +994,8 @@ def test_create_infinte_retention_policy(mock_client, mock_box_session):
         retention_length=float('inf'),
         can_owner_extend_retention=False,
         are_owners_notified=False,
-        retention_type='non_modifiable'
+        retention_type='non_modifiable',
+        description=policy_description,
     )
     mock_box_session.post.assert_called_once_with(expected_url, data=json.dumps(expected_data))
     assert policy.object_id == mock_policy['id']
@@ -996,6 +1005,7 @@ def test_create_infinte_retention_policy(mock_client, mock_box_session):
     assert policy.can_owner_extend_retention == mock_policy['can_owner_extend_retention']
     assert policy.are_owners_notified == mock_policy['are_owners_notified']
     assert policy.retention_type == mock_policy['retention_type']
+    assert policy.description == mock_policy['description']
     assert isinstance(policy, RetentionPolicy)
 
 

test/unit/object/test_retention_policy.py

@@ -14,19 +14,22 @@ def test_get(test_retention_policy, mock_box_session):
         'policy_type': 'finite',
         'retention_length': '10',
         'disposition_action': 'permanently_delete',
+        'description': 'Description',
     }
     retention_policy = test_retention_policy.get()
     mock_box_session.get.assert_called_once_with(expected_url, headers=None, params=None)
     assert isinstance(retention_policy, RetentionPolicy)
     assert retention_policy['type'] == test_retention_policy.object_type
     assert retention_policy['id'] == test_retention_policy.object_id
     assert retention_policy['policy_name'] == 'Policy Name'
+    assert retention_policy['description'] == 'Description'
 
 
 def test_update(test_retention_policy, mock_box_session):
     new_policy_name = 'New Name'
     new_retention_type = 'modifiable'
     new_retention_length = 60
+    new_description = 'New Description'
     expected_url = f'{API.BASE_API_URL}/retention_policies/{test_retention_policy.object_id}'
     mock_box_session.put.return_value.json.return_value = {
         'type': test_retention_policy.object_type,
@@ -35,11 +38,13 @@ def test_update(test_retention_policy, mock_box_session):
         'policy_type': 'finite',
         'retention_length': new_retention_length,
         'retention_type': new_retention_type,
+        'description': new_description,
     }
     data = {
         'policy_name': new_policy_name,
         'retention_type': new_retention_type,
-        'retention_length': new_retention_length
+        'retention_length': new_retention_length,
+        'description': new_description,
     }
     retention_policy = test_retention_policy.update_info(data=data)
     mock_box_session.put.assert_called_once_with(expected_url, data=json.dumps(data), headers=None, params=None)
@@ -49,6 +54,7 @@ def test_update(test_retention_policy, mock_box_session):
     assert retention_policy['policy_name'] == new_policy_name
     assert retention_policy['retention_type'] == new_retention_type
     assert retention_policy['retention_length'] == new_retention_length
+    assert retention_policy['description'] == new_description
 
 
 def test_assign(test_retention_policy, test_folder, mock_box_session):
@@ -59,21 +65,24 @@ def test_assign(test_retention_policy, test_folder, mock_box_session):
         'assign_to': {
             'type': test_folder.object_type,
             'id': test_folder.object_id,
-        }
+        },
+        "start_date_field": "upload_date"
     }
     mock_assignment = {
         'type': 'retention_policy_assignment',
         'id': '1234',
         'retention_policy': {
             'type': 'retention_policy',
             'id': policy_id,
-        }
+        },
+        "start_date_field": "upload_date"
     }
     mock_box_session.post.return_value.json.return_value = mock_assignment
-    assignment = test_retention_policy.assign(test_folder)
+    assignment = test_retention_policy.assign(test_folder, start_date_field='upload_date')
     mock_box_session.post.assert_called_once_with(expected_url, data=json.dumps(expected_data), params={})
     assert assignment.id == mock_assignment['id']
     assert assignment.retention_policy['id'] == mock_assignment['retention_policy']['id']
+    assert assignment.start_date_field == mock_assignment['start_date_field']
     assert isinstance(assignment, RetentionPolicyAssignment)