NAME

Zenoss::Router::Device - A JSON/ExtDirect interface to operations on devices

SYNOPSIS

use Zenoss;
my $api = Zenoss->connect(
    {
        username    => 'zenoss username',
        password    => 'zenoss password',
        url         => 'http://zenossinstance:8080',
    }
);

# Replace SOMEMETHOD with one of the available methods provided by this module
my $response = $api->device_SOMEMETHOD(
    {
        parameter1 => 'value',
        parameter2 => 'value',
    }
);

DESCRIPTION

This module is NOT instantiated directly. To call methods from this module create an instance of Zenoss. This document serves as a resource of available Zenoss API calls available to Zenoss.

METHODS

The following is a list of available methods available for interaction with the Zenoss API. Please take note of the argument requirements, defaults and return content.

$obj->device_addLocationNode()

Adds a new location organizer specified by the parameter id to the parent organizer specified by contextUid. contextUid must be a path to a Location.

ARGUMENTS

type (string) - Node type (always 'organizer' in this case)

contextUid (string) - Path to the location organizer that will be the new node's parent (ex. /zport/dmd/Devices/Locations)

id (string) - The identifier of the new node

description (string) - Describes the new location

address (string) - Physical address of the new location

REQUIRED ARGUMENTS

type

contextUid

id

DEFAULT ARGUMENTS

N/A

RETURNS

success: (bool) Success of node creation

nodeConfig: (dictionary) The new location's properties

$obj->device_getTree()

Returns the tree structure of an organizer hierarchy where the root node is the organizer identified by the id parameter.

ARGUMENTS

id (string) - Id of the root node of the tree to be returned

REQUIRED ARGUMENTS

id

DEFAULT ARGUMENTS

N/A

RETURNS

success: (bool) Success of node creation

Object representing the tree

$obj->device_getComponents()

Retrieves all of the components at a given UID. This method allows for pagination.

ARGUMENTS

uid (string) - Unique identifier of the device whose components are being retrieved

meta_type (string) - The meta type of the components to be retrieved

keys (list) - List of keys to include in the returned dictionary. If None then all keys will be returned

start (integer) - Offset to return the results from; used in pagination

limit (integer) - Number of items to return; used in pagination

sort (string) - Key on which to sort the return results;

dir (string) - Sort order; can be either 'ASC' or 'DESC'

name (regex) - Used to filter the results

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

{start => 0, limit => 50, sort => 'name', dir => 'ASC'}

RETURNS

data: (dictionary) The components returned

totalCount: (integer) Number of items returned

hash: (string) Hashcheck of the current component state (to check whether components have changed since last query)

$obj->device_getComponentTree()

Retrieves all of the components set up to be used in a tree.

ARGUMENTS

uid (string) - Unique identifier of the root of the tree to retrieve

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

N/A

RETURNS

Component properties in tree form

$obj->device_findComponentIndex()

Given a component uid and the component search criteria, this retrieves the position of the component in the results.

ARGUMENTS

componentUid (string) - Unique identifier of the component whose index to return

uid (string) - Unique identifier of the device queried for components

meta_type (string) - The meta type of the components to retrieve

sort (string) - Key on which to sort the return results

dir (string) - Sort order; can be either 'ASC' or 'DESC'

name (regex) - Used to filter the results

REQUIRED ARGUMENTS

componentUid

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

index: (integer) Index of the component

$obj->device_getForm()

Given an object identifier, this returns all of the editable fields on that object as well as their ExtJs xtype that one would use on a client side form.

ARGUMENTS

uid (string) - Unique identifier of an object

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

form: (dictionary) form fields for the object

$obj->device_getInfo()

Get the properties of a device or device organizer

ARGUMENTS

uid (string) - Unique identifier of an object

keys (list) - List of keys to include in the returned dictionary. If None then all keys will be returned

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

data: (dictionary) Object properties

disabled: (bool) If current user doesn't have permission to use setInfo

$obj->device_setProductInfo()

Sets the ProductInfo on a device. This method has the following valid keyword arguments:

ARGUMENTS

uid (string) - Unique identifier of a device

hwManufacturer (string) - Hardware manufacturer

hwProductName (string) - Hardware product name

osManufacturer (string) - Operating system manufacturer

osProductName (string) - Operating system product name

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

Not documented

$obj->device_getDevices()

Retrieves a list of devices. This method supports pagination.

ARGUMENTS

uid (string) - Unique identifier of the organizer to get devices from

start (integer) - Offset to return the results from; used in pagination

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

limit (integer) - Number of items to return; used in pagination

sort (string) - Key on which to sort the return results

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

{start => 0, limit => 50, sort => 'name', dir => 'ASC'}

RETURNS

devices: (list) Dictionaries of device properties

totalCount: (integer) Number of devices returned

hash: (string) Hashcheck of the current device state (to check whether devices have changed since last query)

$obj->device_moveDevices()

Moves the devices specified by uids to the organizer specified by 'target'.

ARGUMENTS

uids ([string]) - List of device uids to move

target (string) - Uid of the organizer to move the devices to

hashcheck (string) - Hashcheck for the devices (from getDevices())

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

uid (string) - Organizer to use when using ranges to get additional uids

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

target

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

tree: ([dictionary]) Object representing the new device tree

exports: (integer) Number of devices moved

$obj->device_pushChanges()

Push changes on device(s) configuration to collectors.

ARGUMENTS

uids ([string]) - List of device uids to push changes

hashcheck (string) - Hashcheck for the devices (from getDevices())

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

uid (string) - Organizer to use when using ranges to get additional uids

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

Success message

$obj->device_lockDevices()

Lock device(s) from changes.

ARGUMENTS

uids ([string]) - List of device uids to lock

hashcheck (string) - Hashcheck for the devices (from getDevices())

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

updates (boolean) - True to lock device from updates

deletion (boolean) - True to lock device from deletion

sendEvent (boolean) - True to send an event when an action is blocked by locking

uid (string) - Organizer to use when using ranges to get additional uids

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{updates => JSON::false, deletion => JSON::false, sendevent => JSON::false, sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_resetIp()

Reset IP address(es) of device(s) to the results of a DNS lookup or a manually set address

ARGUMENTS

uids ([string]) - List of device uids with IP's to reset

hashcheck (string) - Hashcheck for the devices (from getDevices())

uid (string) - Organizer to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

ip (string) - IP to set device to. Empty string causes DNS lookup

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC', ip => ''}

RETURNS

Success or failure message

$obj->device_resetCommunity()

Reset IP address(es) of device(s) to the results of a DNS lookup or a manually set address

ARGUMENTS

uids ([string]) - List of device uids to reset

hashcheck (string) - Hashcheck for the devices (from getDevices())

uid (string) - Organizer to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_setProductionState()

Set the production state of device(s)

ARGUMENTS

uids ([string]) - List of device uids to set

prodState (integer) - Production state to set device(s) to.

hashcheck (string) - Hashcheck for the devices (from getDevices())

uid (string) - Organizer to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or

productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

prodState

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_setPriority()

Set device(s) priority.

ARGUMENTS

uids ([string]) - List of device uids to set

priority (integer) - Priority to set device(s) to.

hashcheck (string) - Hashcheck for the devices (from getDevices())

uid (string) - Organizer to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

priority

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_setCollector()

Set device(s) collector.

ARGUMENTS

uids ([string]) - List of device uids to set

collector (string) - Collector to set devices to

hashcheck (string) - Hashcheck for the devices (from getDevices())

uid (string) - Organizer to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or

productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

collector

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_setComponentsMonitored()

Set the monitoring flag for component(s)

ARGUMENTS

uids ([string]) - List of component uids to set

hashcheck (string) - Hashcheck for the components (from getComponents())

monitor (boolean) - True to monitor component

uid (string) - Device to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

meta_type (string) - The meta type of the components to retrieve

start (integer) - Offset to return the results from; used in pagination

limit (integer) - Number of items to return; used in pagination

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

name (string) - Component name to search for when loading ranges

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{monitor => JSON::false, start => 0, limit => 50, sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_lockComponents()

Lock component(s) from changes.

ARGUMENTS

uids ([string]) - List of component uids to lock

hashcheck (string) - Hashcheck for the components (from getComponents())

uid (string) - Device to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

updates (boolean) - True to lock component from updates

deletion (boolean) - True to lock component from deletion

sendEvent (boolean) - True to send an event when an action is blocked by locking

meta_type (string) - The meta type of the components to retrieve

start (integer) - Offset to return the results from; used in pagination

limit (integer) - Number of items to return; used in pagination

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

name (string) - Component name to search for when loading ranges

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{updates => JSON::false, deletion => JSON::false, sendEvent => JSON::false, start => 0, limit => 50, sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_deleteComponents()

Lock component(s) from changes.

ARGUMENTS

uids ([string]) - List of component uids to delete

hashcheck (string) - Hashcheck for the components (from getComponents())

uid (string) - Device to use when using ranges to get additional uids

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

meta_type (string) - The meta type of the components to retrieve

start (integer) - Offset to return the results from; used in pagination

limit (integer) - Number of items to return; used in pagination

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

name (string) - Component name to search for when loading ranges

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{start => 0, limit => 50, sort => 'name', dir => 'ASC'}

RETURNS

Success or failure message

$obj->device_removeDevices()

Lock component(s) from changes.

ARGUMENTS

uids ([string]) - List of device uids to remove

hashcheck (string) - Hashcheck for the devices (from getDevices())

action (string) - Action to take. 'remove' to remove devices from organizer uid, and 'delete' to delete the device from Zenoss.

uid (string) - Organizer to use when using ranges to get additional uids and/or to remove device

ranges ([integer]) - List of two integers that are the min/max values of a range of uids to include

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

uids

hashcheck

DEFAULT ARGUMENTS

{action => 'remove', sort => 'name', dir => 'ASC'}

RETURNS

devtree: ([dictionary]) Object representing the new device tree

grptree: ([dictionary]) Object representing the new group tree

systree: ([dictionary]) Object representing the new system tree

loctree: ([dictionary]) Object representing the new location tree

$obj->device_getEvents()

Get events for a device.

ARGUMENTS

uid ([string]) - Device to get events for

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

data: ([dictionary]) List of events for a device

$obj->device_loadRanges()

Get a range of device uids.

ARGUMENTS

ranges ([integer]) - List of two integers that are the min/max values of a range of uids

hashcheck (string) - Hashcheck for the devices (from getDevices())

uid (string) - Organizer to use to get uids

params (dictionary) - Key-value pair of filters for this search. Can be one of the following: name, ipAddress, deviceClass, or productionState

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

REQUIRED ARGUMENTS

ranges

hashcheck

DEFAULT ARGUMENTS

{sort => 'name', dir => 'ASC'}

RETURNS

A list of device uids

$obj->device_loadComponentRanges()

Get a range of component uids.

ARGUMENTS

ranges ([integer]) - List of two integers that are the min/max values of a range of uids

hashcheck (string) - not used

uid (string) - Device to use to get uids

types ([string]) - The types of components to retrieve

meta_type (string) - The meta type of the components to retrieve

start (integer) - Offset to return the results from; used in pagination

limit (integer) - Number of items to return; used in pagination

sort (string) - Key on which to sort the return result

dir (string) - Sort order; can be either 'ASC' or 'DESC'

name (string) - Component name to search for when loading ranges

REQUIRED ARGUMENTS

ranges

hashcheck

DEFAULT ARGUMENTS

{start => 0, sort => 'name', dir => 'ASC'}

RETURNS

A list of component uids

$obj->device_getUserCommands()

Get a list of user commands for a device uid.

ARGUMENTS

uid (string) - Device to use to get user commands

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

List of objects representing user commands

$obj->device_getProductionStates()

Get a list of available production states.

ARGUMENTS

NONE

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

N/A

RETURNS

List of name/value pairs of available production states

$obj->device_getPriorities()

Get a list of available device priorities.

ARGUMENTS

NONE

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

N/A

RETURNS

List of name/value pairs of available device priorities

$obj->device_getCollectors()

Get a list of available collectors.

ARGUMENTS

NONE

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

N/A

RETURNS

List of collectors

$obj->device_getDeviceClasses()

Get a list of all device classes.

ARGUMENTS

NONE

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

N/A

RETURNS

deviceClasses: ([dictionary]) List of device classes

totalCount: (integer) Total number of device classes

$obj->device_getManufacturerNames()

Get a list of all manufacturer names.

ARGUMENTS

NONE

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

N/A

RETURNS

manufacturers: ([dictionary]) List of manufacturer names

totalCount: (integer) Total number of manufacturer names

$obj->device_getHardwareProductNames()

Get a list of all hardware product names from a manufacturer.

ARGUMENTS

manufacturer (string) - Manufacturer name

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

{manufacturer => ''}

RETURNS

productNames: ([dictionary]) List of hardware product names

totalCount: (integer) Total number of hardware product names

$obj->device_getOSProductNames()

Get a list of all OS product names from a manufacturer.

ARGUMENTS

manufacturer (string) - Manufacturer name

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

{manufacturer => ''}

RETURNS

productNames: ([dictionary]) List of OS product names

totalCount: (integer) Total number of OS product names

$obj->device_addDevice()

Add a device.

ARGUMENTS

deviceName (string) - Name or IP of the new device

deviceClass (string) - The device class to add new device to

title (string) - The title of the new device

snmpCommunity (string) - A specific community string to use for this device.

snmpPort (integer) - SNMP port on new device

model (boolean) - True to model device at add time

collector (string) - Collector to use for new device

rackSlot (string) - Rack slot description

productionState (integer) - Production state of the new device

comments (string) - Comments on this device

hwManufacturer (string) - Hardware manufacturer name

hwProductName (string) - Hardware product name

osManufacturer (string) - OS manufacturer name

osProductName (string) - OS product name

priority (integer) - Priority of this device

tag (string) - Tag number of this device

serialNumber (string) - Serial number of this device

REQUIRED ARGUMENTS

deviceName

deviceClass

DEFAULT ARGUMENTS

{snmpCommunity => '', snmpPort => '161', collector => 'localhost', rackSlot => 0, productionState => 1000, comments => '', hwManufacturer => '', hwProductName => '', osManufacturer => '', osProductName => '', priority => 3, tag => '', serialNumber => ''}

RETURNS

jobId: (string) ID of the add device job

$obj->device_addLocalTemplate()

Adds a local template on a device.

ARGUMENTS

deviceUid (string) - Device uid to have local template

templateId (string) - Name of the new template

REQUIRED ARGUMENTS

deviceUid

templateId

DEFAULT ARGUMENTS

N/A

RETURNS

Success message

$obj->device_removeLocalTemplate()

Removes a locally defined template on a device.

ARGUMENTS

deviceUid (string) - Device uid that has local template

templateUid (string) - Name of the template to remove

REQUIRED ARGUMENTS

deviceUid

templateUid

DEFAULT ARGUMENTS

N/A

RETURNS

Success message

$obj->device_getLocalTemplates()

Get a list of locally defined templates on a device.

ARGUMENTS

uid (string) - Device uid to query for templates

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

data: ([dictionary]) List of objects representing local templates

$obj->device_getTemplates()

Get a list of available templates for a device.

ARGUMENTS

id (string) - Device uid to query for templates

REQUIRED ARGUMENTS

id

DEFAULT ARGUMENTS

N/A

RETURNS

data: ([dictionary]) List of objects representing templates

$obj->device_getUnboundTemplates()

Get a list of unbound templates for a device.

ARGUMENTS

uid (string) - Device uid to query for templates

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

data: ([dictionary]) List of objects representing templates

$obj->device_getBoundTemplates()

Get a list of bound templates for a device.

ARGUMENTS

uid (string) - Device uid to query for templates

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

data: ([dictionary]) List of objects representing templates

$obj->device_setBoundTemplates()

Set a list of templates as bound to a device.

ARGUMENTS

uid (string) - Device uid to bind templates to

templateIds ([string]) - List of template uids to bind to device

REQUIRED ARGUMENTS

uid

templateIds

DEFAULT ARGUMENTS

N/A

RETURNS

Success message

$obj->device_resetBoundTemplates()

Remove all bound templates from a device.

ARGUMENTS

uid (string) - Device uid to remove bound templates from

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

Success message

$obj->device_bindOrUnbindTemplate()

Bind an unbound template or unbind a bound template from a device.

ARGUMENTS

uid (string) - Device uid to bind/unbind template

templateUid (string) - Template uid to bind/unbind

REQUIRED ARGUMENTS

uid

templateUid

DEFAULT ARGUMENTS

N/A

RETURNS

Success message

$obj->device_getOverridableTemplates()

Get a list of available templates on a device that can be overridden.

ARGUMENTS

uid (string) - Device to query for overridable templates

REQUIRED ARGUMENTS

uid

DEFAULT ARGUMENTS

N/A

RETURNS

data: ([dictionary]) List of objects representing templates

$obj->device_clearGeocodeCache()

Clear the Google Maps geocode cache.

ARGUMENTS

NONE

REQUIRED ARGUMENTS

N/A

DEFAULT ARGUMENTS

N/A

RETURNS

Success message

SEE ALSO

• Zenoss

• Zenoss::Response

AUTHOR

Patrick Baker <patricksbaker@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Patrick Baker <patricksbaker@gmail.com>

This module is free software: you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You can obtain the Artistic License 2.0 by either viewing the LICENSE file provided with this distribution or by navigating to http://opensource.org/licenses/artistic-license-2.0.php.

cpanm Zenoss

perl -MCPAN -e shell
install Zenoss