Add events command to legal-hold

CHANGELOG.md

@@ -8,6 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The intended audience of this file is for py42 consumers -- as such, changes that don't affect
 how a consumer would use the library (e.g. adding unit tests, updating documentation, etc) are not captured here.
 
+## Unreleased
+
+### Added
+
+- `code42 legal-hold events` command:
+    - `--matter-id` filters based on a legal hold uid.
+    - `--begin` filters based on a beginning timestamp.
+    - `--end` filters based on an end timestamp.
+    - `--event-type` filters based on a list of event types.
+
 ## 1.4.0 - 2021-03-09
 
 ### Added

docs/userguides/legalhold.md

@@ -93,4 +93,12 @@ To view all custodians (including inactive) for a legal hold matter, enter
 
 `code42 legal-hold show <matterID> --include-inactive`
 
+### List legal hold events
+
+To view a list of legal hold administrative events, use the following command:
+
+`code42 legal-hold events`
+
+This command takes the optional filters of a specific matter uid, beginning time stamp, end time stamp, and event type.
+
 Learn more about the [Legal Hold](../commands/legalhold.md) commands.

src/code42cli/cmds/legal_hold.py

@@ -14,6 +14,8 @@
 from code42cli.file_readers import read_csv_arg
 from code42cli.options import format_option
 from code42cli.options import sdk_options
+from code42cli.options import set_begin_default_dict
+from code42cli.options import set_end_default_dict
 from code42cli.output_formats import OutputFormat
 from code42cli.output_formats import OutputFormatter
 from code42cli.util import format_string_list_to_columns
@@ -25,6 +27,18 @@
 _MATTER_KEYS_MAP["description"] = "Description"
 _MATTER_KEYS_MAP["creator_username"] = "Creator"
 _MATTER_KEYS_MAP["creationDate"] = "Creation Date"
+_EVENT_KEYS_MAP = OrderedDict()
+_EVENT_KEYS_MAP["eventUid"] = "Event ID"
+_EVENT_KEYS_MAP["eventType"] = "Event Type"
+_EVENT_KEYS_MAP["eventDate"] = "Event Date"
+_EVENT_KEYS_MAP["legalHoldUid"] = "Legal Hold ID"
+_EVENT_KEYS_MAP["actorUsername"] = "Actor Username"
+_EVENT_KEYS_MAP["custodianUsername"] = "Custodian Username"
+
+
+LEGAL_HOLD_KEYWORD = "legal hold events"
+BEGIN_DATE_DICT = set_begin_default_dict(LEGAL_HOLD_KEYWORD)
+END_DATE_DICT = set_end_default_dict(LEGAL_HOLD_KEYWORD)
 
 
 @click.group(cls=OrderedGroup)
@@ -124,6 +138,37 @@ def show(state, matter_id, include_inactive=False, include_policy=False):
         echo("")
 
 
+@legal_hold.command()
+@click.option(
+    "--matter-id", type=str, help="Filter results by legal hold UID",
+)
+@click.option(
+    "--event-type",
+    type=click.Choice(
+        [
+            "MembershipCreated",
+            "MembershipReactivated",
+            "MembershipDeactivated",
+            "HoldCreated",
+            "HoldDeactivated",
+            "HoldReactivated",
+            "Restore",
+        ]
+    ),
+    help="Filter results by event types",
+)
+@click.option("--begin", **BEGIN_DATE_DICT)
+@click.option("--end", **END_DATE_DICT)
+@format_option
+@sdk_options()
+def events(state, matter_id, event_type, begin, end, format):
+    """Report on legal hold events"""
+    formatter = OutputFormatter(format, _EVENT_KEYS_MAP)
+    events = _get_all_events(state.sdk, matter_id, begin, end, event_type)
+    if events:
+        formatter.echo_formatted_list(events)
+
+
 @legal_hold.group(cls=OrderedGroup)
 @sdk_options(hidden=True)
 def bulk(state):
@@ -230,6 +275,24 @@ def _get_all_active_matters(sdk):
     return matters
 
 
+def _get_all_events(sdk, legal_hold_uid, begin_date, end_date, event_type):
+    events_generator = sdk.legalhold.get_all_events(
+        legal_hold_uid, begin_date, end_date
+    )
+    if event_type:
+        events = [
+            event
+            for page in events_generator
+            for event in page["legalHoldEvents"]
+            if event["eventType"] == event_type
+        ]
+    else:
+        events = [
+            event for page in events_generator for event in page["legalHoldEvents"]
+        ]
+    return events
+
+
 def _print_matter_members(username_list, member_type="active"):
     if username_list:
         echo("\n{} matter members:\n".format(member_type.capitalize()))

tests/cmds/test_legal_hold.py

@@ -8,7 +8,6 @@
 from code42cli.cmds.legal_hold import _check_matter_is_accessible
 from code42cli.main import cli
 
-
 _NAMESPACE = "{}.cmds.legal_hold".format(PRODUCT_NAME)
 TEST_MATTER_ID = "99999"
 TEST_LEGAL_HOLD_MEMBERSHIP_UID = "88888"
@@ -169,6 +168,41 @@
     ]
 }
 """
+EVENTS_RESPONSE = """
+{
+        "eventUid":"564564654566",
+        "eventType":"HoldCreated",
+        "eventDate":"2015-05-16T15:07:44.820Z",
+        "legalHoldUid":"88888",
+        "actorUserUid":"12345",
+        "actorUsername":"[email protected]",
+        "actorFirstName":"john",
+        "actorLastName":"doe",
+        "actorUserExtRef":null,
+        "actorEmail":"[email protected]"
+      },
+      {
+        "eventUid":"74533457745",
+        "eventType":"MembershipCreated",
+        "eventDate":"2019-05-17T15:07:44.820Z",
+        "legalHoldUid":"88888",
+        "legalHoldMembershipUid":"645576514441664433",
+        "custodianUserUid":"12345",
+        "custodianUsername":"[email protected]",
+        "custodianFirstName":"kim",
+        "custodianLastName":"jones",
+        "custodianUserExtRef":null,
+        "custodianEmail":"[email protected]",
+        "actorUserUid":"1234512345",
+        "actorUsername":"[email protected]",
+        "actorFirstName":"john",
+        "actorLastName":"doe",
+        "actorUserExtRef":null,
+        "actorEmail":"[email protected]"
+      }
+"""
+EMPTY_EVENTS_RESPONSE = """{"legalHoldEvents": []}"""
+ALL_EVENTS_RESPONSE = """{{"legalHoldEvents": [{}]}}""".format(EVENTS_RESPONSE)
 EMPTY_MATTERS_RESPONSE = """{"legalHolds": []}"""
 ALL_MATTERS_RESPONSE = """{{"legalHolds": [{}]}}""".format(MATTER_RESPONSE)
 LEGAL_HOLD_COMMAND = "legal-hold"
@@ -212,6 +246,21 @@ def active_and_inactive_legal_hold_memberships_response(mocker):
     return [_create_py42_response(mocker, ALL_ACTIVE_AND_INACTIVE_CUSTODIANS_RESPONSE)]
 
 
+@pytest.fixture
+def events_response(mocker):
+    return _create_py42_response(mocker, EVENTS_RESPONSE)
+
+
+@pytest.fixture
+def empty_events_response(mocker):
+    return _create_py42_response(mocker, EMPTY_EVENTS_RESPONSE)
+
+
+@pytest.fixture
+def all_events_response(mocker):
+    return [_create_py42_response(mocker, ALL_EVENTS_RESPONSE)]
+
+
 @pytest.fixture
 def get_user_id_success(cli_state):
     cli_state.sdk.users.get_by_username.return_value = {
@@ -246,6 +295,11 @@ def check_matter_accessible_failure(cli_state, custom_error):
     )
 
 
+@pytest.fixture
+def get_all_events_success(cli_state):
+    cli_state.sdk.legalhold.get_all_events.return_value = events_response
+
+
 @pytest.fixture
 def user_already_added_response(mocker):
     mock_response = mocker.MagicMock(spec=Response)
@@ -575,6 +629,28 @@ def test_list_with_csv_format_returns_no_response_when_response_is_empty(
     assert "Matter ID,Name,Description,Creator,Creation Date" not in result.output
 
 
+def test_events_shows_events_that_respect_type_filters(
+    runner, cli_state, get_all_events_success, all_events_response
+):
+
+    cli_state.sdk.legalhold.get_all_events.return_value = all_events_response
+    result = runner.invoke(
+        cli, ["legal-hold", "events", "--event-type", "HoldCreated"], obj=cli_state
+    )
+
+    assert "564564654566" in result.output
+    assert "74533457745" not in result.output
+
+
+def test_events_with_csv_returns_no_events_when_response_is_empty(
+    runner, cli_state, get_all_events_success, empty_events_response
+):
+    cli_state.sdk.legalhold.get_all_events.return_value = empty_events_response
+    result = runner.invoke(cli, ["legal-hold", "events", "-f", "csv"], obj=cli_state)
+
+    assert "Matter ID,Name,Description,Creator,Creation Date" not in result.output
+
+
 @pytest.mark.parametrize(
     "command, error_msg",
     [