kepconfig.admin.user_groups

  1# -------------------------------------------------------------------------
  2# Copyright (c), PTC Inc. and/or all its affiliates. All rights reserved.
  3# See License.txt in the project root for
  4# license information.
  5# --------------------------------------------------------------------------
  6
  7r"""`user_groups` exposes an API to allow modifications (add, delete, modify) to 
  8user groups within the Kepware Administration User Manager through the Kepware Configuration API
  9"""
 10from typing import Union
 11from ..error import KepHTTPError, KepError
 12from ..connection import server
 13from ..utils import _url_parse_object
 14
 15
 16USERGROUPS_ROOT = '/admin/server_usergroups'
 17ENABLE_PROPERTY = 'libadminsettings.USERMANAGER_GROUP_ENABLED'
 18
 19def _create_url(user_group = None):
 20    '''Creates url object for the "server_usergroups" branch of Kepware's project tree. Used 
 21    to build a part of Kepware Configuration API URL structure
 22
 23    Returns the user group specific url when a value is passed as the user_group name.
 24    '''
 25    
 26    if user_group == None:
 27        return USERGROUPS_ROOT
 28    else:
 29        return '{}/{}'.format(USERGROUPS_ROOT, _url_parse_object(user_group))
 30
 31def add_user_group(server: server, DATA: Union[dict, list]) -> Union[bool, list]:
 32    '''Add a `"user group"` or multiple `"user group"` objects to Kepware User Manager by passing a 
 33    list of user groups to be added all at once.
 34
 35    :param server: instance of the `server` class
 36    :param DATA: Dict or List of Dicts of the user groups to add
 37
 38    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 39    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 40    endpoints added that failed.
 41
 42    :raises KepHTTPError: If urllib provides an HTTPError
 43    :raises KepURLError: If urllib provides an URLError
 44    '''
 45
 46    r = server._config_add(server.url + _create_url(), DATA)
 47    if r.code == 201: return True 
 48    elif r.code == 207:
 49        errors = [] 
 50        for item in r.payload:
 51            if item['code'] != 201:
 52                errors.append(item)
 53        return errors
 54    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 55
 56def del_user_group(server: server, user_group: str) -> bool:
 57    '''Delete a `"user group"` object in Kepware User Manager
 58    
 59    :param server: instance of the `server` class
 60    :param user_group: name of user group to delete
 61    
 62    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 63
 64    :raises KepHTTPError: If urllib provides an HTTPError
 65    :raises KepURLError: If urllib provides an URLError
 66    '''
 67
 68    r = server._config_del(server.url + _create_url(user_group))
 69    if r.code == 200: return True 
 70    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 71
 72def modify_user_group(server: server, DATA: dict, *, user_group: str = None) -> bool:
 73    '''Modify a `"user group"` object and it's properties in Kepware User Manager. If a `"user group"` is not provided as an input,
 74    you need to identify the user group in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 75    assume that is the user group that is to be modified.
 76
 77    :param server: instance of the `server` class
 78    :param DATA: Dict of the user group properties to be modified.
 79    :param user_group: *(optional)* name of user group to modify. Only needed if not existing in `"DATA"`
 80    
 81    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 82
 83    :raises KepHTTPError: If urllib provides an HTTPError
 84    :raises KepURLError: If urllib provides an URLError
 85    '''
 86    
 87    if user_group == None:
 88        try:
 89            r = server._config_update(server.url + _create_url(DATA['common.ALLTYPES_NAME']), DATA)
 90            if r.code == 200: return True 
 91            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 92        except KeyError as err:
 93            err_msg = 'Error: No User Group identified in DATA | Key Error: {}'.format(err)
 94            raise KepError(err_msg)
 95    else:
 96        r = server._config_update(server.url + _create_url(user_group), DATA)
 97        if r.code == 200: return True 
 98        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 99
100def get_user_group(server: server, user_group: str) -> dict:
101    '''Returns the properties of the `"user group"` object.
102    
103    :param server: instance of the `server` class
104    :param user_group: name of user group to retrieve
105    
106    :return: Dict of properties for the user group requested
107
108    :raises KepHTTPError: If urllib provides an HTTPError
109    :raises KepURLError: If urllib provides an URLError
110    '''
111
112    r = server._config_get(server.url + _create_url(user_group))
113    return r.payload
114
115def get_all_user_groups(server: server, *, options: dict = None) -> list:
116    '''Returns list of all `"user group"` objects and their properties.
117    
118    :param server: instance of the `server` class
119    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of user groups. Options are 'filter', 
120    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize.
121
122    :return: List of properties for all user groups
123
124    :raises KepHTTPError: If urllib provides an HTTPError
125    :raises KepURLError: If urllib provides an URLError
126    '''
127
128    r = server._config_get(f'{server.url}{_create_url()}', params= options)
129    return r.payload
130
131def enable_user_group(server: server, user_group: str) -> bool:
132    '''Enable the `"user group"`.
133    
134    :param server: instance of the `server` class
135    :param user_group: name of user group
136
137    :return: True - If a "HTTP 200 - OK" is received from Kepware server
138
139    :raises KepHTTPError: If urllib provides an HTTPError
140    :raises KepURLError: If urllib provides an URLError
141    '''
142    DATA = {ENABLE_PROPERTY: True}
143    return modify_user_group(server, DATA, user_group= user_group)
144
145def disable_user_group(server: server, user_group: str) -> bool:
146    '''Disable the `"user group"`.
147    
148    :param server: instance of the `server` class
149    :param user_group: name of user group
150
151    :return: True - If a "HTTP 200 - OK" is received from Kepware server
152
153    :raises KepHTTPError: If urllib provides an HTTPError
154    :raises KepURLError: If urllib provides an URLError
155    '''
156    DATA = {ENABLE_PROPERTY: False}
157    return modify_user_group(server, DATA, user_group= user_group)