A Wizard That Auto-Generates Lua Code

tl;dr: (For those who don’t know: tl;dr is Internet slang for “too long, didn’t read“)

• It’s easy to create web services in IGUANA that create new / restrict workflow
• I made a web service to take in a few parameters and then auto-generate the Lua code required to monitor IGUANA’s vital stats and send immediate alerts or daily reports
• You can check out the generator here: http://labs.interfaceware.com:6544/notify/
• You can learn the why and how by reading on.

Background:

One of the topics I presented on at last year’s user conference was how to build and use Web Services with IGUANA.  I wanted to show some of the amazing things you can do with IGUANA once you understand how its pieces work. Since I’m a “web” guy, it was a natural fit for me.

I started with the easy stuff: a basic overview of Web Services  and some simple examples of why, when and how you build web services with IGUANA. With that out of the way, I moved on to some of the more fun examples.

My favourite was when I demonstrated how you could use a relatively simple web service to programmatically generate code/interfaces/whatever else you want.

Why?

Here’s a common scenario: a small group of people at HQ define the “master templates” and then the larger implementation team use/modify these templates in the field for each unique implementation.

Typically, this is in relation to interfaces and is managed by a shared code-library somewhere that everyone can dip into. Seeing this in action got me thinking: Isn’t there a way I could restrict/automate this process in IGUANA? Of course there was.

What?

I didn’t have a particular interface that I wanted to create but I knew I wanted to build something for our entire user-base. So, I decided to look into alerts and reporting.

If you’re not familiar with how custom alerting works with IGUANA, here’s a quick overview:

1. Custom alerts work by monitoring IGUANA’s logs.
2. When a log entry matches the string/type your alert was monitoring for, you get an email.

This gets really powerful when you combine it with the fact that:

1. You can create your own log entries from within the translator.
2. These custom log entries can be based off of any data, lookup or event of your choosing.

 

Basically, what I’m saying is that with those two things you can create your own reporting platform that notifies you of critical and important events.

On top of that, IGUANA exposes an API that let’s you query all of the same information that’s available on the dashboard like: errors, CPU usage and Free Disk Space.

Since our API is standard (and the only thing most of you would want to customize is the threshold of when you’re notified), I created a simple form that when submitted takes your values and generates the relevant code.

In that context, our web service is going to be doing 2 things:

1. When you hit a specific URL (http://server:6544/notify/) it’s going to serve up a form.  That’s it.  While that might sound pretty simple, what’s great about that is that I don’t need to install or configure any special web server.  No Apache, no IIS, no node.js.  On any computer with IGUANA installed on it, I just create a new “From HTTPS” channel and have it return html code.  Instant web app!
2. The form is going to post back to the same channel with a new command (http://server:6544/notify/go/). The web service is going to accept all the form values, generate the new LUA script and return that it to the browser.

 

How? (The things you need to know to build your own)

1. Know what you want to build.

I jotted down a list of the items I wanted to be notified on immediately (low disk space, CPU spikes, etc) along with a list of the things I want to be informed of every day regardless of their state.  Once I had that, I was ready to start building something.

2. Look for the easy way out 

I’m lazy.  Chances are, you’re lazy too.  So, let’s not fool ourselves into thinking we’re going to build some totally unique/awesome/innovative GUI.  Instead, be sure to use tooling whenever possible.  I found an online form generator and used that to craft the HTML and JavaScript for my generator.  I made the simplest form I could with 1 field for each option.  Once I had that, I went back to the Translator for my “From HTTPS” component and dumped the HTML in its entirety into a single variable like this:

gui = [[
   <html>
      <body>
         Art's awesome form
      </body>
   </html>
]]

net.http.respond{body=gui}

(you know you can do multiline variables with [[ and ]], right?)

3. Create a template with placeholders

There’s no need for anything fancy here.  For my script, I went with something like this:

template = [[
-- A place to inject global declarations / require statements:
REPLACE_GLOBAL

function main()

   iguana.stopOnError(false)

   -- A place to inject the code that queries for stats 
   -- Injected because older versions of IGUANA do this differently
   REPLACE_GET_STATS
   
   -- A place to inject the alerting code
   REPLACE_ALERT

   -- A place to inject the daily report code
   REPLACE_DAILY
   
end
]]

4. Replace the placeholders with actual code

Once you have your template, it’s just a matter of mapping the values that are passed in via the form to variables, concatenating those variables with strings for the new script and then injecting those strings into the template.  Here’s a generic example of what that looks like:

-- Get the form values
local request = net.http.parseRequest{data=Data}
local form = request.post_params

-- Define our injection string
local inject_Global = ''
inject_Global = inject_Global .. 'alert={max={}, min={}}\n\n'

-- Check if we want to be alerted on errors
if form["Errors_On[]"] ~= nil then

   -- Get the # of errors (form.Errors) and create a string like:
   -- alert.max.Errors = 4 
   inject_Global = inject_Global .. 'alert.max.Errors = ' .. form.Errors .. '\n'

end

-- Get the template and replace the variable(s) with our newly created code
local generatedScript = template 
generatedScript = generatedScript:gsub("REPLACE_GLOBAL",inject_Global)

-- Return the finished script to the browser
net.http.respond{body=generatedScript}

And that’s it. You can add as much (or as little) conditional logic as you want. I wanted my code to be as clean as possible. So, in the working example, you’ll notice that if you uncheck an item (or whole section), there’s no longer any reference to that item in the declarations or throughout the code. I did that by grouping together my injection logic. I check to see if you want to include say, CPU usage. It is only when you say yes that I include it in the table declaration, in the global space and in the alerts.

Most importantly, the alerts/reports actually work!

Even if you don’t care to make your own code generator, you might be interested in the code I produced to generate the alerts and reports.  Everything should work, please let me know if it doesn’t. Go ahead and click the link below to get your own custom code.

http://labs.interfaceware.com:6544/notify/

A few final usage notes:

1. Be sure to select your IGUANA version from the top of the form.  The technique for grabbing stats was different in versions prior to 5.6.4, so the code changes depending on your version
2. Once you’ve generated the code, be sure to read and follow the instructions at the top of the script.  Not only do you have to copy-and-paste the code, but you also need to setup 2 new email rules.  Without them, all you’ll be doing is writing log entries.

Well, that’s all for today. If you have any questions or comments, leave them below and I’ll be here to help out!

Cheers,
-Art