kepconfig.datalogger.mapping

 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"""`mapping` exposes an API to allow modifications (add, delete, modify) to 
 8column mapping objects in a Datalogger log group within the Kepware Configuration API
 9"""
10
11from . import log_group as Log_Group
12from ..error import KepError, KepHTTPError
13from ..connection import server
14from ..utils import _url_parse_object
15
16MAPPING_ROOT = '/column_mappings'
17
18def _create_url(mapping = None):
19    '''Creates url object for the "column_mappings" branch of Kepware's project tree. Used 
20    to build a part of Kepware Configuration API URL structure
21
22    Returns the mapping specific url when a value is passed as the column_mapping name.
23    '''
24
25    if mapping == None:
26        return '{}'.format(MAPPING_ROOT)
27    else:
28        return '{}/{}'.format(MAPPING_ROOT, _url_parse_object(mapping))
29
30def modify_mapping(server: server, log_group: str, DATA: dict, *, mapping: str = None, force: bool = False) -> bool:
31    '''Modify a column `"mapping"` object and it's properties in Kepware. If a `"mapping"` is not provided as an input,
32    you need to identify the column mapping in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
33    assume that is the column mapping that is to be modified.
34
35    :param server: instance of the `server` class
36    :param log_group: name of log group for the mapping
37    :param DATA: Dict of the mapping properties to be modified.
38    :param mapping: *(optional)* column mapping to modify in the log group. Only needed if not existing in `"DATA"`
39    :param force: *(optional)* if True, will force the configuration update to the Kepware server
40
41    :return: True - If a "HTTP 200 - OK" is received from Kepware server
42
43    :raises KepHTTPError: If urllib provides an HTTPError
44    :raises KepURLError: If urllib provides an URLError
45    '''
46    
47    mapping_data = server._force_update_check(force, DATA)
48    
49    if mapping == None:
50        try:
51            r = server._config_update(server.url + Log_Group._create_url(log_group) + _create_url(mapping_data['common.ALLTYPES_NAME']), mapping_data)
52            if r.code == 200: return True 
53            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
54        except KeyError as err:
55            err_msg = 'Error: No column mapping identified in DATA | Key Error: {}'.format(err)
56            raise KepError(err_msg)
57    else:
58        r = server._config_update(server.url + Log_Group._create_url(log_group) + _create_url(mapping), mapping_data)
59        if r.code == 200: return True 
60        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
61
62def get_mapping(server: server, log_group: str, mapping: str) -> dict:
63    '''Returns the properties of the `"mapping"` object.
64    
65    :param server: instance of the `server` class
66    :param log_group: name of log group for the mapping
67    :param mapping: name of column mapping to retrieve properties
68    
69    :return: Dict of properties for the mapping object requested
70
71    :raises KepHTTPError: If urllib provides an HTTPError
72    :raises KepURLError: If urllib provides an URLError
73    '''
74    r = server._config_get(server.url + Log_Group._create_url(log_group) + _create_url(mapping))
75    return r.payload
76
77def get_all_mappings(server: server, log_group: str, *, options: dict = None) -> list:
78    '''Returns the properties of all column `"mapping"` objects for a log group.
79    
80    :param server: instance of the `server` class
81    :param log_group: name of log group for the mapping
82    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of mapping items. Options are 'filter', 
83    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'. Only used when exchange_name is not defined.
84
85    :return: list of properties for all mapping items in the log group requested
86
87    :raises KepHTTPError: If urllib provides an HTTPError
88    :raises KepURLError: If urllib provides an URLError
89    '''
90    r = server._config_get(f'{server.url}{Log_Group._create_url(log_group)}{_create_url()}', params= options)
91    return r.payload