API-DOC

Business Process AddOn: JSON-API
================================


Starting with version 0.9.6 the Business Process AddOn for Nagios and Icinga has
got a JSON-API. This means You can query state information of business processes 
from the Business Process AddOn in JSON format to use the results e. g. in 
Your own scripts or for building up Your own GUI.

You can get any information about any business processes also by querying the
API. That means: Any information available in the Business Process AddOn 
can be requested by API too.
This document describes this API.

The JSON-API is being already used by the Business Process Cronks in the new
Icinga-Web.


Calling the API
===============

There are two ways:
1. Call a local script on the machine Business Process AddOn is running at, 
   e. g. 
	sbin/bp-addon.cgi outformat=json
   (within Business Process AddOn's install path)

2. Call the script remote by HTTP(S):
	http://nagioshost.example.com/bp-addon/cgi-bin/bp-addon.cgi?outformat=json
   Normally You have to give username and password by HTTP basic auth.
   A browser asks for Your credentials, but on a script You have to add them, 
   e. g.
	curl -u nagiosadmin:secret http://nagioshost.example.com/bp-addon/cgi-bin/bp-addon.cgi?outformat=json

In both cases You get back a data structure in JSON format. There are modules
for every common scriping language to read JSON. Use them!


Parameters
==========

By adding more parameters when calling You can decide what information You want
to get. Append these parameters with a blank when calling local and with a & 
when using HTTP(S).
e. g.
	sbin/bp-addon.cgi outformat=json tree=mail
or
	http://nagioshost.example.com/bp-addon/cgi-bin/bp-addon.cgi?outformat=json&tree=mail

If none of the parameters tree or detail is given, a complete list of all
defined business processes is returned, the default view.

tree
----
	give the name of a business process as argument, e. g.
	tree=mail

	returns: only one level of hierarchy in the tree of one business process

	excludes: detail
	(give parameter tree or detail or none of them, but never both)

detail
------
	give the name of a business process as argument, e. g.
	detail=mail

	returns: plain list of all components in this business process without 
	hierarchy, going down recursively

	excludes: tree
	(give parameter tree or detail or none of them, but never both)

conf
----
	give the name of one config as argument, e. g.
	conf=business-processes-second-view
	to read definition of business processes from 
	etc/business-processes-second-view.conf
	instead of default file
	etc/business-processes.conf

	hint: leave out the path of the file and the .conf extension
	
lang
----
	give wanted language of output as argument, e. g.
	lang=en

	it is only used to determine from which language files You want to
	take strings for display_prio_description and display_prio_headline

trafficlight
------------
	can be "yes", "only" or "short"
	(same as in html view, but not so self explaning in json context)
	trafficlight=yes
	is the default.
	
	give
	trafficlight=only
	or
	trafficlight=short
	if You want to get only the over all status for each priority
	but no status information of single business processes

	only valid in the default view
	excludes: detail, tree


Output Description
==================

The resulting JSON at the top level contains a hash map with the following
keys:

business_processes
	only in default view
	refers to a section with all the business processes 

business_process
	only in tree or detail view
	refers to a section with all components of the given business process

priority_definitions
	refers to a section giving display strings and over all status for 
	every priority used in any of the business processes found in the 
	business_process section. Parameter lang is only for this section.

json_created
	refers to a very simple section containing only on timestamp when this
	output was created


Output sections in detail
=========================

business_processes
------------------

hashmap with references to business_process objects
key is the business process name

business_process
----------------

hashmap with following keys, where values are taken from the business process 
definition

bp_id
	the name of a business process
display_name
	the string for displaying it
display_prio
	in which prio is the process displayed 
	may be 0 if not displayed in the top level view of the web GUI
info_url
	the URL You get to when clicking the little blue i icon on the GUI
operator
	the operator used in definition of this process
	may be: and, or, of
hardstate
	the actual (hard) state of this business process
components
	array with all components
	see description of components below


components
----------

array of components
in tree view or detail view components can be subprocesses or single services
in detail view components are always single services

subprocesses have fields:

subprocess
	the name of a subprocess
display_name
	the string for displaying this subprocess
hardstate
	the actual (hard) state of this subprocess
display_prio
	in which prio is the subprocess displayed 
	may be 0 if not displayed in the top level view of the web GUI


single services have fields:

host
	hostname of the service
service
	servicename of the service
hardstate
	the actual (hard) state of this service
plugin_output
	the plugin output of last check of this service



priority_definitions
--------------------

hashmap to priority definitions and over all status
key is the id of the priority
fields:

display_prio_headline
	headline defined in language file for this priority

display_prio_description
	description defined in language file for this priority

hardstate
	the status of every business process in the given priority is taken
	from all of them an "AND" conjunction is made
	the result is called the over all status of the priority
	this value is given as hardstate of the priority
	(simplified You can say: the worst status of any business process
	in the given priority)


json_created
------------

just a timestamp in format YYYY-MM-DD hh:mm:ss