- 1.0 About Perl API Monarch
- 1.1 Classes and Methods
- 1.2 dassmonarch Perl API Example
- 1.3 Standalone Monarch configuration scripts
- 2.0 About Perl API
- 3.0 About PHP Foundation API
- 4.0 About Web Services API
dassmonarch is a Perl API to GroundWork Monitor. It provides an API to program configuration changes of the GroundWork Monitor system. The Perl API is published under GPL and is free for download. Almost the same functionality is available as an additional SOAP interface, which lets you access and modify the GroundWork configuration by a remote SOAP client. The SOAP interface is available from dass IT under a commercial license. Thanks to dass-IT - Maik Aussendorf for contributing the Perl configuration API to Monarch.
Following is a complete reference of the GWHelper Class and the dassmonarch Class. Additionally you can view a simple example application for dassmonarch and extended information for externals routine calling sequences.
This class provides methods related to the installed GroundWork system like determining GroundWork's release version, etc. This version is for use with GW Monitor 6.2 and later releases ONLY.
- GWHelper Class Reference - Select this link for a list of members and links to function documentation.
This class provides relevant methods to access the monarch DB in order to automatically import configuration data.
- dassmonarch Class Reference - This reference provides a list of members and links to function documentation which describes in detail every method including parameters and return values.
- dassmonarch Externals Routine Calling Sequences - Additionally, here you can access a more detailed look at externals routine information.
This link displays a simple example application for dassmonarch Perl API to GroundWork Monarch. This is not for the SOAP interface, only for the local class.
Along with the extensions to dassmonarch for the 7.1.0 release, there are now standalone scripts that exercise certain parts of dassmonarch functionality. This means that for certain common simple tasks, an administrator need not dive down to the dassmonarch level to get these tasks done from the command line. The names of the scripts are somewhat descriptive however further documentation can be obtained by listing out the help for each as shown below.
The new scripts all live in the /usr/local/groundwork/core/monarch/bin directory.
There are two means to obtain simple documentation on each of these scripts. The first is to run perldoc on the script; this will produce documentation in the style of a man page. For example:
Very terse documentation is also available by running the script with the -h option. This mostly just shows the available command-line options, with little explanation. For example:
In addition to those scripts, which are directly associated with the dassmonarch package, we have also added two other scripts:
- monarch_assign_contactgroups_to_hostgroup_hosts_and_host_services - This can be used to manage contact groups at the hostgroup level and can save you from having to crawl through a lot of screens to manually do a lot of configuration work. Currently, there is no perldoc documentation for this script, but the -h option will spill out a long usage message, which currently reads like this:
- monarch_restore_from_backup - This is referenced by the new Backup code within the Monarch UI. This script is not run automatically from the UI (Configuration > Control > Backup and restore). Instead, when you request the UI to restore a particular backup, it instead composes the full invocation of this script that you will need to run from the command line, and displays that command in the browser. Documentation is available in both perldoc and -h forms.
The Perl API is a module called CollageQuery which allows a Perl program to retrieve data from Collage. Also see the Perl API example using CollageQuery module. The following classes and methods are available for the Perl API.
- new - Create the CollageQuery object. Required to use any of the following methods.
- destroy - Destroys the CollageQuery object. Should be called when the CollageQuery object is no longer needed.
- getServicesForHostGroup(String hostGroup) - Returns a reference to a hash host-service-attributes for a designated Host Group.
- getHostsForHostGroup(String hostGroup) - Returns a reference to a hash of all Host names, device names for a designated Host Group.
- getHostGroups() - Returns a reference to all Host Group names, descriptions.
- getHostGroup(String hgName) - Returns a hash containing the attributes for a Host Group.
- getServicesForHost(String host) - Returns a reference to a hash of all services-attributes for a Host.
- getHosts() - Returns a reference to a hash of all Host-attributes.
- getHostStatusForHost(String host) - Returns a hash of all the status attributes for a Host.
- getDeviceForHost(String host) - Returns a hash of the device attributes for a Host.
- getService(String serviceName, String hostName) - Returns a hash of service attributes.
- getServices() - Returns a reference to a hash of host-service-attributes.
- getMonitorServers - Returns a reference to a hash of monitorserver-attributes.
- getHostsForMonitorServer(String MonitorServer) - Returns a reference to a hash of Hosts for a designated monitorserver.
- getHostGroupsForMonitorServer(String MonitorServer) - Returns a reference to a hash of host groups-attributes.
These methods return a reference to a hash of events with the event ID as primary key and attributes as secondary key.
|timeField (String) can be "FirstInsertDate" or "LastInsertDate;" if it's NULL, no range will be applied.|
- getEventsForDevice(String identification, String timeField, Date fromDate, Date toDate)
- getEventsForService(String serviceDescription, String HostName, String timeField, Date fromDate, Date toDate)
- getEventsForHost(String HostName, String timeField, Date fromDate, Date toDate)
The following code is a Perl API example using CollageQuery module.
The examples that use the Perl CollageQuery API are as follows. These files can be found at this link Perl Examples.
- test1.pl - This script exercises each method in the API. It is invoked via command line and returns the result to STDOUT.
- api_sample2.pl - This is a CGI program that allows you to select the Collage class and method to test. The drop down selection lists use the API to give you options from the Foundation data store. The form will show the results of the query.
- api_sample3.pl - This is a modified version of api_sample2.pl that outputs data in a more user-friendly form.
GroundWork Monitor includes an API called PHP Foundation API for PHP applications that internally uses the Foundation Web Services to query for monitoring data. In previous versions of GroundWork Monitor the API called, CollageDB API, is marked as deprecated and any new development should use the new PHP Foundation API.
The PHP Foundation API is a wrapper around a soap client that communicates to the Web Service Interface of GroundWork Foundation. With this architecture change applications written in PHP using the PHP Foundation API will be more scalable and perform better than with the previous API. Better performance was achieved by using the Web Service Interface that uses optimized queries and a query cache.
The PHP Foundation API requires GroundWork Foundation to be installed and accessible. The PHP wrapper classes (DAL) reside in the directory:
The /usr/local/groundwork/nagios/libexec/check_host_foundation.php script provides a simple example of the use of this API.
|The shebang line (#!) in the example below mentions php/bin/php.bin instead of php/bin/php as you would normally expect. This is because of a known problem. Contact GroundWork Support for additional information.|
To use this API, you must provide the URL to the Foundation Web Service. This URL is passed to the constructor of each DAL object when it is created. It will look something like:
If you are writing an application that is part of Groundwork Monitor, you can use the global variable $foundationModule and call the getWebServiceURL() method on it.
Select the link PHP Foundation API to view the documentation.
Adding a Web Service layer enables more applications to use and integrate with the existing Foundation Framework. The Web Service API uses SOAP (Simple Object Access Protocol) as the communication protocol. Since Web Services are a well defined and a widely used standard other technologies such as .NET or popular development tools such as Visual Studio or Java Studio Creator can be used to create UI or business components on the top of the Foundation platform.
The Web Services framework is able to scale and distribute the API more easily, than the previous API, which results in higher throughput and therefore better overall performance of large installations. The BIRT reporting feature uses the Foundation Web Service API to access data stored in the Foundation persistent store.
The Web Service API uses SOAP (Simple Object Access Protocol) as the communication protocol. Applications consume Web Service Description Language (WSDL) files in order to view and retrieve data from the endpoint (Foundation). SOAP requests are based on the WSDL file. In order to consume the Web Service, the SOAP library needs to know the following URLs:
- WSDL file location
- Schema file location
- SOAP end point
The Foundation Web Service API provides the web services listed in the table below. Web Service Description Language (WSDL) for GroundWork can be consumed by applications to view and retrieve data from the endpoint (Foundation). Select the .wsdl link in the last column of the table below to display its contents in a .pdf file.
Table: GroundWork Web Services
|Category||Categories are used to group any entities (Service, Host, Log Message, devices) and build a hierarchy. The web service allows creating, maintaining, and deleting Categories (grouping) but not the entities. The current version of GroundWork uses Categories to manage Service Groups.||fwscategory.wsdl|
|Common||Web Service API to retrieve meta data for Application Types, Statuses, etc. and to access the Action API used for custom actions from the GroundWork Console.||fwscommon.wsdl|
|Device||Web Service to maintain device entries in the foundation database. Devices are the addressable base entities for monitoring.||fwsdevice.wsdl|
|Event||Event Web Service is an API that manages LogMessage stored in Foundation.||fwsevent.wsdl|
|Host||Host Web Service is an API that manages Host entities in Foundation.||fwshost.wsdl|
|HostGroup||Host Web Service is an API that manages HostGroup entries in Foundation. HostGroup is a collection of Host entities.||fwshostgroup.wsdl|
|Model||Defines the basic types and objects used by the Foundation Web Service API.||fwsmodel.wsdl|
|RRD||Web service that retrieves images (PNG) for a set of RRD files. Calling the web service with just the Host argument will return an array of graphs that represent all services for that host. By providing the Host name/Service description, only the specific graph will be returned.||fwsrrd.wsdl|
|Service||Service web service is an API that manages all ServiceStatus objects in Foundation.||fwsservice.wsdl|
|Statistics||At runtime, Foundation generates statistics about the current state of Host/HostGroup and Service/ServiceGroup data. The web service has several methods to access this runtime data.||fwsstatistics.wsdl|
- getServiceAvailabilityForHostgroup ( hostGroupName )
Input: hostGroupName = String that defines the HostGroup name for which the Services availability percentage should be retrieved.
Return: Service availability as a double which represents the percentage of Services in the specified Hostgroup that are in Status OK
- getHostAvailabilityForHostgroup ( hostGroupName )
Input: hostGroupName = String that defines the HostGroup name for which the Host availability percentage should be retrived.
Return: Host availability as a double which represents the percentage of Hosts in the specified Hostgroup that are in Status UP.