kepconfig.datalogger.triggers

  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"""`triggers` exposes an API to allow modifications (add, delete, modify) to 
  8trigger objects in a Datalogger log group within the Kepware Configuration API
  9"""
 10
 11from typing import Union
 12from . import log_group as Log_Group
 13from ..error import KepError, KepHTTPError
 14from ..connection import server
 15from ..utils import _url_parse_object
 16
 17TRIGGERS_ROOT = '/triggers'
 18
 19def _create_url(trigger = None):
 20    '''Creates url object for the "trigger" branch of Kepware's project tree. Used 
 21    to build a part of Kepware Configuration API URL structure
 22
 23    Returns the trigger specific url when a value is passed as the trigger name.
 24    '''
 25
 26    if trigger == None:
 27        return '{}'.format(TRIGGERS_ROOT)
 28    else:
 29        return '{}/{}'.format(TRIGGERS_ROOT, _url_parse_object(trigger))
 30
 31
 32def add_trigger(server: server, log_group: str, DATA: Union[dict, list]) -> Union[bool, list]:
 33    '''Add a `"trigger"` or multiple `"trigger"` objects to a log group in Kepware's Datalogger. It can 
 34    be used to pass a list of triggers to be added all at once.
 35
 36    :param server: instance of the `server` class
 37    :param log_group: name of log group for the trigger items
 38    :param DATA: Dict or a list of the trigger items to add through Kepware Configuration API
 39
 40    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 41    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 42    triggers added that failed.
 43
 44    :raises KepHTTPError: If urllib provides an HTTPError
 45    :raises KepURLError: If urllib provides an URLError
 46    '''
 47
 48    r = server._config_add(server.url + Log_Group._create_url(log_group) + _create_url(), DATA)
 49    if r.code == 201: return True
 50    elif r.code == 207:
 51        errors = [] 
 52        for item in r.payload:
 53            if item['code'] != 201:
 54                errors.append(item)
 55        return errors 
 56    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 57
 58def del_trigger(server: server, log_group: str, trigger: str) -> bool:
 59    '''Delete a `"trigger"` object of a log group in Kepware's Datalogger.
 60    
 61    :param server: instance of the `server` class
 62    :param log_group: name of log group for the trigger items
 63    :param trigger: name of trigger to delete
 64
 65    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 66
 67    :raises KepHTTPError: If urllib provides an HTTPError
 68    :raises KepURLError: If urllib provides an URLError
 69    '''
 70    r = server._config_del(server.url + Log_Group._create_url(log_group) + _create_url(trigger))
 71    if r.code == 200: return True
 72    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 73
 74def modify_trigger(server: server, log_group: str, DATA: dict, *, trigger: str = None, force: bool = False)  -> bool:
 75    '''Modify a `"trigger"` object and it's properties in Kepware. If a `"trigger"` is not provided as an input,
 76    you need to identify the trigger in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 77    assume that is the trigger that is to be modified.
 78
 79    :param server: instance of the `server` class
 80    :param log_group: name of log group for the trigger items
 81    :param DATA: Dict of the trigger properties to be modified.
 82    :param trigger: *(optional)* name of trigger to modify in the log group. Only needed if not existing in `"DATA"`
 83    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 84
 85    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 86
 87    :raises KepHTTPError: If urllib provides an HTTPError
 88    :raises KepURLError: If urllib provides an URLError
 89    '''
 90    
 91    trigger_data = server._force_update_check(force, DATA)
 92    
 93    if trigger == None:
 94        try:
 95            r = server._config_update(server.url + Log_Group._create_url(log_group) + _create_url(trigger_data['common.ALLTYPES_NAME']), trigger_data)
 96            if r.code == 200: return True 
 97            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 98        except KeyError as err:
 99            err_msg = 'Error: No trigger identified in DATA | Key Error: {}'.format(err)
100            raise KepError(err_msg)
101        # except:
102        #     return 'Error: Error with {}'.format(inspect.currentframe().f_code.co_name)
103    else:
104        r = server._config_update(server.url + Log_Group._create_url(log_group) + _create_url(trigger), trigger_data)
105        if r.code == 200: return True 
106        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
107
108def get_trigger(server, log_group, trigger) -> dict:
109    '''Returns the properties of the `"trigger"` object.
110    
111    :param server: instance of the `server` class
112    :param log_group: name of log group for the trigger items
113    :param trigger: name of trigger to retrieve
114
115    :return: Dict of properties for the trigger requested
116
117    :raises KepHTTPError: If urllib provides an HTTPError
118    :raises KepURLError: If urllib provides an URLError
119    '''
120    r = server._config_get(server.url + Log_Group._create_url(log_group) + _create_url(trigger))
121    return r.payload
122
123def get_all_triggers(server: server, log_group: str, *, options: dict = None) -> list:
124    '''Returns the properties of all `"trigger"` objects for a log group.
125    
126    :param server: instance of the `server` class
127    :param log_group: name of log group for the trigger items
128
129    :return: Dict of properties for the trigger requested
130
131    :raises KepHTTPError: If urllib provides an HTTPError
132    :raises KepURLError: If urllib provides an URLError
133    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of triggers. Options are 'filter', 
134    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'. Only used when exchange_name is not defined.
135
136    :return: list of properties for all triggers in the log group requested
137
138    :raises KepHTTPError: If urllib provides an HTTPError
139    :raises KepURLError: If urllib provides an URLError
140    '''
141    r = server._config_get(f'{server.url}{Log_Group._create_url(log_group)}{_create_url()}', params= options)
142    return r.payload