Merge pull request #66 from adobe-apiplatform/v2

umapi-client 2.11

Author: adorton-adobe

docs/usage-instructions-v2.md

@@ -298,3 +298,175 @@ Each entry in `errors` would then be a dictionary giving
 the command that failed, the target user it failed on,
 and server information about the reason for the failure.
 
+# Performing Operations on User Groups
+
+User group operations work similarly to user operations.  The
+UserGroupAction class has a similar interface to the UserAction class.
+Currently, the UserGroupAction interface supports the following
+operations:
+
+* `create()` - create a new user group
+* `update()` - update the name and/or description of an existing user
+  group
+* `delete()` - delete a user group
+* `add_users()` - add users to a user group
+* `remove_users()` - remove users from a user group
+* `add_to_products()` - add one or more product profiles to a user group
+* `remove_from_products()` - remove one or more product profiles from
+  a user group
+
+## Step 1: Specify the User Group
+
+The group name is required to create new UserGroupAction object.  For a
+new user group, this should be the name of the new group.  To perform
+an operation on an existing group, specify the name of that group.
+
+Group names:
+
+* Must be unique to the Adobe organization
+* May not start with an underscore ("_") - groups with names that begin
+  with an underscore are reserved for Adobe use
+* Must be no longer than 255 characters
+
+Group name is the only required parameter.  An optional `requestID` can
+be passed to make it easier to connect action requests with API
+responses.
+
+```python
+from umapi_client import UserGroupAction
+group = UserGroupAction(group_name="Employees")
+```
+
+## Step 2: Specify the Operations
+
+### Create a New Group
+
+User Groups are created with `UserGroupAction.create()`.  Two
+optional parameters can be passed:
+
+* `description` - a short description of the group
+* `option` - an option specifying how to handle existing groups with
+  the same name.  Specify one of two `IfAlreadyExistsOptions` variants:
+  * `ignoreIfAlreadyExists` - do not attempt to create the group if a
+    group with the same name already exists.  Other operations for the
+    UserGroupAction object will be performed.
+  * `updateIfAlreadyExists` - update the description if it is different
+    than the description currently applied to the user group
+  * **Default**: `ignoreIfAlreadyExists`
+
+Example:
+
+```python
+group = UserGroupAction(group_name="Employees")
+group.create(description="A user group just for employees",
+             option=IfAlreadyExistsOptions.updateIfAlreadyExists)
+```
+
+### Update a Group
+
+Updates are done using `UserGroupAction.update()`.  Two optional
+parameters can be passed:
+
+* `name` - the new name of the user group
+* `description` - the new description of the user group
+
+Both parameters default to `None`.  If either parameter is omitted,
+that field will not be updated.  If neither parameter is specified,
+`update()` will throw an `ArgumentException`.
+
+Example:
+
+```python
+group = UserGroupAction(group_name="Employees")
+group.update(name="Employees and Contractors",
+             description="Full-time Employees and Contractors")
+```
+
+### Delete a Group
+
+User groups can be deleted with `UserGroupAction.delete()`.  The
+`delete()` method takes no parameters.
+
+```python
+group = UserGroupAction(group_name="Employees and Contractors")
+group.delete()
+```
+
+### Manage Users in Group
+
+The User Management API supports the bulk management of users for a
+specific group.  This functionality is exposed in the
+`UserGroupAction` methods `add_users()` and `remove_users()`.
+
+A list of user IDs to add or remove must to provided to either method.
+
+Add users example:
+
+```python
+group = UserGroupAction(group_name="Employees and Contractors")
+add_users = ["[email protected]", "[email protected]"]
+group.add_users(users=add_users)
+```
+
+Remove users example:
+
+```python
+group = UserGroupAction(group_name="Employees and Contractors")
+remove_users = ["[email protected]", "[email protected]"]
+group.remove_users(users=remove_users)
+```
+
+### Manage Product Profiles for a Group
+
+The `UserGroupAction` interface can also be used to manage the product
+profiles associated with a user group.  Adding a product profile to a
+group will grant all members of that group access to the profile's
+associated product plan.
+
+The `add_to_products()` method adds one or more product profiles to a
+user group.  `remove_from_products()` removes one or more profiles from
+a user group.
+
+Both methods take two parameters.  These are mutually exclusive -
+either method will throw an `ArgumentError` if both parameters are
+specified (also, if neither are specified).
+
+* `products` list of product profiles to add/remove
+* `all_products` boolean that will add/remove all product profiles to a
+  user group
+
+Add profile example:
+
+```python
+group = UserGroupAction(group_name="Employees and Contractors")
+profiles_to_add = ["Default All Apps plan - 100 GB configuration",
+                   "Default Acrobat Pro DC configuration"]
+group.add_to_products(products=profiles_to_add)
+```
+
+Remove profile example:
+
+```python
+group = UserGroupAction(group_name="Employees and Contractors")
+profiles_to_remove = ["Default All Apps plan - 100 GB configuration",
+                      "Default Acrobat Pro DC configuration"]
+group.remove_from_products(products=profiles_to_add)
+```
+
+## Step 3: Submit to the UMAPI server
+
+`UserGroupAction` objects can be used with the same conn methods as
+`UserAction` objects.  See "Step 3" in the User Management section of
+this document for more information.
+
+Here is a complete example that creates a new user group and adds a
+list of users to it:
+
+```python
+group = UserGroupAction(group_name="New User Group")
+group.create(description="A new user group",
+             option=IfAlreadyExistsOptions.updateIfAlreadyExists)
+group.add_users(users=["[email protected]", "[email protected]"])
+
+result = conn.execute_single(group)
+```

tests/conftest.py

@@ -40,7 +40,7 @@
 class MockResponse:
     def __init__(self, status=200, body=None, headers=None, text=None):
         self.status_code = status
-        self.body = body if body else {}
+        self.body = body if body is not None else {}
         self.headers = headers if headers else {}
         self.text = text if text else ""
 

tests/test_connections.py

@@ -30,7 +30,7 @@
 
 from umapi_client import Connection
 from umapi_client import ArgumentError, UnavailableError, ServerError, RequestError
-from umapi_client import UserAction, GroupTypes, IdentityTypes, RoleTypes
+from umapi_client import UserAction, GroupTypes, IdentityTypes, RoleTypes, UserGroupAction
 from umapi_client import __version__ as umapi_version
 from umapi_client.auth import Auth
 
@@ -451,3 +451,12 @@ def test_split_remove_all():
                                                             'G10']}},
                                        {'add': {'product': ['G11']}}],
                                 'user': '[email protected]'}
+
+
+def test_split_group_action():
+    user_template = six.text_type("user.{}@example.com")
+    add_users = [user_template.format(n+1) for n in range(0, 25)]
+    group = UserGroupAction(group_name="Test Group")
+    group.add_users(users=add_users)
+    assert group.maybe_split_groups(10) is True
+    assert len(group.commands) == 3

tests/test_functional.py

@@ -22,9 +22,10 @@
 
 import pytest
 import six
+import mock
 
-from conftest import mock_connection_params
-from umapi_client import ArgumentError
+from conftest import mock_connection_params, MockResponse
+from umapi_client import ArgumentError, RequestError
 from umapi_client import Connection
 from umapi_client import IdentityTypes, GroupTypes, RoleTypes
 from umapi_client import UserAction, UserGroupAction
@@ -354,7 +355,7 @@ def test_delete_account_adobeid():
 def test_add_to_products():
     group = UserGroupAction(group_name="SampleUsers")
     group.add_to_products(products=["Photoshop", "Illustrator"])
-    assert group.wire_dict() == {"do": [{"add": {"product": ["Photoshop", "Illustrator"]}}],
+    assert group.wire_dict() == {"do": [{"add": {"productConfiguration": ["Photoshop", "Illustrator"]}}],
                                  "usergroup": "SampleUsers"}
 
 
@@ -374,7 +375,7 @@ def test_add_to_products_all_error():
 def test_remove_from_products():
     group = UserGroupAction(group_name="SampleUsers")
     group.remove_from_products(products=["Photoshop", "Illustrator"])
-    assert group.wire_dict() == {"do": [{"remove": {"product": ["Photoshop", "Illustrator"]}}],
+    assert group.wire_dict() == {"do": [{"remove": {"productConfiguration": ["Photoshop", "Illustrator"]}}],
                                  "usergroup": "SampleUsers"}
 
 
@@ -424,6 +425,57 @@ def test_remove_users_error():
         group.remove_users(users=[])
 
 
+def test_create_user_group():
+    group = UserGroupAction(group_name="Test Group")
+    group.create(description="Test Group Description")
+    assert group.wire_dict() == {'do': [{'createUserGroup': {'option': 'ignoreIfAlreadyExists',
+                                                             'description': 'Test Group Description'}}],
+                                 'usergroup': 'Test Group'}
+
+
+def test_create_user_group_error():
+    group = UserGroupAction(group_name="Test Group")
+    group.create(description="Test Group Description")
+    with pytest.raises(ArgumentError):
+        group.create()
+
+
+def test_invalid_user_group_name():
+    group = UserGroupAction(group_name="_Invalid Group Name")
+    with pytest.raises(ArgumentError):
+        group.create()
+    with pytest.raises(ArgumentError):
+        group.update(name="_Another invalid group name")
+
+
+def test_long_user_group_name():
+    long_group_name = """
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna 
+    aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
+    Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur 
+    sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."""
+    group = UserGroupAction(group_name=long_group_name)
+    with pytest.raises(ArgumentError):
+        group.create()
+    with pytest.raises(ArgumentError):
+        group.update(name=long_group_name)
+
+
+def test_update_user_group():
+    group = UserGroupAction(group_name="Test Group")
+    group.update(name="Renamed Test Group", description="Test Group Description")
+    assert group.wire_dict() == {'do': [{'updateUserGroup': {'name': 'Renamed Test Group',
+                                                             'description': 'Test Group Description'}}],
+                                 'usergroup': 'Test Group'}
+
+
+def test_delete_user_group():
+    group = UserGroupAction("Test Group")
+    group.delete()
+    assert group.wire_dict() == {'do': [{'deleteUserGroup': {}}],
+                                 'usergroup': 'Test Group'}
+
+
 def test_query_users():
     conn = Connection(**mock_connection_params)
     query = UsersQuery(conn)
@@ -432,3 +484,4 @@ def test_query_users():
     query = UsersQuery(conn, in_group="test", in_domain="test.com", direct_only=False)
     assert query.url_params == ["test"]
     assert query.query_params == {"directOnly": False, "domain": "test.com"}
+

tests/test_live.py

@@ -28,7 +28,13 @@
 
 import umapi_client
 
-# this test relies on a sensitive configuraition
+# PyCharm runs tests by default in the tests directory,
+# but setup.py runs them in the umapi_client directory,
+# so make sure we can run either way
+if os.getcwd().find("tests"):
+    os.chdir("..")
+
+# this test relies on a sensitive configuration
 config_file_name = "local/live_configuration.yaml"
 pytestmark = pytest.mark.skipif(not os.access(config_file_name, os.R_OK),
                                 reason="Live config file '{}' not found.".format(config_file_name))
@@ -43,7 +49,7 @@ def config():
     with open(config_file_name, "r") as f:
         conf_dict = yaml.load(f)
     creds = conf_dict["test_org"]
-    conn = umapi_client.Connection(org_id=creds["org_id"], auth_dict=creds)
+    conn = umapi_client.Connection(ims_host='ims-na1-stg1.adobelogin.com', user_management_endpoint='https://usermanagement-stage.adobe.io/v2/usermanagement', org_id=creds["org_id"], auth_dict=creds)
     return conn, conf_dict
 
 
@@ -79,14 +85,42 @@ def test_list_users(config):
     logging.info("Found %d users.", user_count)
 
 
+def test_list_user_groups(config):
+    conn, params = config
+    groups = umapi_client.UserGroupsQuery(connection=conn)
+    group_count = 0
+    for group in groups:
+        name = group.get("name")
+        admin_name = group.get("adminGroupName")
+        member_count = group.get("userCount", 0)
+        admin_count = int(group.get("adminCount", "-1"))
+        logging.info("Group %s has %d members.", name, member_count)
+        if admin_name:
+            logging.info("Group %s has admin group %s with %d members.", name, admin_name, admin_count)
+            # logging.info("Adding test user as admin.")
+            # user = umapi_client.UserAction(id_type=params["test_user"]["type"],
+            #                                email=params["test_user"]["email"],
+            #                                username=params["test_user"]["username"])
+            # user.add_to_groups([admin_name])
+            # assert (0, 1, 1) == conn.execute_single(user, immediate=True)
+            users = umapi_client.UsersQuery(connection=conn, in_group=admin_name)
+            logging.info("Admin group %s has: %s", admin_name, users.all_results())
+        assert member_count >= 0
+        group_count += 1
+    logging.info("Found %d groups.", group_count)
+    groups.reload()
+    group_count_2 = len(groups.all_results())
+    assert group_count == group_count_2
+
+
 def test_list_groups(config):
     conn, params = config
     groups = umapi_client.GroupsQuery(connection=conn)
     group_count = 0
     for group in groups:
         name = group.get("groupName")
         member_count = group.get("memberCount", -1)
-        logging.info("Group %s has %d members.", name, member_count)
+        logging.info("Group %s has %d members: %s", name, member_count, group)
         assert member_count >= 0
         group_count += 1
     logging.info("Found %d groups.", group_count)
@@ -112,3 +146,24 @@ def test_rename_user(config):
     user.update(first_name="Rodney", last_name="Danger")
     user.update(first_name=params["test_user"]["firstname"], last_name=params["test_user"]["lastname"])
     assert (0, 1, 1) == conn.execute_single(user, immediate=True)
+
+def test_create_user_group(config):
+    conn, params = config
+    usergroups = umapi_client.UserGroups(conn)
+    groupName = "Test-Dummy-Group"
+    groupID = usergroups.getGroupIDByName(groupName)
+    if groupID:
+        usergroups.delete(groupName)
+    result = usergroups.create("Test-Dummy-Group")
+    assert result.name == "Test-Dummy-Group"
+
+def test_remove_user_group(config):
+    conn, params = config
+    usergroups = umapi_client.UserGroups(conn)
+    groupName = "Test-Dummy-Group"
+    groupID = usergroups.getGroupIDByName(groupName)
+    if not groupID:
+        result = usergroups.create(groupName)
+        groupID = result.groupid
+    usergroups.delete(groupID)
+    assert usergroups.getGroupIDByName(groupName) == None