How to use Gondul templating
============================

We utilize Jinja2 templates.

See http://jinja.pocoo.org/ for the full documentation of the templating
language.

The rest of this document is about templating as it relates to Gondul

Neat: This document is an actual template, so the examples are working
examples.

URLs
====

To read raw (unprocessed) templates, see http://nms/templates

To see the rendered final result, see http://nms/api/templates

Basics
======

Gondul provides templating through two different, but similar mechanisms.

First, there are permanent templates, or server-side templates. These are
templates stored on the server and accessible by all Tech crew/equipment.

These are fetched typically through a HTTP GET request. E.g.:

http://nms/api/templates/switches.txt

Secondly, you can write templates yourself and POST them to Gondul. This is
highly useful for one-off templates or template development. The syntax is
the same.

Simply write a template-file and POST it with your favorite command-line
tool to:

http://nms/api/templates/WHATEVER

Example:

POST http://nms/api/templates/foobar < my-local-template

Available objects
=================

Gondul templates have two dictionaries available for general use. The first
is "options". This is a simple list of GET parameters. If you access
http://nms/api/templates/HOWTO.txt?foo=bar, options[foo] will evaluate to
"bar" in that template. This can be accessed in the template as:

Foo: {{ options["foo"] }}

The second object is the "objects" ... dictionary. This is a list of all
the HTTP API end-points, in all their glory. The key is the URL.

To use this, you need to review the relevant endpoint. This is best done by
reading the API documentation (or skimming through other templates). If you
want to acces e13-2's latency, for example, you can access
objects["public/ping"].switches["e13-2"].latency4

As such: {{ objects["public/ping"].switches["e13-2"].latency4 }}

The logic is that "public/ping" is the url: http://nms/api/public/ping, it
contains JSON that begins with "switches", a list of all switches, each
switch as a "latency4" object (among other things)

Other worth-while api-endpoints:

- read/switch-management - Management information
- public/switches - All switches
- read/snmp - All SNMP data

Work flow
=========

Recommended:

1. Read some other template with relevant data.
2. Open the API endpoints in your browser to review the data structure
3. Use query-parameters to provide user-selection (e.g.: ?switch=foobar)
4. Write your template on your local machine, test frequently by POST'ing it
5. When done: Ask us and we'll upload it server-side