added support for core/admins.Administrators (#155)

cterasdk/core/__init__.py

@@ -14,6 +14,7 @@
     'servers',
     'devices',
     'session',
+    'admins',
     'users',
     'cloudfs',
     'zones',

cterasdk/core/admins.py

@@ -0,0 +1,139 @@
+import logging
+
+from .base_command import BaseCommand
+from ..exception import CTERAException, ObjectNotFoundException
+from ..common import Object, DateTimeUtils
+from ..common import union
+from . import query
+
+
+class Administrators(BaseCommand):
+    """
+    Portal Global Administrators User Management APIs
+    """
+
+    default = ['name']
+
+    def _get_entire_object(self, name):
+        ref = f'/administrators/{name}'
+        try:
+            return self._portal.get(ref)
+        except CTERAException as error:
+            raise CTERAException('Failed to get the user', error)
+
+    def get(self, name, include=None):
+        """
+        Get a Global Administrator user account
+
+        :param str name: Global administrator username
+        :param list[str] include: List of fields to retrieve, defaults to ['name']
+        :return: The user account, including the requested fields
+        """
+        baseurl = f'/administrators/{name}'
+        include = union(include or [], Administrators.default)
+        include = ['/' + attr for attr in include]
+        user_object = self._portal.get_multi(baseurl, include)
+        if user_object.name is None:
+            raise ObjectNotFoundException('Could not find user', baseurl, username=name)
+        return user_object
+
+    def list_admins(self, include=None):
+        """
+        List local administrators
+
+        :param list[str] include: List of fields to retrieve, defaults to ['name']
+        :return: Iterator for local administrators
+        :rtype: cterasdk.lib.iterator.Iterator
+        """
+        include = union(include or [], Administrators.default)
+        param = query.QueryParamBuilder().include(include).build()
+        return query.iterator(self._portal, '/administrators', param)
+
+    def add(self, name, email, first_name, last_name, password, role, company=None, comment=None, password_change=False):
+        """
+        Create a Global Administrator
+
+        :param str name: User name for the new GlobalAdmin
+        :param str email: E-mail address of the new GlobalAdmin
+        :param str first_name: The first name of the new GlobalAdmin
+        :param str last_name: The last name of the new GlobalAdmin
+        :param str password: Password for the new GlobalAdmin
+        :param cterasdk.core.enum.Role role: User role of the new GlobalAdmin
+        :param str,optional company: The name of the company of the new GlobalAdmin, defaults to None
+        :param str,optional comment: Additional comment for the new GlobalAdmin, defaults to None
+        :param variable,optional password_change:
+            Require the user to change the password on the first login.
+            Pass datetime.date for a specific date, integer for days from creation, or True for immediate , defaults to False
+        """
+        param = Object()
+        param._classname = "PortalAdmin"  # pylint: disable=protected-access
+        param.name = name
+        param.email = email
+        param.firstName = first_name
+        param.lastName = last_name
+        param.password = password
+        param.role = role
+        param.company = company
+        param.comment = comment
+        if password_change:
+            param.requirePasswordChangeOn = DateTimeUtils.get_expiration_date(password_change).strftime('%Y-%m-%d')
+
+        logging.getLogger().info('Creating a global administrator. %s', {'user': name})
+        response = self._portal.add('/administrators', param)
+        logging.getLogger().info('Global administrator created. %s', {'user': name, 'email': email, 'role': role})
+
+        return response
+
+    def modify(self, current_username, new_username=None, email=None, first_name=None,
+               last_name=None, password=None, role=None, company=None, comment=None):
+        """
+        Modify a Global Administrator user account
+
+        :param str current_username: The current GlobalAdmin username
+        :param str,optional new_username: New name
+        :param str,optional email: E-mail address
+        :param str,optional first_name: First name
+        :param str,optional last_name: Last name
+        :param str,optional password: Password
+        :param cterasdk.core.enum.Role,optional role: User role
+        :param str,optional company: Company name
+        :param str,optional comment: Comment
+        """
+        user = self._get_entire_object(current_username)
+        if new_username:
+            user.name = new_username
+        if email:
+            user.email = email
+        if first_name:
+            user.firstName = first_name
+        if last_name:
+            user.lastName = last_name
+        if password:
+            user.password = password
+        if role:
+            user.role = role
+        if company is not None:
+            user.company = company
+        if comment is not None:
+            user.comment = comment
+
+        try:
+            response = self._portal.put('/administrators/' + current_username, user)
+            logging.getLogger().info("User modified. %s", {'username': user.name})
+            return response
+        except CTERAException as error:
+            logging.getLogger().error("Failed to modify user.")
+            raise CTERAException('Failed to modify user', error)
+
+    def delete(self, name):
+        """
+        Delete a Global Administrator
+
+        :param str username: Global administrator username
+        """
+        logging.getLogger().info('Deleting user. %s', {'user': name})
+        baseurl = f'/administrators/{name}'
+        response = self._portal.execute(baseurl, 'delete', True)
+        logging.getLogger().info('User deleted. %s', {'user': name})
+
+        return response

cterasdk/object/Portal.py

@@ -27,13 +27,15 @@
 from ..core import templates
 from ..core import uri
 from ..core import files
+from ..core import admins
 
 
 class Portal(CTERAHost):  # pylint: disable=too-many-instance-attributes
     """
     Parent class for communicating with the Portal through either GlobalAdmin or ServicesPortal
 
     :ivar cterasdk.core.users.Users users: Object holding the Portal user APIs
+    :ivar cterasdk.core.admins.Administrators admins: Object holding the Portal GlobalAdmin users APIs
     :ivar cterasdk.core.plans.Plans plans: Object holding the Plan APIs
     :ivar cterasdk.core.reports.Reports reports: Object holding the Portal reports APIs
     :ivar cterasdk.core.devices.Devices devices: Object holding the Portal devices APIs
@@ -58,6 +60,7 @@ def __init__(self, host, port, https):
         super().__init__(host, port, https)
         self._session = session.Session(self.host(), self.context)
         self.users = users.Users(self)
+        self.admins = admins.Administrators(self)
         self.reports = reports.Reports(self)
         self.plans = plans.Plans(self)
         self.devices = devices.Devices(self)
@@ -104,6 +107,7 @@ def backups_base_path(self):
     @property
     def _omit_fields(self):
         return super()._omit_fields + [
+            'admins',
             'users',
             'reports',
             'plans',

docs/source/api/cterasdk.core.admins.rst

@@ -0,0 +1,7 @@
+cterasdk.core.admins module
+===========================
+
+.. automodule:: cterasdk.core.admins
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/api/cterasdk.core.rst

@@ -44,5 +44,6 @@ Submodules
    cterasdk.core.taskmgr
    cterasdk.core.templates
    cterasdk.core.types
+   cterasdk.core.admins
    cterasdk.core.users
    cterasdk.core.zones

docs/source/user_guides/Portal/GlobalAdmin.rst

@@ -623,6 +623,48 @@ Antivirus Servers
 .. automethod:: cterasdk.core.antivirus.AntivirusServers.unsuspend
    :noindex:
 
+
+Global Administrators
+---------------------
+
+.. automethod:: cterasdk.core.admins.Administrators.list_admins
+   :noindex:
+
+.. code-block:: python
+
+   """list all global admins"""
+   for admin in admin.admins.list_global_administrators():
+       print(admin.name)
+
+   for admin in admin.admins.list_global_administrators(include=['name', 'email', 'firstName', 'lastName']):
+       print(admin)
+
+.. automethod:: cterasdk.core.admins.Administrators.add
+   :noindex:
+
+.. code-block:: python
+
+   """Create a global admin"""
+   admin.admins.add('bruce', 'bruce.wayne@we.com', 'Bruce', 'Wayne', 'G0th4amCity!')
+
+.. automethod:: cterasdk.core.admins.Administrators.modify
+   :noindex:
+
+.. code-block:: python
+
+   """Modify a global admin"""
+   admin.admins.modify('bruce', 'bwayne@we.com', 'Bruce', 'Wayne', 'Str0ngP@ssword!', 'Wayne Enterprises')
+
+
+.. automethod:: cterasdk.core.admins.Administrators.delete
+   :noindex:
+
+.. code-block:: python
+
+   """Delete a global admin"""
+   admin.admins.delete('alice')
+
+
 Users
 -----