Function Reference

Introduction

This is by no means meant to be an exhaustive list of the functions available in Nagios Fusion. These are the most common ones that will be used by extending Fusion by building custom components and dashlets.

If you have any questions or require clarification, don't hesitate to visit the Nagios Support Form!

Details

`register_component`

Description

Registers a component with Fusion.

Usage register_component($opts)

Arguments

Argument	Type	Info
`$opts`	Array	An array of component options. More details are on the Components page.

Return

Returns a boolean representing if the function was successful

`register_dashlet`

Description

Registers a dashlet with Fusion.

Usage register_dashlet($opts)

Arguments

Argument	Type	Info
`$opts`	Array	An array of dashlet options. More details are on the Dashlets page.

Return

Returns a boolean representing if the function was successful

`register_callback`

Description

Register a function to be executed when a specific callback occurs. The function you specify must accept two arguments, the first will be the callback being performed, and the second will be an array of data passed. Generally called $cbtype and $cbargs.

Usage register_callback($cbtype, $func)

Arguments

Argument	Type	Info
`$cbtype`	CALLBACK TYPE	One of the callbacks listed on the Callbacks Reference page.
`$func`	Callback	The function to execute once the callback occurs.

`get_dashlet_dependent_params`

Description

Used by dashlets as a generic DASHLET_PARAMS value which will supply a server/host/service combination for the parameters of that dashlet.

Usage get_dashlet_dependent_params($get_servers = true, $get_hosts = true, $get_services = true, $server_type = SERVER_TYPE_FUSION)

Arguments

Argument	Type	Info
`$get_servers`	Bool	Return servers
`$get_hosts`	Bool	Return hosts
`$get_services`	Bool	Return services
`$server_type`	Int	Bit field of `SERVER_TYPE_CORE` and/or `SERVER_TYPE_XI` (both together is `SERVER_TYPE_FUSION`).

Return

Returns an array containing the specified options suitable for passing to a DASHLET_PARAMS.

`get_dashlet_dependent_request_vars`

Description

This function is used in conjunction with get_dashlet_dependent_params. Used in dashlet pages to grab the server/host/service combination of query parameters.

Usage get_dashlet_dependent_request_vars(&$server, &$host, &$service)

Arguments

Argument	Type	Info
`$server`	Mixed	The variable will be populated with the value from the query parameter 'server'
`$host`	Mixed	The variable will be populated with the value from the query parameter 'host'
`$service`	Mixed	The variable will be populated with the value from the query parameter 'service'

`pack_array`

Description

Used to pack an array for storage in the database.

Usage pack_array($arr)

Arguments

Argument	Type	Info
`$arr`	Array	The array to pack

Return

Returns a base64 encoded and serialized array (or just what was originally passed on failure).

`unpack_array`

Description

Unpack a previously packed array (using pack_array).

Usage unpack_array($packed)

Arguments

Argument	Type	Info
`$packed`	String	A base64 encoded serialized array suitable for unpacking.

Return

Returns an array (or just what was originally passed on failure).

`dashlets_data_check`

Description

This function serves to check to see if any data exists in the polling database.

Usage dashlets_data_check($redirect = true)

Arguments

Argument	Type	Info
`$redirect`	Boolean	Redirect the page

Return

If there is data then this function returns true, otherwise if $redirect is true then there is no return and the location is reset via header(), or else false is returned.

`get_servers`

Description

Return an array of all of the servers that are fused.

Usage get_servers($enabled_servers_only = true, $include_exclusions = true, $order_alphabetically = true)

Arguments

Argument	Type	Info
`$enabled_servers_only`	Boolean	If true, only enabled servers are returned
`$include_exclusions`	Boolean	If true, only displays servers the currently logged in user has access to
`$order_alphabetically`	Boolean	If true, order the servers alphabetically before returning

Return

Returns an array of fused servers based on the options specified, or false if none or error.

`get_server`

Description

Retrieve specific server data based on a server's database id or validates an existing server array.

Usage get_server($server_data)

Arguments

Argument	Type	Info
`$server_data`	Mixed	Either a server id, or an array already populated with server data

Return

Returns an associative array of fused server data, or false on failure.

`get_server_polled_key`

Description

Grab all existing entries of a key in the polled data tables or a certain number based on the limit supplied.

Usage get_server_polled_key($server, $key, $limit = 0, $user_id = 0)

Arguments

Argument	Type	Info
`$server`	Mixed	Either a server id or a server array
`$key`	String	The polled key to grab (see Poll Callback Reference)
`$limit`	Int	How many entries to limit the grabbing to, 0 means no limit
`$user_id`	Int	The user to limit the data to, 0 means current logged in user

Return

Returns an associative array that is required to cycle through and run unpack_array on. Example:

$service_status = get_server_polled_key($server, 'service_status', $limit = 1);
$services = unpack_array($service_status[0]['service_status']);

`get_appended_server_url`

Description

Build a URL dependent on the type of server passed.

Usage get_appended_server_url($url, $server_type, $authentication_type, $xi_fusekey = null, $xi_session = null, $core_basic = null)

Arguments

Argument	Type	Info
`$url`	String	The URL of the current server the URL is being built for
`$server_type`	Int	Bit field of `SERVER_TYPE_CORE` and/or `SERVER_TYPE_XI` (both together is `SERVER_TYPE_FUSION`)
`$authentication_type`	Int	The authentication type used by the current server the URL is being built for
`$xi_fusekey`	String	The string to append to the URL if the server/auth type is xi/fusekey
`$xi_session`	String	The string to append to the URL if the server/auth type is xi/session
`$core_basic`	String	The string to append to the URL if the server/auth type is core/basic

Return

Returns a fully built URL depending on the options specified. Example usage (building)

$url = get_appended_server_url($url, $server_type, $authentication_type, 
    "api/v1/objects/",
    "backend/",
    "statusjson.cgi")

Where $url will append api/v1/objects to the $url passed if $server_type is SERVER_TYPE_XI and $authentication_type is AUTH_TYPE_FUSEKEY.

`child_page`

Description

Prints a child page (one of the inner frame pages), and includes all of the headers. Automatically handles the closing of the page as well.

Usage child_page($page_title, $opts = array(), $page = null)

Arguments

Argument	Type	Info
`$page_title`	String	The title of the page to print
`$opts`	Array	Options to pass
`$page`	String	sometding else

`$menu->add_link`

Description

Add a link to the side navigation menu object.

Usage add_link($link, $search_section_id, $terms = null)

Arguments

Argument	Type	Info
`$link`	Array	The link to add (built with `menu_link()`)
`$search_section_id`	String	The section to add the link to
`$terms`	String	The terms of the link addition. Some examples: `'before:{link_id}'`,`'before:{link_title}'` will go before the specified link_id/link_title, `'after:{link_id}'`,`'after:{link_id}'` will go after the specified link_id/link_title, `'before'` will go at the beginning of the section, `array('before' => {link_id})` will go before the specified link_id, etc.

`$menu->add_link_spacer`

Description

Add a link spacer to the side navigation menu object.

Usage add_link_spacer($search_section_id, $terms = null)

Arguments

Argument	Type	Info
`$search_section_id`	String	The section to add the link to
`$terms`	String	The terms of the link spacer addition. Same `$terms` as `$menu->add_link()`

`menu_link`

Description

Build a link to insert into the $menu object.

Usage menu_link($title = '', $href = '', $class = '', $id = '', $icon = '', $target = '', $raw = '')

Arguments

Argument	Type	Info
`$title`	String	The title of the link
`$href`	String	The href URL to link to
`$class`	String	An additional class to append to the wrapping `<li>` tag
`$id`	String	An id to specify for the wrapping `<li>` tag
`$icon`	String	A fontawesome icon to include beside the link
`$target`	String	The target in which the link will open (defaults to the innerframe)
`$raw`	String	Any additional raw `attribute="value"` you wish to include inside of the `<a> tag`

`grab_request_var`

Description

Nagios wrapper function for grabbing values from $_REQUEST (and friends).

Usage grab_request_var($varname, $default = "")

Arguments

Argument	Type	Info
`$varname`	String	The name of the `$_REQUEST` variable to grab
`$default`	String	The default value to return if no matching request variable was found

Return

Returns either the $_REQUEST variable found, or the $default specified.

`grab_array_var`

Description

Nagios wrapper function for grabbing values from PHP arrays with minimal effort.

Usage grab_array_var($arr, $key, $default = '')

Arguments

Argument	Type	Info
`$arr`	Array	The array from which to grab the specified index
`$key`	String	The array index to attempt and grab data from
`$default`	String	The value to return if the index specified by `$key` didn't exist

Return

Returns either $arr[$key] if found, or the $default specified.

`set_option`

Description

Sets an option in the options table of the fusion database (a basic key/value store).

Usage set_option($name, $value)

Arguments

Argument	Type	Info
`$name`	String	The name (key) of the option to set (will overwrite any pre-existing option by this name)
`$value`	String	The value of the option to set

`get_option`

Description

Get the value of an option that exists in the options table in the fusion database (a basic key/value store).

Usage get_option($name, $default = null)

Arguments

Argument	Type	Info
`$name`	String	The name (key) of the option whose value we want
`$default`	Mixed	If no option existed by the name specified, use this value

Return

Returns the option's value if found, $default specified otherwise.

`set_array_option`

Description

Use this to set an option that's an array. It uses the pack_array() function before calling set_option().

Usage set_array_option($name, $array)

Arguments

Argument	Type	Info
`$name`	String	The name (key) of the option to set (will overwrite any pre-existing option by this name)
`$array`	String	The array to pack and then set as the option's value

`get_array_option`

Description

Get the value of an option that exists that has been set using the set_array_option() function.

Usage get_array_option($name, $default = array())

Arguments

Argument	Type	Info
`$name`	String	The name (key) of the option whose value we want
`$default`	Mixed	If no option existed by the name specified, use this value

Return

Returns the option's unpacked value if found, $default specified otherwise.

`register_poll_callback`

Description

Register a predefined end point for Fusion to connect to during polling. You may optionally also specify the function that transforms the raw data into the proper format for database inclusion.

Usage register_poll_callback($server_type, $poll_type, $cb = null)

Arguments

Argument	Type	Info
`$server_type`	Int	The server type to register for (`SERVER_TYPE_XI` or `SERVER_TYPE_CORE`)
`$poll_type`	Int	The poll type to register. This is one of: `POLL_TYPE_HOSTSTATUS`, `POLL_TYPE_SERVICESTATUS`, `POLL_TYPE_ALERTS`, `POLL_TYPE_NOTIFICATIONS`, `POLL_TYPE_STATEHISTORY`, `POLL_TYPE_COMMENT`, `POLL_TYPE_DOWNTIME`, `POLL_TYPE_CONTACT`, `POLL_TYPE_HOST`, `POLL_TYPE_SERVICE`, `POLL_TYPE_HOSTGROUP`, `POLL_TYPE_SERVICEGROUP`, `POLL_TYPE_CONTACTGROUP`, `POLL_TYPE_HOSTGROUPMEMBERS`, `POLL_TYPE_SERVICEGROUPMEMBERS`, `POLL_TYPE_CONTACTGROUPMEMBERS`, `POLL_TYPE_STATUS`, or `POLL_TYPE_USER`
`$cb`	String	The function to pass the raw data collected to. The function must accept an array of raw data returned, and should return an array in the form of `array('key' => 'value) for inclusion into the poll tables`

`flash_message`

Description

Flash a message to be displayed using the message banner on next page load.

Usage flash_message($text, $type = 'info', $options = array())

Arguments

Argument	Type	Info
`$text`	String	The message to flash
`$type`	String	The type of message (`info`, `success`, or `error`)
`$options`	Array	An array of options (`details`[String], `persistent`[Boolean], `dismissable`[Boolean])

`get_base_dir`

Description	Get the location of Fusion's html directory.
Usage	`get_base_dir()`
Return	Returns the html directory (e.g.: `/usr/local/nagiosfusion/html`).

`convert_server_timestring_to_local_timestring`

Description

Convert a given timestring (passed to strtotime) to the given server's timezone.

Usage convert_server_timestring_to_local_timestring($server, $timestring)

Arguments

Argument	Type	Info
`$server`	Mixed	The server id or an array containing the server data whose timezone we should convert to
`$timestring`	String	The timestring to convert

Return

Returns

`get_formatted_number`

Description

Convert a given number to the logged in user's specified number format

Usage get_formatted_number($num = 0, $dec = -1, $format = NF_AUTO)

Arguments

Argument	Type	Info
`$num`	Int	The number to convert
`$dec`	Int	If less than 0 automatically determine the decimal places, otherwise specify
`$format`	Int	The specified format. `NF_1` for English, `NF_2` for German, `NF_3` for French, `NF_4` for Swiss

Return

Return a formatted number.

`user_date`

Description

Convert a unix timestamp into the specified user's preferred datetime format.

Usage user_date($time = null, $user_id = 0)

Arguments

Argument	Type	Info
`$time`	Int	The unix timestamp to convert
`$user_id`	Int	The user_id's datetime format to convert to, 0 means current logged in user

Return

Returns the converted datetime format.

`get_base_url`

Description

Get the base URL of the Fusion server.

Usage get_base_url($usefullpath = true)

Arguments

Argument	Type	Info
`$usefullpath`	Boolean	If true then use the entire URL, otherwise it will return as a server-local address (e.g.: `/nagiosfusion/so/on/and/so/forth.php`)

Return

Returns the base URL of the Fusion server.

`get_dashlets_base_url`

Description

Get the dashlets URL of the Fusion server.

Usage get_dashlets_base_url($usefullpath = false)

Arguments

Argument	Type	Info
`$usefullpath`	Boolean	If true then use the entire URL, otherwise it will return as a server-local address (e.g.: `/nagiosfusion/so/on/and/so/forth.php`)

Return

Returns the base dashlets URL of the Fusion server.

`get_components_base_url`

Description

Get the components URL of the Fusion server.

Usage get_components_base_url($usefullpath = false)

Arguments

Argument	Type	Info
`$usefullpath`	Boolean	If true then use the entire URL, otherwise it will return as a server-local address (e.g.: `/nagiosfusion/so/on/and/so/forth.php`)

Return

Returns the base components URL of the Fusion server.

`get_image_url`

Description

Get a specified image's URL from the Fusion server.

Usage get_image_url($img)

Arguments

Argument	Type	Info
`$img`	String	The image located in `/static/images` whose URL you'd like

Return

Returns the specified image's URL.

`get_icon_url`

Description

Get a specified icons's URL from the Fusion server.

Usage get_icon_url($img)

Arguments

Argument	Type	Info
`$img`	String	The icon located in `/static/images/icons` whose URL you'd like

Return

Returns the specified icon's URL.

`get_base_uri`

Description

Get the Fusion server's base URI.

Usage get_base_uri($usefullpath = true)

Arguments

Argument	Type	Info
`$usefullpath`	Boolean	If true then use the entire URL, otherwise it will return as a server-local address (e.g.: `/nagiosfusion/so/on/and/so/forth.php`)

Return

Returns the Fusion server's base URI.

Getting Started

Components

Dashlets

Function Reference

Callback Reference

Poll Callback Reference

Function Reference

Introduction

Details

register_component

register_dashlet

register_callback

get_dashlet_dependent_params

get_dashlet_dependent_request_vars

pack_array

unpack_array

dashlets_data_check

get_servers

get_server

get_server_polled_key

get_appended_server_url

child_page

$menu->add_link

$menu->add_link_spacer

menu_link

grab_request_var

grab_array_var

set_option

get_option

set_array_option

get_array_option

register_poll_callback

flash_message

get_base_dir

convert_server_timestring_to_local_timestring

get_formatted_number

user_date

get_base_url

get_dashlets_base_url

get_components_base_url

get_image_url

get_icon_url

get_base_uri

Functions

`register_component`

`register_dashlet`

`register_callback`

`get_dashlet_dependent_params`

`get_dashlet_dependent_request_vars`

`pack_array`

`unpack_array`

`dashlets_data_check`

`get_servers`

`get_server`

`get_server_polled_key`

`get_appended_server_url`

`child_page`

`$menu->add_link`

`$menu->add_link_spacer`

`menu_link`

`grab_request_var`

`grab_array_var`

`set_option`

`get_option`

`set_array_option`

`get_array_option`

`register_poll_callback`

`flash_message`

`get_base_dir`

`convert_server_timestring_to_local_timestring`

`get_formatted_number`

`user_date`

`get_base_url`

`get_dashlets_base_url`

`get_components_base_url`

`get_image_url`

`get_icon_url`

`get_base_uri`