zenoss.py

'''Python module to work with the Zenoss JSON API

[modification] Steve Goossens:
* added authentication by client cert
* changed __init__ constructor to allow auth by username/password or cert
* changed get_events method parameters to match query method
* changed get_events method to call API iteratively to get events in batches
  if there is a server-imposed query limit
* added EventState enumeration
* added EventSeverity enumeration
'''

import ast
import re
import json
import logging
import requests

log = logging.getLogger(__name__)  # pylint: disable=C0103
requests.packages.urllib3.disable_warnings()

ROUTERS = {'MessagingRouter': 'messaging',
           'EventsRouter': 'evconsole',
           'EventClassesRouter': 'Events/evclasses',
           'ProcessRouter': 'process',
           'ServiceRouter': 'service',
           'DeviceRouter': 'device',
           'ManufacturersRouter': 'manufacturers',
           'NetworkRouter': 'network',
           'PropertiesRouter': 'properties',
           'TemplateRouter': 'template',
           'DetailNavRouter': 'detailnav',
           'ReportRouter': 'report',
           'MibRouter': 'mib',
           'TriggersRouter': 'triggers',
           'ZenPackRouter': 'zenpack'}


class ZenossException(Exception):
    '''Custom exception for Zenoss
    '''
    pass


class EventState:
    """
    eventState:
    0 = new
    1 = acknowledged
    2 = suppressed
    3 = closed
    4 = cleared
    5 = dropped
    6 = aged
    """
    new, acknowledged, suppressed, closed, cleared, dropped, aged = range(7)


class EventSeverity:
    """
    0 = clear
    1 = debug
    2 = info
    3 = warning
    4 = error
    5 = critical
    """
    clear, debug, info, warning, error, critical = range(6)


class ProductionState:
    production = 1000
    pre_production = 500
    test = 400
    maintenance = 300
    decommissioned = -1


class Zenoss(object):
    '''A class that represents a connection to a Zenoss server
    '''
    def __init__(self,
                 host=None,
                 username=None,
                 password=None,
                 cert=None,
                 ssl_verify=True
                 ):

        self.__host = host
        self.__session = requests.Session()
        # auth by username/password or client cert
        if username and password:
            self.__session.auth = (username, password)
        elif cert:
            self.__session.cert = cert
        else:
            self.__session.auth = None
        # host SSL verification enable/disabled
        self.__session.verify = ssl_verify
        # reset count
        self.__req_count = 0

    def __router_request(self, router, method, data=None, uri=None):
        '''Internal method to make calls to the Zenoss request router
        '''
        if router not in ROUTERS:
            raise ZenossException('Router "' + router + '" not available.')

        req_data = json.dumps([dict(
            action=router,
            method=method,
            data=data,
            type='rpc',
            tid=self.__req_count)])
        log.debug('Making request to router %s with method %s', router, method)
        if not uri:
            uri = '%s/zport/dmd/%s_router' % (self.__host, ROUTERS[router])
        headers = {'Content-type': 'application/json; charset=utf-8'}
        response = self.__session.post(uri, data=req_data, headers=headers)
        self.__req_count += 1

        # The API returns a 200 response code even whe auth is bad.
        # With bad auth, the login page is displayed. Here I search for
        # an element on the login form to determine if auth failed.
        returned = response.content.decode("utf-8")

        if re.search('name="__ac_name"', returned):
            log.error('Request failed. Bad username/password.')
            raise ZenossException('Request failed. Bad username/password.')
        if response.status_code == 200:
            return json.loads(response.content.decode("utf-8"))['result']
        else:
            raise ZenossException("Unable to complete request:\n%s\nHTTP Status: %s" % (
                req_data,
                response.status_code,
            ))

    def get_rrd_values(self,
                       device,
                       dsnames,
                       start=None,
                       end=None,
                       function='LAST'
                       ):
        '''Method to abstract the details of making a request
        to the getRRDValue method for a device
        '''

        if function not in ['MINIMUM', 'AVERAGE', 'MAXIMUM', 'LAST']:
            raise ZenossException(
                'Invalid RRD function {0} given.'.format(function)
            )

        if len(dsnames) == 1:
            # Appending a junk value to dsnames because
            # if only one value is provided Zenoss fails to return a value.
            dsnames.append('junk')

        url = '{0}/{1}/getRRDValues'.format(self.__host,
                                            self.device_uid(device))
        params = {'dsnames': dsnames,
                  'start': start,
                  'end': end,
                  'function': function
                  }
        return ast.literal_eval(self.__session.get(url, params=params).content)

    def get_devices(self, device_class='/zport/dmd/Devices', limit=None):
        '''Get a list of all devices.

        '''
        log.info('Getting all devices')
        return self.__router_request('DeviceRouter',
                                     'getDevices',
                                     data=[{
                                         'uid': device_class,
                                         'params': {},
                                         'limit': limit
                                     }])

    def get_components(self, device_name, **kwargs):
        '''Get components for a device given the name
        '''
        uid = self.device_uid(device_name)
        return self.get_components_by_uid(uid=uid, **kwargs)

    def get_components_by_uid(self, uid=None, meta_type=None, keys=None,
                              start=0, limit=50, page=0,
                              sort='name', dir='ASC', name=None):
        '''Get components for a device given the uid
        '''
        data = dict(uid=uid, meta_type=meta_type, keys=keys, start=start,
                    limit=limit, page=page, sort=sort, dir=dir, name=name)
        return self.__router_request('DeviceRouter', 'getComponents', [data])

    def find_device(self, device_name):
        '''Find a device by name.

        '''
        log.info('Finding device %s', device_name)
        all_devices = self.get_devices()

        for device in all_devices['devices']:
            if device_name in [device['name'], device['ipAddressString']]:
                device['hash'] = all_devices['hash']
                return device


    def device_uid(self, device):
        '''Helper method to retrieve the device UID for a given device name
        '''
        return self.find_device(device)['uid']

    def create_device(self,
                      device_name,
                      device_class,
                      model=False,
                      collector='localhost',
                      monitorIp=False,
                      **kwargs):

        out = []
        out.append(
            self.add_device(device_name,
                            device_class,
                            **kwargs
                            )
        )

        if monitorIp:
            out.append(
                self.reset_ip(device_name, ip_address=monitorIp)
            )
        if model:
            out.append(
                self.remodel_device(device_name)
            )

        return out

    def add_device(self,
                   device_name,
                   device_class,
                   model=False,
                   collector='localhost',
                   **kwargs):
        '''Add a device.

        https://www.zenoss.com/sites/default/files/zenoss-doc/3621/Zenoss_JSON_API_r5.2.0/Products.Zuul.routers.device.DeviceRouter-class.html#addDevice
        '''

        log.info('Adding %s', device_name)
        args = dict(deviceName=device_name,
                    deviceClass=device_class,
                    model=model,
                    collector=collector,
                    )
        args.update(kwargs)

        return self.__router_request('DeviceRouter', 'addDevice', [args])

    def remove_device(self, device_name):
        '''Remove a device.

        '''
        log.info('Removing %s', device_name)
        device = self.find_device(device_name)
        data = dict(uids=[device['uid']],
                    hashcheck=device['hash'],
                    action='delete')
        return self.__router_request('DeviceRouter', 'removeDevices', [data])

    def move_device(self, device_name, organizer):
        '''Move the device the organizer specified.

        '''
        log.info('Moving %s to %s', device_name, organizer)
        device = self.find_device(device_name)
        data = dict(uids=[device['uid']],
                    hashcheck=device['hash'],
                    target=organizer)
        return self.__router_request('DeviceRouter', 'moveDevices', [data])

    def set_prod_state(self, device_name, prod_state):
        '''Set the production state of a device.

        '''
        log.info('Setting prodState on %s to %s', device_name, prod_state)
        device = self.find_device(device_name)
        data = dict(uids=[device['uid']],
                    prodState=prod_state,
                    hashcheck=device['hash'])
        return self.__router_request('DeviceRouter',
                                     'setProductionState',
                                     [data])

    def set_maintenance(self, device_name):
        '''Helper method to set prodState for device so that it does not alert.

        '''
        return self.set_prod_state(device_name, 300)

    def set_production(self, device_name):
        '''Helper method to set prodState for device
        so that it is back in production and alerting.

        '''
        return self.set_prod_state(device_name, 1000)

    def set_product_info(self,
                         device_name,
                         hw_manufacturer,
                         hw_product_name,
                         os_manufacturer,
                         os_product_name):
        '''Set ProductInfo on a device.

        '''
        log.info('Setting ProductInfo on %s', device_name)
        device = self.find_device(device_name)
        data = dict(uid=device['uid'],
                    hwManufacturer=hw_manufacturer,
                    hwProductName=hw_product_name,
                    osManufacturer=os_manufacturer,
                    osProductName=os_product_name)
        return self.__router_request('DeviceRouter', 'setProductInfo', [data])

    def set_rhel_release(self, device_name, release):
        '''Sets the proper release of RedHat Enterprise Linux.'''
        if type(release) is not float:
            log.error("RHEL release must be a float")
            return {u'success': False}
        log.info('Setting RHEL release on %s to %s', device_name, release)
        device = self.find_device(device_name)
        return self.set_product_info(device_name,
                                     device['hwManufacturer']['name'],
                                     device['hwModel']['name'],
                                     'RedHat',
                                     'RHEL {}'.format(release)
                                     )

    def set_device_info(self, device_name, data):
        '''Set attributes on a device or device organizer.
            This method accepts any keyword argument
            for the property that you wish to set.

        '''
        data['uid'] = self.find_device(device_name)['uid']
        return self.__router_request('DeviceRouter', 'setInfo', [data])

    def remodel_device(self, device_name):
        '''Submit a job to have a device remodeled.

        '''
        return self.__router_request(
            'DeviceRouter',
            'remodel',
            [dict(uid=self.find_device(device_name)['uid'])]
        )

    def set_collector(self, device_name, collector):
        '''Set collector for device.

        '''
        device = self.find_device(device_name)
        data = dict(uids=[device['uid']],
                    hashcheck=device['hash'],
                    collector=collector)
        return self.__router_request('DeviceRouter', 'setCollector', [data])

    def rename_device(self, device_name, new_name):
        '''Rename a device.

        '''
        data = dict(uid=self.find_device(device_name)['uid'], newId=new_name)
        return self.__router_request('DeviceRouter', 'renameDevice', [data])

    def reset_ip(self, device_name, ip_address=''):
        '''Reset IP address(es) of device
        to the results of a DNS lookup or a manually set address.

        '''
        device = self.find_device(device_name)
        data = dict(uids=[device['uid']],
                    hashcheck=device['hash'],
                    ip=ip_address)
        return self.__router_request('DeviceRouter', 'resetIp', [data])

    def get_events(self,
                   limit=0,
                   start=0,
                   sort='lastTime',
                   dir='DESC',
                   params={},
                   archive=False,
                   uid=None,
                   detailFormat=False):
        """ Use EventsRouter action (Class) and query method found
        in JSON API docs on Zenoss website:

        query(self, limit=0, start=0, sort='lastTime', dir='desc', params=None,
        archive=False, uid=None, detailFormat=False)

        Parameters:

        limit (integer) - (optional) Max index of events to retrieve (default: 0)
        start (integer) - (optional) Min index of events to retrieve (default: 0)
        sort (string) - (optional) Key on which to sort the return results (default: 'lastTime')
        dir (string) - (optional) Sort order; can be either 'ASC' or 'DESC' (default: 'DESC')
        params (dictionary) - (optional) Key-value pair of filters for this search. (default: None)
        params are the filters to the query method and can be found in the _buildFilter method.
            agent = params.get('agent'),
            component = ???
            count_range = params.get('count'),
            current_user_name = params.get('ownerid'),
            details = details,
            device = ???
            element_sub_title = params.get('component'),
            element_title = params.get('device'),
            event_class = filter(None, [params.get('eventClass')]),
            event_summary = params.get('summary'),
            fingerprint = params.get('dedupid'),
                Note that the time values can be ranges where a valid range would be
                '2012-09-07 07:57:33/2012-11-22 17:57:33'
            first_seen = params.get('firstTime') and self._timeRange(params.get('firstTime')),
            last_seen = params.get('lastTime') and self._timeRange(params.get('lastTime')),
            monitor = params.get('monitor'),
            severity = params.get('severity'),
            status = [i for i in params.get('eventState', [])],
            status_change = params.get('stateChange') and self._timeRange(params.get('stateChange')),
            Systems (string) =
            tags = params.get('tags'),
            uuid = filterEventUuids,
        archive (boolean) - (optional) True to search the event history table instead of active events (default: False)
        uid (string) - (optional) Context for the query (default: None)
        detailFormat (boolean) - (optional) True to include/retrieve event detail instead of event summary(default: False)

        Returns: dictionary
        Properties:
            events: ([dictionary]) List of objects representing events
            totalCount: (integer) Total count of events returned
            asof: (float) Current time
        """

        # prepare data by passing arguments
        data = locals().copy()
        del data["self"]

        # query Zenoss
        log.info('Getting events for %s', data)
        response = self.__router_request('EventsRouter', 'query', [data])
        # if a valid response, continue to check
        # if further queries are required to get all events
        if 'success' in response and response['success'] is True:
            result_total_count = response['totalCount']
            result_count_in_initial_response = len(response['events'])
            log.info('%s events received, %s requested, %s events available',
                     result_count_in_initial_response,
                     data['limit'],
                     result_total_count)
            # if the number of results is less than the limit requested
            # and there are more total events available
            if (
                result_count_in_initial_response < data['limit'] and
                result_total_count > result_count_in_initial_response
            ):
                # iterate through remaining results in batches
                quotient = result_total_count / result_count_in_initial_response
                for i in range(0, quotient):
                    data['start'] = (i + 1) * result_count_in_initial_response
                    data['limit'] = result_count_in_initial_response
                    # store additional query result temporarily
                    log.info('Getting events for %s', data)
                    temp_response = self.__router_request('EventsRouter',
                                                          'query',
                                                          [data])
                    # add events to initial response
                    response['events'] += temp_response['events']
                    log.info('Events received: %s (iteration %s), %s (total)',
                             len(temp_response['events']),
                             (i + 2), len(response['events']))
            return response['events']
        # response was not valid
        else:
            log.error('No success field in response or success == false. %s',
                      response['msg'])
            return None

    def get_event_detail(self, event_id):
        '''Find specific event details

        '''
        data = dict(evid=event_id)
        return self.__router_request('EventsRouter', 'detail', [data])

    def write_log(self, event_id, message):
        '''Write a message to the event's log

        '''
        data = dict(evid=event_id, message=message)
        return self.__router_request('EventsRouter', 'write_log', [data])

    def change_event_state(self, event_id, state):
        '''Change the state of an event.

        '''
        log.info('Changing eventState on %s to %s', event_id, state)
        return self.__router_request('EventsRouter',
                                     state,
                                     [{'evids': [event_id]}])

    def ack_event(self, event_id):
        '''Helper method to set the event state to acknowledged.

        '''
        return self.change_event_state(event_id, 'acknowledge')

    def close_event(self, event_id):
        '''Helper method to set the event state to closed.

        '''
        return self.change_event_state(event_id, 'close')

    def create_event_on_device(self, device_name, severity, summary,
                               component='', evclasskey='', evclass=''):

        '''Manually create a new event for the device specified.

        '''
        log.info('Creating new event for %s with severity %s',
                 device_name,
                 severity)
        if severity not in ('Critical',
                            'Error',
                            'Warning',
                            'Info',
                            'Debug',
                            'Clear'):
            raise Exception('Severity %s is not valid.' % severity)

        data = dict(device=device_name,
                    summary=summary,
                    severity=severity,
                    component=component,
                    evclasskey=evclasskey,
                    evclass=evclass)
        return self.__router_request('EventsRouter', 'add_event', [data])

    def get_load_average(self, device):
        '''Returns the current 1, 5 and 15 minute load averages for a device.
        '''
        dsnames = ('laLoadInt1_laLoadInt1',
                   'laLoadInt5_laLoadInt5',
                   'laLoadInt15_laLoadInt15')
        result = self.get_rrd_values(device=device, dsnames=dsnames)

        def normalize_load(load):
            '''Convert raw RRD load average to something reasonable
            so that it matches output from /proc/loadavg
            '''
            return round(float(load) / 100.0, 2)
        return [normalize_load(l) for l in result.values()]

    def add_device_class(self, name, description="", path=""):
        '''
        create a new device class in zenoss
        zen.add_device_class("Arista", path="/Network")
        :param name: name of new device class
        :type name: string
        :param description: description of new device class
        :type description: string
        :return: dict showing the status of the command
        :rtype: dict
        usage::
            >>> zen.add_device_class("Testing", path="/HTTP")
            {u'msg': u'Device Class Added',
            u'nodeConfig': {
                u'children': [],
                u'hasNoGlobalRoles': False,
                u'hidden': False,
                u'iconCls': u'tree-severity-icon-small-clear',
                u'id': u'.zport.dmd.Devices.HTTP.Testing',
                u'leaf': False,
                u'path': u'Devices/HTTP/Testing',
                u'text': {u'count': 0, u'description': u'devices', u'text': u'Testing'},
                u'uid': u'/zport/dmd/Devices/HTTP/Testing',
                u'uuid': u'...',
                u'zPythonClass': u''},
            u'success': True}
        '''
        base_org = "/zport/dmd/Devices%s" % path
        data = dict(contextUid=base_org, id=name, description=description, type="organizer")
        return self.__router_request('DeviceRouter', 'addDeviceClassNode', [data])

    def add_event_class(self, name, description="", path=""):
        '''
        create a new event class

        :param name: the endpoint name of the event class
        :type name: string
        :param description: description the new event class
        :type description: string
        :param path: path to where to put new event class
        :type path: string
        :return: zenoss success dict, with nodeConfig key showing the new event class details
        :rtype: dict

        usage::
            >>> zen.add_event_class("Test", path="/Net", description="Testing")
            {u'nodeConfig': {u'children': [],
                 u'count': 0,
                 u'hidden': False,
                 u'iconCls': u'tree-severity-icon-small-clear',
                 u'id': u'.zport.dmd.Events.Net.Testing',
                 u'leaf': True,
                 u'path': u'Events/Net/Test',
                 u'text': {u'count': 0,
                 u'description': u'Testing',
                 u'hasTransform': False,
                 u'text': u'Testing'},
                 u'uid': u'/zport/dmd/Events/Net/Testing',
                 u'uuid': u'...'},
             u'success': True}
        '''
        base_org = "/zport/dmd/Events%s" % path
        data = dict(contextUid=base_org, id=name, description=description, type="organizer")
        return self.__router_request('EventClassesRouter', 'addNode', [data])

    def add_group(self, group, description="", path=""):
        '''
        add group

        :param group: name of group to be added
        :type group: string
        :param description: description for the group
        :type description: string
        :param path: path to the group, if group is to be placed in suborganizers
        :type path: string
        :return: zenoss success dict
        :rtype: dict

        usage::
            >>> zen.add_group("MyGroup")
            {u'nodeConfig': {u'children': [],
                u'hasNoGlobalRoles': False,
                u'hidden': False,
                u'iconCls': u'tree-severity-icon-small-clear',
                u'id': u'.zport.dmd.Groups.MyGroup',
                u'leaf': False,
                u'path': u'Groups/MyGroup',
                u'text': {u'count': 0, u'description': u'devices', u'text': u'MyGroup'},
                u'uid': u'/zport/dmd/Groups/MyGroup',
                u'uuid': u'...',
                u'zPythonClass': None},
            u'success': True
        '''
        log.info('Adding Group %s', group)
        base_org = "/zport/dmd/Groups/%s" % path
        data = dict(type='organizer', contextUid=base_org, id=group, description=description)
        return self.__router_request('DeviceRouter', 'addNode', [data])

    def add_hardware_product(self, product_name, manufacturer, product_type, part_number="",
                             product_keys="", description=""):
        '''
        Add Hardware
        '''
        log.info('Adding Hardware Product %s', product_name)
        tmp = dict(prodname=product_name, uid="/zport/dmd/Manufacturers/%s" % manufacturer,
                   type=product_type, description=description, partno=part_number,
                   prodkeys=product_keys)
        data = dict(params=tmp)
        return self.__router_request('ManufacturersRouter', 'addNewProduct', [data])

    def add_location(self, location_name, path="", description="", address=""):
        '''
        Add Location

        path key word denotes the path under /Locations that should be added
        and should be formatted like this sub/sub1

        :param location_name: name of location
        :type location_name: string
        :param path: path to location organizer
        :type path: string
        :param description: description of location
        :type description: string
        :param address: address of location
        :type address: string
        :return: zenoss success dict
        :rtype: dict

        usage::
            >>> zen.add_location("Springfield", address="742 evergreen terrace")
            {u'msg': u'Location added',
             u'nodeConfig': {u'children': [],
              u'hasNoGlobalRoles': False,
              u'hidden': False,
              u'iconCls': u'tree-severity-icon-small-clear',
              u'id': u'.zport.dmd.Locations.Springfield',
              u'leaf': False,
              u'path': u'Locations/Springfield',
              u'text': {u'count': 0, u'description': u'devices', u'text': u'Springfield'},
              u'uid': u'/zport/dmd/Locations/Springfield',
              u'uuid': u'...',
              u'zPythonClass': None},
             u'success': True}
        '''
        log.info('Adding Location %s', location_name)
        base_org = "/zport/dmd/Locations%s" % path
        data = dict(type='organizer', contextUid=base_org, id=location_name, description=description,
                    address=address)
        return self.__router_request('DeviceRouter', 'addLocationNode', [data])

    def add_notification(self, name, action):
        '''
        add a new notification

        :param name: name of the notification
        :type name: string
        :param action: the notifications action
        :type action: string
        :return: zenoss success dict where the data key holds the whole notifications config details
        :rtype: dict
        usage::
            >>> zen.add_notification("Testing", "email")
            {u'data':
                {u'action': u'email',
                u'content': {...},
                  ...
                },
            u'success': True}
        '''
        data = dict(newId=name, action=action)
        return self.__router_request('TriggersRouter', 'addNotification', [data])

    def add_trigger(self, name, rules=None, users=None, enabled=True,
                    global_manage=False, global_read=False, global_write=False):
        '''
        add a new trigger

        :param name: name of new trigger
        :type name: string
        :param rule: event rule string
        :type rule: string
        :param users: list of dicts for user setting definitions
        :type rule: list
        :param enabled: is the trigger enabled
        :type enabled: boolean
        :param global_manage: is the trigger manageable by all, can it be deleted
        :type global_manage: boolean
        :param global_read: is the trigger readable by all, can it be seen
        :type gloabl_read: boolean
        :param global_write: is the trigger writable by all, can it be updated
        :type global_write: boolean
        :return: zenoss success dict
        :rtype: dict


        usage::
            >>> zen.add_trigger('TEST')
            {u'data': u'b0be2cf8-6182-4cc5-8b5c-545765869612', u'success': True}
        '''
        result = self.__router_request('TriggersRouter', 'addTrigger', [dict(newId=name)])
        if not result['success']:
            raise ZenossException("Unable to add trigger %s Reason: %s" % (name, result['msg']))
        if rules:
            update_result = self.update_trigger_rules(name, rules, users=users, enabled=enabled,
                                                      global_manage=global_manage,
                                                      global_read=global_read,
                                                      global_write=global_write)
            if not update_result['success']:
                raise ZenossException("Unable to update rules for trigger %s" % name)
        return result

    def get_locations(self, location='/zport/dmd/Locations', limit=None):
        '''
        given a location endpoint return the details of the location object

        :return: dict of dict, with locations key holding a list of dicts
        :rtype: dict
        ::
            >> zen.get_locations()
            {
                u'locations': [
                    {u'name': u'/DataCenter1'},
                ],
                u'success': True,
                u'totalCount': 1
            }
        '''
        return self.__router_request('DeviceRouter', 'getLocations',
                                     data=[{'uid': location, 'params': {}, 'limit': limit}])

    def get_groups(self, groups='/zport/dmd/Groups', limit=None):
        '''
        get details of infrastructure group
        '''
        return self.__router_request('DeviceRouter', 'getGroups',
                                     data=[{'uid': groups, 'params': {}, 'limit': limit}])

    def get_device_classes(self, path):
        '''
        given a device class path return all the sub classes

        :param path: path to device classes
        :type path: string
        :return: list of dicts where each dict describes the sub device class
        :rtype: list
        uasge::
            >>> zen.get_device_classes("/Network")
            [{
                u'hidden': False,
                u'iconCls': u'tree-severity-icon-small-clear',
                u'id': u'.zport.dmd.Devices.Network.Router',
                u'leaf': False,
                u'path': u'Devices/Network/Router',
                u'text': {u'count': 0, u'description': u'devices', u'text': u'Router'},
                u'uid': u'/zport/dmd/Devices/Network/Router'
            }]
        '''
        base_org = "/zport/dmd/Devices%s" % path
        return self.__router_request('DeviceRouter', 'asyncGetTree', [base_org])

    def get_device_class_template(self, path):
        '''
        gather the templates for a device class

        :param path: Path to the device class, the root is /Devices
        :type path: string
        :return: list of device class templates
        :rtype: list
        usage::
            >>> zen.get_device_class_template("/Network")
            [{u'id': u'/zport/dmd/Devices/rrdTemplates/Device',
            u'leaf': True,
            u'path': u'/',
            u'text': u'Device (/)',
            u'uid': u'/zport/dmd/Devices/rrdTemplates/Device'}]
        '''
        base_org = "/zport/dmd/Devices%s" % path
        return self.__router_request('DeviceRouter', 'getTemplates', [base_org])

    def get_ec_instance_details(self, name, path="", is_uid=False):
        '''
        get the details of an event class

        :param name: instance name
        :type name: string
        :param path: path to event class transform
        :type path: string
        :param is_uid: flag to check if name is uid
        :type is_uid: boolean
        :return: zenoss success dict, with data key holding all the instance details
        :rtype: dict


        usage::
            >>> zen.get_ec_instance_details("bgpBackwardTransNotification", path="/Net/BGP")
            {u'data': [{u'evaluation': u'',
                u'eventClass': u'BGP',
                u'eventClassKey': u'bgpNotification.2',
                u'example': u'snmp trap bgpNotification.2',
                u'id': u'bgpBackwardTransNotification',
                u'regex': u'',
                u'resolution': u'',
                u'rule': u'',
                u'sequence': 8,
                u'transform': u'\'\'\'\nevent transform for bgpBackwardTransition\n\'\'\'\n
                u'uid': u'/zport/dmd/Events/Net/BGP/instances/bgpBackwardTransNotification'}],
             u'success': True}
        '''
        if is_uid:
            data = dict(uid=name)
        else:
            data = dict(uid="/zport/dmd/Events%s/instances/%s" % (path, name))
        return self.__router_request('EventClassesRouter', 'getInstanceData', [data])

    def get_event_classes_instances(self, path=""):
        '''
        get all the event class instances

        :params path: limit the instances to event classes in this path
        :type path: string
        :return: zenoss success dict, with data key holding all the event classes
        :rtype: dict

        usage::
            >>> zen.get_event_classes(path="/Net/Time")
            {u'data': [{
                u'eval': u'The time provider NtpServer...',
               u'eventClassKey': u'W32Time_22',
               u'hasTransform': False,
               u'id': u'W32Time_22',
               u'uid': u'/zport/dmd/Events/Net/Time/instances/W32Time_22'}],
           u'success': True}
        '''
        base_org = "/zport/dmd/Events%s" % path
        data = dict(params={}, uid=base_org)
        return self.__router_request('EventClassesRouter', 'getInstances', [data])

    def get_ec_instance_transform(self, name, path="", is_uid=False):
        '''
        get the event transform off an event class instance

        :param name: instance name
        :type name: string
        :param path: path to event class transform
        :type path: string
        :param is_uid: flag to check if name is uid
        :type is_uid: boolean
        :return: zenoss success dict
        :rtype: dict

        usage::
            >>> zen.get_ec_instance_transform("bgpBackwardTransNotif", path="/Net/BGP")
            {
                u'data': u'\'\'\'\nevent transform for bgpBackwardTransNotif\n\'\'\'\n...',
                u'success': True
            }
        '''
        if is_uid:
            data = dict(uid=name)
        else:
            base_org = "/zport/dmd/Events%s" % path
            data = dict(uid="%s/instances/%s" % (base_org, name))
        return self.__router_request('EventClassesRouter', 'getTransform', [data])

    def get_location_details(self, name, path=""):
        '''
        given a location return all the info about said location

        :param name: location name
        :type name: string
        :param path: path to location
        :return: dict of dict where data key has all the location details
        :rtype: dict
        ::
            >>> zen.get_location_details("DataCenter1")
            {u'data': {u'address': u'742 Evergreen Terrace',
              u'description': u'',
              u'events': {u'clear': {u'acknowledged_count': 0, u'count': 0},
               u'critical': {u'acknowledged_count': 0, u'count': 1},
               u'debug': {u'acknowledged_count': 0, u'count': 0},
               u'error': {u'acknowledged_count': 1, u'count': 7},
               u'info': {u'acknowledged_count': 0, u'count': 82},
               u'warning': {u'acknowledged_count': 0, u'count': 8}},
              u'id': u'Europe',
              u'inspector_type': u'Location',
              u'meta_type': u'Location',
              u'name': u'/DataCenter1',
              u'severity': u'critical',
              u'uid': u'/zport/dmd/Locations/DataCenter1',
              u'uuid': u'...'},
             u'disabled': False,
             u'success': True}
        '''
        uid = "/zport/dmd/Locations%s/%s" % (path, name)
        return self.__router_request('DeviceRouter', 'getInfo', data=[dict(uid=uid)])

    def get_notifications(self):
        '''
        return all the notifications

        :return: dict
        :rtype: dict
        usage::
            >>> zen.get_device_classes("/Network")
            {
                'success': True,
                'data': [{
                    u'action': u'email',
                    u'content': {...},
                    ...
                }]
            }
        '''
        return self.__router_request('TriggersRouter', 'getNotifications', [{}])

    def get_triggers(self):
        '''
        gather all the triggers

        :return: zenoss success dict, where all the triggers are under the data key
        :rtype: dict

        usage::
        >>> zen.get_triggers()
        {u'data': [{
            u'enabled': True,
            u'globalManage': True,
            u'globalRead': True,
            u'globalWrite': True,
            u'name': u'RuleName',
            u'rule': {
                u'api_version': 1,
                u'source': u'(dev.production_state == 1000) and (evt.severity >= 4)',
                u'type': 1},
            u'subscriptions': [
                {
                    u'delay_seconds': 0,
                    u'repeat_seconds': 0,
                    u'send_initial_occurrence': True,
                    u'subscriber_uuid': u'...',
                    u'trigger_uuid': u'...',
                    u'uuid': u'...'},
                {
                    u'delay_seconds': 1,
                    u'repeat_seconds': 60,
                    u'send_initial_occurrence': True,
                    u'subscriber_uuid': u'...',
                    u'trigger_uuid': u'...',
                    u'uuid': u'...'}
            ],
            u'userManage': True,
            u'userRead': True,
            u'userWrite': True,
            u'users': [],
            u'uuid': u'...'}],
        u'success': True}
        '''
        return self.__router_request('TriggersRouter', 'getTriggers', [{}])

    def get_zproperties(self, uid):
        '''
        take any uid to a zenoss object and return the zproperties for the object

        :param uid: Specify the zenoss uid for object to inspect
        :type uid: string
        :return: zenoss response dict where data key holds all the properties
        :rtype: dict
        usage::
            >>> zen.get_zproperties("/zport/dmd/Devices/Network")
            {u'data': [ {
                u'category': u'Modeler Controls',
                u'description': u'Allows you to set the timeout time of the collector client in seconds',
                u'id': u'zCollectorClientTimeout',
                u'islocal': 0,
                u'label': u'Collector Client Timeout (seconds)',
                u'options': [],
                u'path': u'/',
                u'type': u'int',
                u'value': 180,
                u'valueAsString': 180},
                ...
                ]
            u'success': True,
            u'totalCount': 81
        }
        '''
        return self.__router_request('PropertiesRouter', 'getZenProperties',
                                     uri="%s%s/properties_router" % (self.__host, uid),
                                     data=[dict(uid=uid)])

    def remove_device_class(self, name, path=""):
        '''
        remove a given device class from zenoss

        :param name: name of device class to be removed
        :type name: string
        :param path: path to device class endpoint
        :type path: string
        :return: dict showing the status of the command
        :rtype: dict
        usage::
            >>> zen.remove_device_class("Switch", path="/Network")
            {u'msg': u"Deleted node '/zport/dmd/Devices/HTTP/Test'", u'success': True}
        '''
        base_org = "/zport/dmd/Devices%s" % path
        data = dict(uid="%s/%s" % (base_org, name))
        return self.__router_request('DeviceRouter', 'deleteNode', [data])

    def remove_event_class(self, name, path=""):
        '''
        remove an event class

        :param name: the endpoint name of the event class to be removed
        :type name: string
        :param path: path to where the event class is located
        :type path: string
        :return: zenoss success dict
        :rtype: dict

        usage::
            >>> zen.remove_event_class("Testing", path="/Net")
                {u'success': True}
        '''
        base_org = "/zport/dmd/Events%s" % path
        data = dict(uid="%s/%s" % (base_org, name))
        return self.__router_request('EventClassesRouter', 'deleteEventClass', [data])

    def remove_group(self, group, path=""):
        '''
        Deletes a Group organizer
        :param group: name of group to be deleted
        :type group: string
        :param path: path to organizer holding group
        :type path: string
        :return: zenoss success dict
        :rtype: dict

        usage::
            >>> zen.remove_group("MyGroup")
            {u'msg': u"Deleted node '/zport/dmd/Groups/MyGroup'", u'success': True}
        '''
        base_org = "/zport/dmd/Groups%s" % path
        log.info('Removing Group %s', group)
        data = dict(uid="%s/%s" % (base_org, group))
        return self.__router_request('DeviceRouter', 'deleteNode', [data])

    def remove_locations(self, location, path=""):
        '''
        Deletes a Location organizer

        :param location: name of the location to be remove
        :type location: string
        :param path: path to the location organizer
        :type path: string
        :return: zenoss success dict
        :rtype: dict
        usage::
            >>> zen.remove_locations("Springfield")
            {u'msg': u"Deleted node '/zport/dmd/Locations/Springfield'", u'success': True}
        '''
        base_org = "/zport/dmd/Locations%s" % path
        log.info('Removing Location %s', location)
        data = dict(uid="%s/%s" % (base_org, location))
        return self.__router_request('DeviceRouter', 'deleteNode', [data])

    def remove_trigger(self, name):
        '''
        delete a trigger

        :param name: name of trigger to be removed
        :type name: string
        usage::
            >>> zen.remove_trigger('TEST')
            {u'data': None,
            u'msg': u'Trigger removed successfully. 0 notifications were updated.',
            u'success': True}
        '''
        all_triggers = {_['name']:_ for _ in self.get_triggers()['data']}
        if name not in all_triggers:
            raise ZenossException("Unable to find trigger %s" % (name))
        uuid = all_triggers[name]['uuid']
        return self.__router_request('TriggersRouter', 'removeTrigger', [dict(uuid=uuid)])

    def set_ec_instance_details(self, name, transform, path="", is_uid=False):
        '''
        modify an event class details

        :param name: name of the event class
        :type name: string
        :param transform: transform code
        :type transform: string
        :param path: path to even class
        :type path: string
        :param is_uid: is the name provided a uid, saves on look ups
        :type is_uid: boolean
        :return: zenoss success dict
        :rtype: dict

        usage::

        '''
        if is_uid:
            data = dict(uid=name, transform=transform)
        else:
            base_org = "/zport/dmd/Events%s" % path
            data = dict(uid="%s/instances/%s" % (base_org, name))
        return self.__router_request('EventClassesRouter', 'setTransform', [data])

    def update_notifiication_sub(self, name, subscriptions, by_name=False):
        '''
        update the notification subscription

        :param name: name of the notification
        :type name: string
        :param subscription: list of uids for this notification to subscribe to
        :type subscription: list
        :param by_name: flag to send a list of trigger names, not uuids of triggers
        :type by_name: boolean
        usage::
            >>> zen.update_notification_sub('Test', ['f1f9eb4b-090b-4021-8e26-e535b29077c5'])
            {u'data': None,
             u'msg': u'Notification updated successfully.',
             u'success': True}
        '''
        all_notifications = {_['name']: _ for _ in self.get_notifications()['data']}
        if name not in all_notifications:
            raise ZenossException("Unable to find notification %s" % name)
        if by_name:
            all_triggers = {_['name']:_ for _ in self.get_triggers()['data']}
            tmp = list()
            for _ in subscriptions:
                if _ in all_triggers:
                    tmp.append(all_triggers[_]['uuid'])
                else:
                    raise ZenossException("Unable to map trigger %s to notification %s" % (
                        _,
                        name
                    ))
            subscriptions = tmp
        else:
            diff = set(subscriptions).difference(
                set([_['uuid'] for _ in self.get_triggers()['data']]))
            if diff:
                raise ZenossException("Passed trigger subscription uuid that doesn't exist %s" % diff)
        data = all_notifications[name]
        data['subscriptions'] = subscriptions
        return self.__router_request('TriggersRouter', 'updateNotification', [data])

    def update_trigger_rules(self, name, rule=None, users=None, enabled=True,
                             global_manage=False, global_read=False, global_write=False):
        '''
        modify an existing trigger

        NOTE: is the request isn't properly formatted zenoss might just accept it, and return
        success.

        :param name: name of the trigger
        :type name: string
        :param rule: event rule string
        :type rule: string
        :param users: list of dicts for user setting definitions
        :type rule: list
        :param enabled: is the trigger enabled
        :type enabled: boolean
        :param global_manage: is the trigger manageable by all, can it be deleted
        :type global_manage: boolean
        :param global_read: is the trigger readable by all, can it be seen
        :type gloabl_read: boolean
        :param global_write: is the trigger writable by all, can it be updated
        :type global_write: boolean
        :return: zenoss success dict
        :rtype: dict

        usage::
            >>> zen.update_trigger_rules("dc1_bgp", enabled=False)
            {u'data': u'', u'msg': u'Trigger updated successfully.', u'success': True}
        '''
        all_triggers = {_['name']:_ for _ in self.get_triggers()['data']}
        if name not in all_triggers:
            raise ZenossException("Unable to find trigger %s" % (name))
        if not rule:
            rule = all_triggers[name]['rule']['source']
        uuid = all_triggers[name]['uuid']
        data = dict(
            enabled=enabled,
            globalManage=global_manage,
            globalRead=global_read,
            globalWrite=global_write,
            name=name,
            uuid=uuid,
            rule=dict(source=rule)
        )
        if users:
            data['users'] = users
        return self.__router_request('TriggersRouter', 'updateTrigger', [data])