Server API functions

The HTTP Server API allows you to use an HTTP connection to retrieve information from local or remote Iguana instances.

The functions for this module are:

• api_query : Returns a table containing Iguana Log Messages
• get_server_config : Returns a table containing Iguana Configuration Information
• monitor_query : Returns a table summarizing Iguana Performance Statistics

The Channel API also contains three server-related functions:

• current_version : Returns a table containing version information for the Iguana server
• get_server_salt : Retrieves the salt used by the Iguana server for encryption purposes
• status : Returns a XML report with information on the server itself and the channels within it

---

api_query [top]

Usage:

net.http.post{url=’<value>/api_query‘,

auth={password=<value>, username=<value>},

parameters={ [after=<value>] [, before=<value>] [, …]},

live=<true/false>

}

Queries the specified Iguana Server and accesses to its logs. Returns a table with fields containing the matching log entries (as XML).

Returns:

• Zero or more matching log entries . Table with fields in MIME type: application/xml.

Required parameters: None

Optional parameters:

• after : Select messages after this date (format = yyyy/mm/dd hh:mm:ss). date string.
• before : Select messages before this date (format = yyyy/mm/dd hh:mm:ss). date string.
• debugmode : Include system debug messages, value = “true”|”false” (default = “false”). boolean string.
• deleted : Select only deleted messages, or only messages that have not been deleted. (If this parameter is absent, both will be included.) value = “true”|”false” (default = ‘true’). boolean string.
• filter : Select messages containing the specified value. string.
• includesourcelogs : Include source channel messages, value = “true”|”false” (default = “false”). boolean string.

  Note: Only applies to channels where the source component type is From Channel.

  For example if you have a channel HL7-Process-Clinics (with a From Channel source) that processes HL7 messages from two source channels HL7-Clinic1 and HL7-Clinic2 (i.e., feeds from two different clinics for the same hospital). Then if includesourcelogs = true messages from HL7-Process-Clinics and the two source channels will be included in the query result, includesourcelogs = false then messages from the source channels will not be included.

  -- query parameter that returns messages for 
  -- HL7-Process-Clinics and all its source channels  
  parameter = 
  {
     source = 'HL7-Process-Clinics', 
     type = 'messages', 
     includesourcelogs = true
  }
  
  -- parameter to return only HL7-Process-Clinics messages 
  -- NOTE: includesourcelogs can be omitted as default is false
  parameter = 
  {
     source = 'HL7-Process-Clinics', 
     type = 'messages', 
     includesourcelogs = false -- can be omitted
  }

• refmsgid : The unique message id assigned by the Iguana Logs. string.
• source : Select messages from the specified channel. string.
• type : Select messages of the specified type(s), several types can be included in a comma separated list. string.
  

  type	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

• limit : restrict the number of messages being returned. integer.
• reverse : return log messages in order from newest to oldest (vs the normal behavior of oldest to newest),value = “true”|”false” (default = “false”). boolean string.
• unique : when combined with type=Messages, will return only unique message logs (vs including ignored and resubmitted messages), value = “true”|”false” (default = “false”). boolean string.

Sample Code

Here’s an example that retrieves the last 50 messages from the “Catcher” channel with the newest messages at the top:

function main()

   local messageId = iguana.messageId() -- get log message ID (http://help.interfaceware.com/kb/48#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/kb/1159/3)
         
         -- 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

For More Information

• Programmatically reading Iguana log entries from Lua
• Easy filtering of duplicate messages

get_server_config [top]

Usage:

net.http.post{url=’<value>/get_server_config‘,

auth={password=<value>, username=<value>},

live=<true/false>

}

Queries the specified Iguana Server and returns the configuration information as XML.

Returns:

• The configuration of the specified server. MIME type: application/xml.

Required parameters: None

Optional parameters: None

Sample Code

-- change to the server you wish to query
local SERVER_URL = 'http://localhost:6543/'

function main(Data)
   
   local Config = net.http.get{url=SERVER_URL..'get_server_config',
      parameters={
         username='admin',
         password='password',
      },live=true}  
   Config = xml.parse{data=Config}
   
   -- Networks can fail so if you want to be cautious
   local Success, Config = pcall(net.http.get, {
         url=SERVER_URL..'get_server_config',
         parameters={username='admin', password='password'},
      live = true}
      )
   if Success then
      -- Use the configuration data 
   else
      -- It failed, we might want to raise an error
   end
end

For More Information

• Web access to configuration information for a remote Iguana Server

monitor_query [top]

Usage:

net.http.post{url=’<value>/monitor_query‘,

auth={password=<value>, username=<value>},

live=<true/false>

}

Queries the specified Iguana Server and returns a very detailed XML summary of Iguana Performance Statistics. It includes a variety of useful information like the number of open file handles, memory usage and so on.

Returns:

• A detailed summary of Iguana Performance Statistics. MIME type: application/xml.

Required parameters: None

Optional parameters: None

Sample Code

-- change this to the server you wish to query
local SERVER_URL = 'http://localhost:6543/'

function main(Data)
 
 local Config = net.http.get{url=SERVER_URL..'monitor_query',
 parameters={
 username='admin',
 password='password',
 },live=true} 
 Config = xml.parse{data=Config}
 
 -- Networks can fail so if you want to be cautious
 local Success, Config = pcall(net.http.get, {
 url=SERVER_URL..'monitor_query',
 parameters={username='admin', password='password'},
 live = true}
 )
 if Success then
 -- Use the configuration data 
 else
 -- It failed, we might want to raise an error
 end
end

For More Information

• Monitor – Module to extract runtime information about Iguana from monitor_query data
• Monitor Iguana instances and produce graphed results