HTTP API Reference

Server API functions

Contents

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

Note: The “Usage” examples given below use the Translator net.http.post() function. Equivalent HTTP calls can be written in any language.

The HTTP API portion of the command is highlighted in bold, the remainder is simply the the net.http.post() used to deliver the command.

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

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

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

 

Back to: Intro