Feature/add user roles view (#329)

* trust user guide

* adding trust user guides

* user guides

* adding user guides

* user guides

* user guides

* adding tora.kozic cmd and --include-roles option

* PR feedback

* PR feedback

* user orgs cmds

* cmds to view orgs

* pass checks

* users and orgs integration tests

* style

* new command docs

* naming

* wording

* PR feedback

Author: tora-kozic

CHANGELOG.md

@@ -8,6 +8,18 @@ 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 option `--include-roles` on `code42 users list` that includes the roles for all users.
+
+- New command `code42 users show <username>` that prints all the details of that user.
+
+- New commands to view orgs
+    - `code42 users orgs list`
+    - `code42 users orgs show <org-uid>`
+
 ## 1.10.0 - 2021-10-05
 
 ### Added

docs/userguides/users.md

@@ -15,6 +15,18 @@ To change the information for one or more users, provide the user UID and update
 
 Apply [Code42's user roles](https://support.code42.com/Administrator/Cloud/Monitoring_and_managing/Roles_resources/Roles_reference#Standard_roles) to user accounts to provide administrators with the desired set of permissions.  Each role has associated permissions, limitations, and recommended use cases.
 
+#### View User Roles
+View a user's current roles and other details with the `show` command:
+```bash
+code42 users show "[email protected]"
+```
+Alternatively, pass the `--include-roles` flag to the `list ` command.  The following command will print a list of all active users and their current roles:
+```bash
+code42 users list --active --include-roles
+```
+
+#### Update User Roles
+
 Use the following command to add a role to a user:
 ```bash
 code42 users add-role --username "[email protected]" --role-name "Desktop User"
@@ -40,7 +52,18 @@ Similarly, use the `reactivate` and `bulk reactivate` commands to reactivate a u
 
 Use [Organizations](https://support.code42.com/Administrator/Cloud/Code42_console_reference/Organizations_reference) to group users together in the Code42 environment.
 
-Use the following example command to move a user into an organization associated with the `org_id` 1234567890:
+You'll need an organization's unique identifier number (UID) to move a user into it.  You can use the `list` command to view a list of all current user organizations, including UIDs:
+```bash
+code42 users orgs list
+```
+
+Use the `show` command to view all the details of a user organization.
+As an example, to print the details of an organization associated with the UID `123456789` in JSON format:
+```bash
+code42 users show 123456789 -f JSON
+```
+
+Once you've identified your organizations UID number, use the `move` command to move a user into that organization.  In the following example a user is moved into the organization associated with the UID `1234567890`:
 ```bash
 code42 users move --username [email protected] --org-id 1234567890
 ```

src/code42cli/cmds/users.py

@@ -1,6 +1,7 @@
 import click
 from pandas import DataFrame
 from pandas import json_normalize
+from py42.exceptions import Py42NotFoundError
 
 from code42cli.bulk import generate_template_cmd_factory
 from code42cli.bulk import run_bulk_process
@@ -17,12 +18,7 @@
 from code42cli.worker import create_worker_stats
 
 
-@click.group(cls=OrderedGroup)
-@sdk_options(hidden=True)
-def users(state):
-    """Manage users within your Code42 environment."""
-    pass
-
+username_arg = click.argument("username")
 
 org_uid_option = click.option(
     "--org-uid",
@@ -42,9 +38,15 @@ def users(state):
 )
 org_id_option = click.option(
     "--org-id",
-    help="The identifier for the organization to which the user will be moved.",
+    help="The unique identifier (UID) for the organization to which the user will be moved.",
     required=True,
 )
+include_legal_hold_option = click.option(
+    "--include-legal-hold-membership",
+    default=False,
+    is_flag=True,
+    help="Include legal hold membership in output.",
+)
 
 
 def role_name_option(help):
@@ -55,21 +57,33 @@ def username_option(help, required=False):
     return click.option("--username", help=help, required=required)
 
 
+@click.group(cls=OrderedGroup)
+@sdk_options(hidden=True)
+def users(state):
+    """Manage users within your Code42 environment."""
+    pass
+
+
 @users.command(name="list")
 @org_uid_option
 @role_name_option("Limit results to only users having the specified role.")
 @active_option
 @inactive_option
+@include_legal_hold_option
 @click.option(
-    "--include-legal-hold-membership",
-    default=False,
-    is_flag=True,
-    help="Include legal hold membership in output.",
+    "--include-roles", default=False, is_flag=True, help="Include user roles."
 )
 @format_option
 @sdk_options()
 def list_users(
-    state, org_uid, role_name, active, inactive, include_legal_hold_membership, format
+    state,
+    org_uid,
+    role_name,
+    active,
+    inactive,
+    include_legal_hold_membership,
+    include_roles,
+    format,
 ):
     """List users in your Code42 environment."""
     if inactive:
@@ -80,7 +94,11 @@ def list_users(
         if format == OutputFormat.TABLE
         else None
     )
-    df = _get_users_dataframe(state.sdk, columns, org_uid, role_id, active)
+    if include_roles and columns:
+        columns.append("roles")
+    df = _get_users_dataframe(
+        state.sdk, columns, org_uid, role_id, active, include_roles
+    )
     if include_legal_hold_membership:
         df = _add_legal_hold_membership_to_user_dataframe(state.sdk, df)
     if df.empty:
@@ -90,6 +108,29 @@ def list_users(
         formatter.echo_formatted_dataframe(df)
 
 
+@users.command("show")
+@username_arg
+@include_legal_hold_option
+@format_option
+@sdk_options()
+def show_user(state, username, include_legal_hold_membership, format):
+    """Show user details."""
+    columns = (
+        ["userUid", "status", "username", "orgUid", "roles"]
+        if format == OutputFormat.TABLE
+        else None
+    )
+    response = state.sdk.users.get_by_username(username, incRoles=True)
+    df = DataFrame.from_records(response["users"], columns=columns)
+    if include_legal_hold_membership and not df.empty:
+        df = _add_legal_hold_membership_to_user_dataframe(state.sdk, df)
+    if df.empty:
+        click.echo("No results found.")
+    else:
+        formatter = DataFrameOutputFormatter(format)
+        formatter.echo_formatted_dataframe(df)
+
+
 @users.command()
 @username_option("Username of the target user.")
 @role_name_option("Name of role to add.")
@@ -146,7 +187,7 @@ def update_user(
 
 
 @users.command()
-@click.argument("username")
+@username_arg
 @sdk_options()
 def deactivate(state, username):
     """Deactivate a user."""
@@ -155,7 +196,7 @@ def deactivate(state, username):
 
 
 @users.command()
-@click.argument("username")
+@username_arg
 @sdk_options()
 def reactivate(state, username):
     """Reactivate a user."""
@@ -183,10 +224,64 @@ def reactivate(state, username):
 @sdk_options()
 def change_organization(state, username, org_id):
     """Change the organization of the user with the given username
-    to the org with the given org ID."""
+    to the org with the given org UID."""
     _change_organization(state.sdk, username, org_id)
 
 
+@users.group(cls=OrderedGroup)
+@sdk_options(hidden=True)
+def orgs(state):
+    """Tools for viewing user orgs."""
+    pass
+
+
+def _get_orgs_header():
+    return {
+        "orgId": "ID",
+        "orgUid": "UID",
+        "orgName": "Name",
+        "status": "Status",
+        "parentOrgId": "Parent ID",
+        "parentOrgUid": "Parent UID",
+        "type": "Type",
+        "classification": "Classification",
+        "creationDate": "Creation Date",
+        "settings": "Settings",
+    }
+
+
+@orgs.command(name="list")
+@format_option
+@sdk_options()
+def list_orgs(
+    state, format,
+):
+    """List all orgs."""
+    pages = state.sdk.orgs.get_all()
+    formatter = OutputFormatter(format, _get_orgs_header())
+    orgs = [org for page in pages for org in page["orgs"]]
+    if orgs:
+        formatter.echo_formatted_list(orgs)
+    else:
+        click.echo("No orgs found.")
+
+
+@orgs.command(name="show")
+@click.argument("org-uid")
+@format_option
+@sdk_options()
+def show_org(
+    state, org_uid, format,
+):
+    """Show org details."""
+    formatter = OutputFormatter(format)
+    try:
+        response = state.sdk.orgs.get_by_uid(org_uid)
+        formatter.echo_formatted_list([response.data])
+    except Py42NotFoundError:
+        raise Code42CLIError(f"Invalid org UID {org_uid}.")
+
+
 @users.group(cls=OrderedGroup)
 @sdk_options(hidden=True)
 def bulk(state):
@@ -400,8 +495,10 @@ def _get_role_id(sdk, role_name):
         raise Code42CLIError(f"Role with name '{role_name}' not found.")
 
 
-def _get_users_dataframe(sdk, columns, org_uid, role_id, active):
-    users_generator = sdk.users.get_all(active=active, org_uid=org_uid, role_id=role_id)
+def _get_users_dataframe(sdk, columns, org_uid, role_id, active, include_roles):
+    users_generator = sdk.users.get_all(
+        active=active, org_uid=org_uid, role_id=role_id, incRoles=include_roles
+    )
     users_list = []
     for page in users_generator:
         users_list.extend(page["users"])
@@ -413,6 +510,7 @@ def _add_legal_hold_membership_to_user_dataframe(sdk, df):
     columns = ["legalHold.legalHoldUid", "legalHold.name", "user.userUid"]
 
     custodians = list(_get_all_active_hold_memberships(sdk))
+
     if len(custodians) == 0:
         return df