Users command: option to report on legal hold membership

CHANGELOG.md

@@ -8,6 +8,12 @@ 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
+
+- New command 'code42 users list --include-legal-hold-membership' to print the legal hold matter name and ID for any user on legal hold
+
 ## 1.7.0 - 2021-06-17
 
 ### Added

src/code42cli/cmds/users.py

@@ -1,5 +1,6 @@
 import click
 from pandas import DataFrame
+from pandas import json_normalize
 
 from code42cli.click_ext.groups import OrderedGroup
 from code42cli.click_ext.options import incompatible_with
@@ -46,9 +47,19 @@ def username_option(help):
 @role_name_option("Limit results to only users having the specified role.")
 @active_option
 @inactive_option
+@click.option(
+    "--include-legal-hold-membership",
+    required=False,
+    type=bool,
+    default=False,
+    is_flag=True,
+    help="Include legal hold membership in output.",
+)
 @format_option
 @sdk_options()
-def list_users(state, org_uid, role_name, active, inactive, format):
+def list_users(
+    state, org_uid, role_name, active, inactive, include_legal_hold_membership, format
+):
     """List users in your Code42 environment."""
     if inactive:
         active = False
@@ -59,6 +70,8 @@ def list_users(state, org_uid, role_name, active, inactive, format):
         else None
     )
     df = _get_users_dataframe(state.sdk, columns, org_uid, role_id, active)
+    if include_legal_hold_membership:
+        df = _add_legal_hold_membership_to_user_dataframe(state.sdk, df)
     if df.empty:
         click.echo("No results found.")
     else:
@@ -122,3 +135,37 @@ def _get_users_dataframe(sdk, columns, org_uid, role_id, active):
         users_list.extend(page["users"])
 
     return DataFrame.from_records(users_list, columns=columns)
+
+
+def _add_legal_hold_membership_to_user_dataframe(sdk, df):
+    columns = ["legalHold.legalHoldUid", "legalHold.name", "user.userUid"]
+
+    legal_hold_member_dataframe = (
+        json_normalize(list(_get_all_active_hold_memberships(sdk)))[columns]
+        .groupby(["user.userUid"])
+        .agg(",".join)
+        .rename(
+            {
+                "legalHold.legalHoldUid": "legalHoldUid",
+                "legalHold.name": "legalHoldName",
+            },
+            axis=1,
+        )
+    )
+    df = df.merge(
+        legal_hold_member_dataframe,
+        how="left",
+        left_on="userUid",
+        right_on="user.userUid",
+    )
+
+    return df
+
+
+def _get_all_active_hold_memberships(sdk):
+    for page in sdk.legalhold.get_all_matters(active=True):
+        for matter in page["legalHolds"]:
+            for _page in sdk.legalhold.get_all_matter_custodians(
+                legal_hold_uid=matter["legalHoldUid"], active=True
+            ):
+                yield from _page["legalHoldMemberships"]

tests/cmds/test_users.py

@@ -1,9 +1,11 @@
 import json
 
 import pytest
+from pandas import DataFrame
 from py42.response import Py42Response
 from requests import Response
 
+from code42cli.cmds.users import _add_legal_hold_membership_to_user_dataframe
 from code42cli.main import cli
 
 
@@ -32,6 +34,41 @@
         }
     ]
 }
+TEST_MATTER_RESPONSE = {
+    "legalHolds": [
+        {"legalHoldUid": "123456789", "name": "Legal Hold #1", "active": True},
+        {"legalHoldUid": "987654321", "name": "Legal Hold #2", "active": True},
+    ]
+}
+TEST_CUSTODIANS_RESPONSE = {
+    "legalHoldMemberships": [
+        {
+            "legalHoldMembershipUid": "99999",
+            "active": True,
+            "creationDate": "2020-07-16T08:50:23.405Z",
+            "legalHold": {"legalHoldUid": "123456789", "name": "Legal Hold #1"},
+            "user": {
+                "userUid": "911162111513111325",
+                "username": "[email protected]",
+                "email": "[email protected]",
+                "userExtRef": None,
+            },
+        },
+        {
+            "legalHoldMembershipUid": "11111",
+            "active": True,
+            "creationDate": "2020-07-16T08:50:23.405Z",
+            "legalHold": {"legalHoldUid": "987654321", "name": "Legal Hold #2"},
+            "user": {
+                "userUid": "911162111513111325",
+                "username": "[email protected]",
+                "email": "[email protected]",
+                "userExtRef": None,
+            },
+        },
+    ]
+}
+
 TEST_EMPTY_USERS_RESPONSE = {"users": []}
 TEST_USERNAME = TEST_USERS_RESPONSE["users"][0]["username"]
 TEST_USER_ID = TEST_USERS_RESPONSE["users"][0]["userId"]
@@ -50,6 +87,14 @@ def get_all_users_generator():
     yield TEST_USERS_RESPONSE
 
 
+def matter_list_generator():
+    yield TEST_MATTER_RESPONSE
+
+
+def custodian_list_generator():
+    yield TEST_CUSTODIANS_RESPONSE
+
+
 @pytest.fixture
 def get_available_roles_response(mocker):
     return _create_py42_response(mocker, json.dumps(TEST_ROLE_RETURN_DATA))
@@ -70,6 +115,18 @@ def get_user_id_failure(cli_state):
     cli_state.sdk.users.get_by_username.return_value = TEST_EMPTY_USERS_RESPONSE
 
 
+@pytest.fixture
+def get_all_matter_success(cli_state):
+    cli_state.sdk.legalhold.get_all_matters.return_value = matter_list_generator()
+
+
+@pytest.fixture
+def get_all_custodian_success(cli_state):
+    cli_state.sdk.legalhold.get_all_matter_custodians.return_value = (
+        custodian_list_generator()
+    )
+
+
 @pytest.fixture
 def get_available_roles_success(cli_state, get_available_roles_response):
     cli_state.sdk.users.get_available_roles.return_value = get_available_roles_response
@@ -169,6 +226,32 @@ def test_list_users_when_given_excluding_active_and_inactive_uses_active_equals_
     )
 
 
+def test_add_legal_hold_membership_to_user_dataframe_adds_legal_hold_columns_to_dataframe(
+    cli_state, get_all_matter_success, get_all_custodian_success
+):
+    testdf = DataFrame.from_records(
+        [{"userUid": "840103986007089121", "status": "Active"}]
+    )
+    result = _add_legal_hold_membership_to_user_dataframe(cli_state.sdk, testdf)
+    assert "legalHoldUid" in result.columns
+    assert "legalHoldName" in result.columns
+
+
+def test_list_include_legal_hold_membership_merges_in_and_concats_legal_hold_info(
+    runner,
+    cli_state,
+    get_all_users_success,
+    get_all_custodian_success,
+    get_all_matter_success,
+):
+    result = runner.invoke(
+        cli, ["users", "list", "--include-legal-hold-membership"], obj=cli_state
+    )
+
+    assert "Legal Hold #1,Legal Hold #2" in result.output
+    assert "123456789,987654321" in result.output
+
+
 def test_add_user_role_adds(
     runner, cli_state, get_user_id_success, get_available_roles_success
 ):