PHP API
Contents
PHP API Overview
The GroundWork Foundation PHP API provides an object library to access the Collage database sources and the information within these sources. The library is split up into connection and query type classes.
Requirements
The GroundWork Foundation PHP API requires PHP 5.x and also requires the adodb http://adodb.sourceforge.net/ database abstraction layer to be installed in your PHP include path (or the path configured in the collageapi.inc.php file.
Connnection Classes

Collage DB

 Instances of this class point to an active Collage Database source and is used by query class instances as a target Collage Database to query against. Multiple instances of this class can be used to query multiple Collage databases in one script.

Constructor

function __construct($type, $server, $username, $password, $database)
Using the parameters passed, the constructor of the CollageDB class creates the persistent connection to the Collage source. If there is a problem connecting, the constructor will set it's error code to NOT_CONNECTED and return immediately. Otherwise, the database connection is active and the object can then be used as the source parameter for Collage query instances.

Parameters

$type (String) Determines what type of database engine the Collage source is running. Currently, only MySQL is supported.
server (String) A Hostname or IP address of the Collage source that you wish to target. A IP address is recommended in case of DNS failure.
username (String) The username of the database engine that you wish to connect to the Collage target as.
password (String) The password of the user of the database engine that you wish to connect as.
database (String) The database name of the Collage source inside the database engine.

Destructor

The destructor for the CollageDB class currently performs no actions, other than removing internal variables.
function __destruct()

Methods

function isConnected()
Returns true if the object has an active connection to a Collage source. Returns false, otherwise.
function selectQuery($query)
This function is meant to provide low-level access to the data inside the Collage source. It is not recommended to use this method, except in cases where a Query object cannot perform the task you want. In order to use this method, you must create a SQL statement to pass to the database. This method does not test for SQL-compliance, nor for parameter checking. It assumes the query is valid and attempts to perform it. It will return either a multi-dimensional associative array with your returned records, or it will return a NULL value. If it returns a NULL value, there is possibly no records to match your statement, or there was an error, which you should find from the method get_error_num, described below.

Parameters

$query (String) A SQL select query to run against the collage database source.
function get_error_num() Returns a defined error code (Error codes are described below) in which the object was unable to perform the last attempted task. The error code is reset at the beginning of each operation, so this method should be called after performing an operation.

Collage

 Instances of this class use a CollageDB connection object to communicate with Collage and return information. It is mostly used as a base class for the inherited classes described below; however, instances can be used on their own to perform basic collage queries.

Constructor

function __construct($passedDB)
Will create a Collage object to properly query against.

Parameters

$passedDB (CollageDB) A Collage Connection object which points to an active Collage data source.

Methods

function getMonitorStatus($status_id = NULL)
This method will return either a single Monitor Status record (defined by $status_id), or an array containing all monitor status entries. Will return NULL if error or no entries are found.

Parameters

$status_id (numerical) If provided, will return the monitor status information that matches that status_id only. If not provided, will return all Monitor status entries.
function getPriority($priority_id = NULL)
This method will return either a single Priority record (defined by $priority_id), or an array containing all Priority entries. Will return NULL if error or no entries are found.

Parameters

$priority_id (numerical) If provided, will return the Priority information that matches that priority_id only. If not provided, will return all Priority information entries.
function getTypeRule($type_id = NULL)
This method will return either a single Type Rule record (defined by $type_id), or an array containing all Type Rule entries. Will return NULL if error or no entries are found.

Parameters

$type_id (numerical) If provided, will return the Type Rule information that matches that type_id only. If not provided, will return all Type Rule information entries.
function getComponent($component_id = NULL)
This method will return either a single Component record (defined by $component_id), or an array containing all Component entries. Will return NULL if error or no entries are found.

Parameters

$component_id (numerical) If provided, will return the Component information that matches that component_id only. If not provided, will return all Component information entries.
function getSeverity($severity_id = NULL)
This method will return either a single Severity record (defined by $severity_id), or an array containing all Severity entries. Will return NULL if error or no entries are found.

Parameters

$severity_id (numerical) If provided, will return the Severity information that matches that severity_id only. If not provided, will return all Severity information entries.
function getOperationStatus($operation_status_id = NULL)
This method will return either a single Operation Status record (defined by $operation_status_id), or an array containing all Operation Status entries. Will return NULL if error or no entries are found.

Parameters

$operation_status_id (numerical) If provided, will return the Operation Status information that matches that operation_status_id only. If not provided, will return all Operation Status information entries.
function getMessageFilter($filter_id = NULL)
This method will return either a single Message Filter record (defined by $filter_id), or an array containing all Message Filter entries. Will return NULL if error or no entries are found.

Parameters

$filter_id (numerical) If provided, will return the Message Filter information that matches that filter_id only. If not provided, will return all Message Filter information entries.
function getConsolidationCriteria($criteria_id = NULL)
This method will return either a single Consolidation Criteria record (defined by $criteria_id), or an array containing all Consolidation Criteria entries. Will return NULL if error or no entries are found.

Parameters

$criteria_id (numerical) If provided, will return the Consolidation Criteria information that matches that criteria_id only. If not provided, will return all Consolidation Criteria information entries.
function getLogPerformanceData($data_id = NULL)
This method will return either a single Log Performance Data record (defined by $data_id), or an array containing all Log Performance entries. Will return NULL if error or no entries are found.

Parameters

$data_id (numerical) If provided, will return the Log Performance Data information that matches that data_id only. If not provided, will return all Log Performance Data information entries. **It is NOT recommended to pull all records, as this may take a lot of time to process**
function getCheckType($check_type_id = NULL)
This method will return either a single Check Type record (defined by $check_type_id), or an array containing all Check Type entries. Will return NULL if error or no entries are found.

Parameters

$check_type_id (numerical) If provided, will return the Check Type information that matches that check_type_id only. If not provided, will return all Check Type information entries.
function getLogMessage($message_id = NULL)
This method will return either a single Log Message (defined by $criteria_id), or an array containing all Log Messages. Will return NULL if error or no messages are found.

Parameters

$message_id (numerical) If provided, will return the Log Message that matches that message_id only. If not provided, will return all Log Messages. **It is NOT recommended to pull all records, as this may take a lot of time to process**
function getStateType($type_id = NULL)
This method will return either a single State Type record (defined by $type_id), or an array containing all State Type entries. Will return NULL if error or no entries are found.

Parameters

$type_id (numerical) If provided, will return the State Type that matches that type_id only. If not provided, will return all State Type entries.
function getServiceAvailability($availability_id = NULL)
This method will return either a single Service Availability record (defined by $availability_id), or an array containing all Service Availability entries. Will return NULL if error or no entries are found.

Parameters

$availability_id (numerical) If provided, will return the Service Availability record that matches that availability_id only. If not provided, will return all Service Availability entries.
function getHostAvailability($availability_id = NULL)
This method will return either a single Host Availability record (defined by $availability_id), or an array containing all Host Availability entries. Will return NULL if error or no entries are found.

Parameters

$availability_id (numerical) If provided, will return the Host Availability record that matches that availability_id only. If not provided, will return all Host Availability entries.
function getMonitorServer($server_id = NULL)
This method will return either a single Monitor Server record (defined by $server_id), or an array containing all Monitor Server entries. Will return NULL if error or no entries are found.

Parameters

$server_id (numerical) If provided, will return the Monitor Server record that matches that server_id only. If not provided, will return all Monitor Server entries.
function getMonitorList($server_id = NULL)
Normally used to get a list of devices that are assigned to a Monitor Server (defined by $server_id). If not provided, will return the entire list of assignments.

Parameters

$server_id (numerical) If provided, will return all entries that matches that server_id only. If not provided, will return all Monitor List entries.
function getMonitorListByDevice($device_id = NULL)
Used to determine which Monitor Server monitors a specific Device (defined by $device_id). If not provided, will return the entire list of assignments.

Parameters

$device_id (numerical) If provided, will return the Monitor List entry that matches that device_id. If not provided, will return all Monitor List entries.
function getDevice($device_id = NULL)
Will return the Device information for the specific Device (defined by $device_id), or a list of all devices and their properties.

Parameters

$device_id (numerical) If provided, will return the Device entry that matches that device_id. If not provided, will return all Device entries.
function getDeviceParents($device_id = NULL)
Will return a list of records which Device (defined by $device_id) is a child of.

Parameters

$device_id (numerical) If provided, will return the Device Parent entries that matches that device_id. If not provided, will return all Device Parent entries.
function getDeviceChildren($device_id = NULL)
Will return a list of records which Device (defined by $device_id) is a parent of another Device.

Parameters

$device_id (numerical) If provided, will return the Device Parent entries that matches that device_id. If not provided, will return all Device Parent entries.
function getSchemaInfo()
Returns the data listed in SchemaInfo. (Used to determine what version of Collage you are running, and when it was created in the server).

Parameters

None None
function isError()
Returns true if the previous operation failed.

Parameters

None None
function get_error_num()
Returns the error num which matches the definitions of error codes provided at the end of this document.

Parameters

None None

Collage Host Group Query

 Instances of this class extend Collage (inherits all methods), but provides a more specific interface to receive Host Group related information.

Constructor

(Uses the same as Collage)

Methods

function getServicesForHostGroup($hostGroup)
Will return all ServiceStatus information for all services for all hosts which are assigned to the host group (Defined by $hostGroup).

Parameters

$hostGroup (text) The short name of the hostgroup you wish to query for.
function getHostGroups()
Will return a list of all Host Groups defined.

Parameters

None None
function getHostsForHostGroup($hostGroup)
Will return all associated hosts that are assigned to the host group (defined by $hostGroup).

Parameters

$hostGroup (text) The short name of the hostgroup you wish to query for.
function getHostGroup($hgName)
Will return Host Group (defined by $hgName) information.

Parameters

$hgName (text) The short name of the hostgroup you wish to query for.

Collage Host Query

 Instances of this class extend Collage (inherits all methods), but provides a more specific interface to receive Host related information.

Constructor

(Uses the same as Collage)

Methods

function getHost($host)
Will return Host (defined by $host) information.

Parameters

$host (text) The short name of the host you wish to query for.
function getHostByID($id)
When a record returned by another method provides you with a host id, you can use this method to retrieve the information regarding that host (defined by $id).

Parameters

$id (text) The ID of the host you wish to query for.
function getServicesForHost($host)
Will return all service status information associated with the services for the host (defined by $host).

Parameters

$host (text) The shortname of the host you wish to query for.
function getHostStatusForHost($host)
Will return the Host Status information for the Host (defined by $host).

Parameters

$host (text) The shortname of the host you wish to query for.
function getDeviceForHost($host)
Will return the Device information which is associated with the Host (defined by $host).

Parameters

$host (text) The shortname of the host you wish to query for.
function getHostsByFilter($filter)
If you want to get a list of hosts which match criteria in Host Status information, provide a filter to this method to get a list which matches your filter.

Parameters

$filter (multi-dimensional array) A filter array which specifies the filtered information you wish to receive. Each entry of the array must have 3 elements. "key" => The column you wish to match against, "operator" => The SQL- compliant operator to match the column against the value, "value" => The value you wish to match against.

Collage Service Query

 Instances of this class extend Collage (inherits all methods), but provides a more specific interface to receive Service related information.

Constructor

(Uses the same as Collage)

Methods

function getService($serviceDescription, $hostName)
Will return Service Status information which matches the Host (defined by $hostName) and the Service Description (defined by $serviceDescription).

Parameters

$serviceDescription (text) The service description of the service you wish to query for. $hostName (text): The short name of the host you wish to query for.
function getServices()
Will return all Service Status information for all services.

Parameters

None None
function getServicesByFilter($filter)
If you want to get a list of services which match criteria in Service Status information, provide a filter to this method to get a list which matches your filter.

Parameters

$filter (multi-dimensional array) A filter array which specifies the filtered information you wish to receive. Each entry of the array must have 3 elements. "key" => The column you wish to match against, "operator" => The SQL- compliant operator to match the column against the value, "value" => The value you wish to match against.

Collage Event Query

 Instances of this class extend Collage (inherits all methods), but provides a more specific interface to receive Event (Log Messages) related information.

Constructor

(Uses the same as Collage)

Methods

function getEventsForDevice($identification, $timeField = NULL, $fromDate = NULL, $toDate = NULL, $rows = NULL, $offset = NULL)
Will return Events which have occured based on the criteria passed via the parameters.

Parameters

$identification (numerical) The ID of the Device you wish to query for.
$timeField (FirstInsertDate || LastInsertDate) Either of the two strings, will match against the timeframe provided by $fromDate and $toDate. If not provided, will not filter against a time frame.
$fromDate (date: (yyyy-mm-dd) If $timeField is specified, $fromDate will specify the beginning of the time frame you wish to match against.
$toDate (date: (yyy-mm-dd) If $timeField is specifried, $toDate will specify the end of the time frame you wish to match against.
$rows (numerical): If provided, will specify to only return a certain amount of records.
$offset (numerical): If the number of records are greater than $rows, then $offset will specify at which record you want to start returning information.
function getEventsForService($serviceDescription, $hostName, $timeField = NULL, $fromDate = NULL, $toDate = NULL, $rows = NULL, $offset = NULL)
Will return Events which have occured based on the criteria passed via the parameters.

Parameters

$serviceDescription (text) The service description of the service you wish to query for.
$hostName (text) The short name of the host you wish to query for.
$timeField (FirstInsertDate || LastInsertDate) Either of the two strings, will match against the timeframe provided by $fromDate and $toDate. If not provided, will not filter against a time frame.
$fromDate (date: (yyyy-mm-dd) If $timeField is specified, $fromDate will specify the beginning of the time frame you wish to match against.
$toDate (date: (yyy-mm-dd) If $timeField is specifried, $toDate will specify the end of the time frame you wish to match against.
$rows (numerical) If provided, will to only return a certain amount of records.
$offset (numerical) If the number of records are greater than $rows, then $offset will specify at which record you want to start returning information.
function getEventsForHost($hostName, $timeField = NULL, $fromDate = NULL, $toDate = NULL, $rows = NULL, $offset = NULL)
Will return Events which have occured based on the criteria passed via the parameters.

Parameters

$hostName (text) The short name of the host you wish to query for.
$timeField (FirstInsertDate || LastInsertDate) Either of the two strings, will match against the timeframe provided by $fromDate and $toDate. If not provided, will not filter against a time frame.
$fromDate (date: (yyyy-mm-dd) If $timeField is specified, $fromDate will specify the beginning of the time frame you wish to match against.
$toDate (date: (yyy-mm-dd) If $timeField is specifried, $toDate will specify the end of the time frame you wish to match against.
$rows (numerical) If provided, will specify to only return a certain amount of records.
$offset (numerical) If the number of records are greater than $rows, then $offset will specify at which record you want to start returning information.