Programmatically reading Iguana log entries from Lua

Introduction

There is a API object that we supply in C# and so on (Iguana 4 documentation) that allows an external program to query Iguana and get access to its logs. This API is implemented on top of a RESTful HTTP API, which itself is quite straightforward to access from Lua. The API requires the username and password of the user account you are using to access the data.

I gave it whirl a while back in response to a question from a client and it works very well.

Task [top]

How To programmatically read Iguana log entries from Lua.

Implementation [top]

This example retrieves the last 50 “Catcher” channel messages with the newest at the top:
Note: See the api_query reference for the complete syntax (all parameters and options).

function main()

   local messageId = iguana.messageId() -- get log message ID (http://help.interfaceware.com/api/#iguana_messageId)
   
   local X = net.http.get{url='http://localhost:6543/api_query',
      parameters={
         username='admin',
         password='password',
         limit   = 50,           -- show only 50 entries
         type    = 'message',    -- of type message
         source  = 'Catcher',    -- from the "Catcher" channel
         reverse = 'true',       -- with newest entries at the top
         refmsgid = 'messageId', -- unique log message ID (same as refid on http://help.interfaceware.com/v6/accessing-the-logs-from-other-applications#links)
         
         -- some other useful parameters
         -- after     = '2012/07/01 12:00:00', -- after date
         -- before    = '2012/06/01 12:00:00', -- before date
         -- filter    = 'VIP',                 -- only messages containing "VIP"
         -- deleted   = 'false',               -- exclude deleted messages
         -- debugmode = 'false'                -- exclude debug messages
      },live=true}  
   xml.parse{data=X}
end

The base of the URL and port should be the same as Iguana’s web interface. It’s part of the core of Iguana’s implementation. The API was not documented prior to now, but it is stable (since, if we ever changed it, it would break the API objects that work on top of it).

I believe the optional ‘type’ parameter can take strings in the following table:

String Code Description
messages Messages – i.e. HL7 messages that have been pushed into the queue.
ack_messages Acknowledgements – as logged by the LLP listener component
errors Errors in the logs
errors_marked Errors which have been marked
errors_unmarked Errors which have not been marked
info Informational logs
debug Debug level logs
warnings Warning level logs
successes Success messages
resubmitted Resubmitted messages.

What’s more, ‘type’ can be set to include a list of these separated by commas:

type=’messages,ack_messages’

The ‘refmsgid’ value refers to the unique number associated with each message in the logging system (for more information, see ‘Obtaining a Direct Link to a Logged Message‘). This is how you can query the log entries related to a particular message.

Because I haven’t extensively used this API, I am curious to hear what people can do with this, and if they find it useful!

Tagged: