kepconfig.datalogger.log_group

  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"""`log_group` exposes an API to allow modifications (add, delete, modify) to 
  8log group objects in DataLogger within the Kepware Configuration API
  9"""
 10from typing import Union
 11from ..connection import KepServiceResponse, server
 12from ..error import KepError, KepHTTPError
 13from ..utils import _url_parse_object
 14
 15ENABLE_PROPERTY = 'datalogger.LOG_GROUP_ENABLED'
 16LOG_GROUP_ROOT = '/project/_datalogger/log_groups'
 17SERVICES_ROOT = '/services'
 18def _create_url(log_group = None):
 19    '''Creates url object for the "log_group" branch of Kepware's project tree. Used 
 20    to build a part of Kepware Configuration API URL structure
 21
 22    Returns the agent specific url when a value is passed as the agent name.
 23    '''
 24
 25    if log_group == None:
 26        return '{}'.format(LOG_GROUP_ROOT)
 27    else:
 28        return '{}/{}'.format(LOG_GROUP_ROOT, _url_parse_object(log_group))
 29
 30
 31def add_log_group(server: server, DATA: Union[dict, list]) -> Union[bool, list]:
 32    '''Add a `"log group"` or multiple `"log groups"` objects to Kepware's DataLogger. It can be used 
 33    to pass a list of log groups to be added all at once.
 34
 35    :param server: instance of the `server` class
 36    :param DATA: Dict or a list of the log groups to add through Kepware Configuration API
 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    log groups 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_log_group(server: server, log_group: str) -> bool:
 57    '''Delete a `"log group"` object in Kepware's Datalogger.
 58    
 59    :param server: instance of the `server` class
 60    :param log_group: name of log 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    r = server._config_del(server.url + _create_url(log_group))
 68    if r.code == 200: return True 
 69    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 70
 71def modify_log_group(server: server, DATA: dict, *, log_group: str = None, force: bool = False) -> bool:
 72    '''Modify a `"log group"` object and it's properties in Kepware's Datalogger. If a `"log group"` is not provided as an input,
 73    you need to identify the log group in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 74    assume that is the log group that is to be modified.
 75
 76    :param server: instance of the `server` class
 77    :param DATA: Dict of the log group properties to be modified.
 78    :param log_group: *(optional)* name of log group to modify. Only needed if not existing in `"DATA"`
 79    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 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    log_group_data = server._force_update_check(force, DATA)
 88    
 89    if log_group == None:
 90        try:
 91            r = server._config_update(server.url + _create_url(log_group_data['common.ALLTYPES_NAME']), log_group_data)
 92            if r.code == 200: return True 
 93            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 94        except KeyError as err:
 95            err_msg = 'Error: No log group identified in DATA | Key Error: {}'.format(err)
 96            raise KepError(err_msg)
 97    else:
 98        r = server._config_update(server.url + _create_url(log_group), log_group_data)
 99        if r.code == 200: return True 
100        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
101
102def get_log_group(server: server, log_group: str) -> dict:
103    '''Returns the properties of the `"log group"` object.
104    
105    :param server: instance of the `server` class
106    :param log_group: name of log group to retrieve
107
108    :return: Dict of properties for the log group requested
109
110    :raises KepHTTPError: If urllib provides an HTTPError
111    :raises KepURLError: If urllib provides an URLError
112    '''
113    r = server._config_get(server.url + _create_url(log_group))
114    return r.payload
115
116def get_all_log_groups(server: server, *, options: dict = None) -> list:
117    '''Returns the properties of all log group objects for Kepware's Datalogger. Returned object is JSON list.
118    
119    :param server: instance of the `server` class
120    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of log groups. Options are 'filter', 
121    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'. Only used when exchange_name is not defined.
122
123    :return: list of properties for all log groups requested
124
125    :raises KepHTTPError: If urllib provides an HTTPError
126    :raises KepURLError: If urllib provides an URLError
127    '''
128    r = server._config_get(f'{server.url}{_create_url()}', params= options)
129    return r.payload
130
131def enable_log_group(server: server, log_group: str) -> bool:
132    '''Enable the `"log group"`.
133    
134    :param server: instance of the `server` class
135    :param log_group: name of log group to enable
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_log_group(server, DATA, log_group= log_group)
144
145def disable_log_group(server: server, log_group: str) -> bool:
146    '''Disable the log group. Returned object is JSON.
147    
148    :param server: instance of the `server` class
149    :param log_group: name of log group to enable
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_log_group(server, DATA, log_group= log_group)
158
159def reset_column_mapping_service(server: server, log_group: str, job_ttl: int = None) -> KepServiceResponse:
160    '''Executes a ResetColumnMapping serivce call to the log group
161
162    :param server: instance of the `server` class
163    :param log_group: name of log group to enable
164    :param job_ttl: *(optional)* Determines the number of seconds a job instance will exist following completion.
165
166    :return: `KepServiceResponse` instance with job information
167    
168    :raises KepHTTPError: If urllib provides an HTTPError (If not HTTP code 202 [Accepted] or 429 [Too Busy] returned)
169    :raises KepURLError: If urllib provides an URLError
170    '''
171
172    url = server.url + _create_url(log_group) + SERVICES_ROOT + '/ResetColumnMapping'
173    job = server._kep_service_execute(url, None, job_ttl)
174    return job