• Introduction
• Channel API functions
• Monitor API functions
• Log API functions

Introduction

The following HTTP APIs can be called from any language by using HTTP POST or GET commands (including the net.http.post/get functions included in the Translator). Each of these APIs contains one or more functions that perform useful Iguana management tasks.

For details on how to use modules in your scripts, see Working With Modules. Understanding Iguana node trees and their node types is very helpful for writing mapping code.

Also see the trick about using _G to discover the entire API using auto-completion.

Channel API functions [top]

The HTTP Channel API allows you to use an HTTP connection to manipulate the channels on local or remote Iguana instances.

The functions for this module are:

• add_channel : Adds a new channel to the Iguana server
• current_version : Returns a table containing version information for the Iguana server
• export_project : Retrieves a zip file containing the contents of a Translator project
• get_channel_config : Retrieves the configuration for a channel serialized as XML
• get_default_config : Returns the default configuration for a channel with the specified components
• get_server_salt : Retrieves the salt used by the Iguana server for encryption purposes
• import_project : Sets the contents of a Translator project to the contents of a project zip file
• remove_channel : Removes a channel from the Iguana server
• sc/commit : Commits files from the specified Translator project to source control
• sc/bump: Updates one or more translators to run from a specific commit
• status : Returns a XML report with information on the server itself and the channels within it
• update_channel : Updates the configuration of an existing channel

---

add_channel [top]

Usage:

net.http.post{url='<value>/add_channel‘,

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

parameters={config=<value> [, compact=<value>] },

live=<true/false>

}

Adds a new channel to the Iguana server. The channel added must have a unique name. This operation requires the user to have administrator privileges.

Can be used in conjunction with the get_default_config handler to create new channels from scratch, or with get_channel_config to clone existing channels.

Returns:

• The configuration of the newly added channel. MIME type: application/xml.

Required parameters:

• config : The configuration for the new channel. XML string.

Optional parameters:

• source_password: The password for the source component. Only applicable to channels with a From File or From Database component. string.
• destination_password: The password for the destination component. Only applicable to channels with a To File or To Database component. string.
• salt: A value used to re-encrypt the passwords in certain component types. Useful when cloning channels between servers to prevent passwords from becoming invalid. string.
• compact: If true return XML in compact format, value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- Add a new LLP Listener -> To Translator channel with
-- the default configuration.
local Config = net.http.post{url='localhost:6543/get_default_config',
   auth={password='password', username='admin'},
   parameters={compact='true', source='LLP Listener', destination = 'To Translator'},
   live=true
}
-- Set the channel name in Config XML
XmlTreeCfg = xml.parse(Config)
XmlTreeCfg.channel.name = 'My Channel'
Config = tostring(XmlTreeCfg)
-- Create the new channel
local MyChannelCfg = net.http.post{url='localhost:6543/add_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', config=Config},
   live=true
}

-- Clone a channel within the same server and give it a unique name.
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name= 'My Channel'},
   live=true
}
-- Append " - clone to the channel name
XmlTreeCfg = xml.parse(Config)
XmlTreeCfg.channel.name = XmlTreeCfg.channel.name..' - clone'
Config = tostring(XmlTreeCfg)
-- Create the new channel
local MyChannelCfg = net.http.post{url='localhost:6543/add_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', config=Config},
   live=true
}

For More Information

• Configuring a From Channel component using the HTTP Channel API

current_version [top]

Usage:

net.http.post{url='<value>/current_version’,

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

live=<true/false>

}

Returns a table containing version information for the Iguana server, fomatted as JSON. The JSON table has the following fields: Major, Minor, Build, and BuildExt, if the connection isn’t live then the table will be empty.

This can be used to determine if a given Iguana server has the channel API available, and to perform conditional operations with the API as it evolves over time.

Returns:

• Version information for the Iguana server. MIME type: application/json.

Required parameters: None

Optional parameters: None

Sample Code

-- get the version information for the Iguana Server
local Version = net.http.post{url='localhost:6543/current_version',
   auth={password='password', username='admin'},
   live=true
}

if Version.Major == 5 and Version.Minor == 6 then
   -- perform an operation on the server specific to this Iguana version
end

export_project [top]

Usage:

net.http.post{url='<value>/export_project‘,

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

parameters={guid=<value>, [, milestone_name=<value>] [, sample_data=<value>]},

live=<true/false>

}

Retrieves a zip file containing the contents of a Translator project.

Returns:

• The project data as a base64-encoded zip. MIME type: application/zip.

Required parameters:

• guid: The GUID of the Translator project to export. string.

Optional parameters:

• milestone_name: The name of the milestone to export. Default is the project’s most recent milestone. string.
• sample_data: If false, sample data will be excluded from the project zip, value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- return the project data in a base64 encoded zip format 
-- and write the base64 contents as a zip file
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
-- NOTE: you must use the component guid not the channel guid
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)

-- get the base64 project data
local Base64ZipContents = net.http.post{url='localhost:6543/export_project',
   auth={password='password', username='admin'},
   parameters={guid=GUID, sample_data=true},
   live=true
}
-- write to file (in the Iguana install directory)
local ZipFile = io.open('My Channel.zip', 'w+b')
local ZipContents = filter.base64.dec(Base64ZipContents)
ZipFile:write(ZipContents)
ZipFile:close()

get_channel_config [top]

Usage:

net.http.post{url='<value>/get_channel_config’,

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

parameters={name=<value> OR guid=<value> [,compact=<true/false>]},

live=<true/false>

}

Retrieves the configuration for a channel serialized as XML. This can be used with other request handlers in the API to clone channels or update existing ones. This operation requires the user to have view permission for the channel.

Returns:

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

Required parameters:

• name OR guid must be used to identify the channel to view.
  • name: The name of the channel to view. string.
  • guid: The GUID of the channel to view. string.

Optional parameters:

• compact: If true return XML in compact format, value = “true”|”false” (default = “true”). boolean string.

Sample Code

-- Get the configuration of the channel named "My Channel".
local Result = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}

For More Information

• Configuring a From Channel component using the HTTP Channel API

get_default_config [top]

Usage:

local Config = net.http.post{url='<value>/get_default_config’,

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

parameters={source=<value>, destination=<value> [,compact=<true/false>]},

live=<true/false>

}

Returns the default configuration for a channel with the specified components, serialized as XML. This can be used in conjunction with the add_channel handler to add new channels to the server with customized configurations.

Returns:

• The default configuration for a channel with the specified components. MIME type: application/xml.

Required parameters:

• source: The source component type for the channel. string.
  • One of:
    • LLP Listener
    • From Database
    • From File
    • From Plugin
    • From HTTPS
    • From Channel
    • From Translator
• destination: The destination component type for the channel. string.
  • One of:
    • LLP Client
    • To Database
    • To File
    • To Plugin
    • To HTTPS
    • To Channel
    • To Translator
• compact: If true return XML in compact format, value = “true”|”false” (default = “true”) boolean string.

Optional parameters: None

Sample Code

-- Retrieve the default configuration for a LLP Listener -> To Translator
local Config = net.http.post{url='localhost:6543/get_default_config',
   auth={password='password', username='admin'},
   parameters={compact='true', source='LLP Listener', destination = 'To Translator'},
   live=true
}

For More Information

• Configuring a From Channel component using the HTTP Channel API

get_server_salt [top]

Usage:

net.http.post{url='<value>/get_server_salt‘,

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

live=<true/false>

}

Retrieves the salt used by the Iguana server for encryption purposes. The main use for this function is to preserve password settings when cloning channels between different servers with certain component types. The component types concerned are From/To Database and From/To File.

Returns:

• The salt used by the server for encryption. MIME type: application/plain.

Required parameters: None

Optional parameters: None

Sample Code

-- Showing how the salt can be used when cloning a channel to different server.
-- Assume that "My Channel" has at least one component with the relevant
-- password settings.

local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password',username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local Salt = net.http.post{url='localhost:6543/get_server_salt',
   auth={password='password',username='admin'},
   live=true
}
net.http.post{url='http://remote_iguana.com:6543/add_channel',
   auth={password='password',username='admin'},
   parameters={config=Config, salt=Salt},
   live=true
}

import_project [top]

Usage:

net.http.post{url='<value>/import_project‘,

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

parameters={project=<value>, guid=<value>, sample_data=<value>},

live=<true/false>

}

Sets the contents of a Translator project to the contents of a project zip file.

Returns:

• The GUID of the Translator project into which the zip file was imported. MIME type: application/plain.

Required parameters:

• guid:The GUID of the Translator project to import to. string.
• project: Base64-encoded project zip file contents (matching the structure provided by export_project). MIME type: application/zip.

Optional parameters:

• sample_data: Should be “append”, “replace”. If omitted then sample data will not be included. string.

Sample Code

-- Import a zip project file from disk into a channel component
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
-- get the guid for the "To Translator" in "My Channel"
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)   
-- read the project zip file, and encode the contents as base64
local ZipFile = io.open('My_Channel.zip', 'rb')
local Base64ZipContents = filter.base64.enc(ZipFile:read("*a"))
ZipFile:close()
-- import the project using the guid and base64 encoded zip contents
Base64ZipReturn = net.http.post{url='localhost:6543/import_project',
   auth={password='password', username='admin'},
   parameters={project=Base64ZipContents, guid=GUID, sample_data='replace'},
   live=true
}

-- copy a channel component using "export_project"
-- Note: This provides a convenient way to "clone" a channel
-- get the SOURCE guid for the "To Translator" in "My Other Channel"
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='adsfadsf'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)   
-- export the project as a base64 encoded zip
Base64ZipContents = net.http.post{url='localhost:6543/export_project',
   auth={password='password', username='admin'},
   parameters={guid=GUID, sample_data=true},
   live=true
}
-- get the TARGET guid for the "To Translator" in "My Channel"
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
GUID = tostring(xml.parse(Config).channel.to_mapper.guid)   
-- import the project using the guid and base64 encoded zip contents
Base64ZipReturn = net.http.post{url='localhost:6543/import_project',
   auth={password='password', username='admin'},
   parameters={project=Base64ZipContents, guid=GUID, sample_data='replace'},
   live=true
}

remove_channel [top]

Usage:

net.http.post{url='<value>/remove_channel’,

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

parameters={name=<value> OR guid=<value> [,compact=<true/false>]},

live=<true/false>

}

Removes a channel from the Iguana server; the channel must be stopped before it can be removed. This operation requires the user to have administrator privileges.

Returns:

• The configuration of the channel that was removed. MIME type: application/xml.

Required parameters:

• name OR guid must be used to identify the channel to remove.
  • name: The name of the channel to remove. string.
  • guid: The GUID of the channel to remove. string.

Optional parameters:

• compact: If true return XML in compact format , value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- Remove "My Channel"
local Config = net.http.post{url='localhost:6543/remove_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=false
}
-- Remove "My Channel" using a GUID
 local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.guid)
local Config = net.http.post{url='localhost:6543/remove_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', guid=GUID},
   live=true
}

-- An example where pcall() is used while removing the channel to log any errors
-- that occur.
local Success, Result, Status = pcall(net.http.post, 
   {url='localhost:6543/remove_channel',
      auth={password='password', username='admin'},
      parameters={compact='true', name='My Channel'},
      live=true
   }
)
if not Success or Status >= 400 then
   iguana.logError(Result)
end

sc/commit [top]

Usage:

net.http.post{url='<value>/sc/commit‘,

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

parameters={translator_guid=<value>, comment=<value>[, file_paths=<value>]},

live=<true/false>

}

Saves a commit for the specified Translator project.

Returns:

{
"affected_channels":{
   "CHANNEL NAME":{
      "channel_guid":"CHANNEL_GUID",
      "projects":{
         "TRANSLATOR_GUID":{
            "type":"TRANSLATOR_TYPE"
         },
         "TRANSLATOR_GUID":{
            "type":"TRANSLATOR_TYPE"
         }
      },
   "CHANNEL NAME":{
      "channel_guid":"CHANNEL_GUID",
      "projects":{
         "TRANSLATOR_GUID":{
            "type":"TRANSLATOR_TYPE"
         },
         "TRANSLATOR_GUID":{
            "type":"TRANSLATOR_TYPE"
         }
      }
   },
},
"affected_files_map":{},
"current_channel":{
   "channel_guid":"CHANNEL_GUID",
   "channel_name":"CHANNEL NAME",
   "current_project":{
      "translator_guid":"TRANSLATOR_GUID145539D867C4E69553AEF9771E98111",
      "type":"TRANSLATOR_TYPE"}
   },
   "file_paths": [
      "shared/FILENAME",
      "AFFECTED_TRANSLATOR_GUID/project.prj",
      "AFFECTED_TRANSLATOR_GUID/project.prj",
      "AFFECTED_TRANSLATOR_GUID/project.prj"
   ],
},
"new_commit":{
   "commit_comment":"COMMIT_COMMENT",
   "commit_email":"EMAIL_ADDRESS",
   "commit_id":"COMMIT_ID",
   "commit_time":"2016-02-03 23:11:15 UTC",
   "commit_timestamp":1454541075,
   "commit_user":"admin"
}}

MIME type: text/json.

Required parameters:

• translator_guid: The GUID of the Translator project. string. For backward compatibility, this parameter can also be sent as guid
• comment: The comment to attach to the commit. string. For backward compatibility, this parameter can also be sent as milestone_name

Optional parameters:

• file_paths: A list of files to commit, serialized as a JSON array. string. If this parameter is omitted, all the files in the current project, plus all the project files of all affected projects, will be included in the commit.

Sample Code

-- create a commit for a translator
-- first get the guid for the channel
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)
-- then create the commit
local CommitResult = net.http.post{url='localhost:6543/sc/commit',
   auth={password='password', username='admin'},
   parameters={translator_guid=GUID, comment='My Milestone', file_paths='["GUID/project.prj", "GUID/main.lua", "shared/resource.lua"]'},
   live=true
}
local CommitTable = json.parse(CommitResult);

sc/bump [top]

Usage:

net.http.post{url='<value>/sc/bump‘,

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

parameters={translator_guid=<value>, commit_id=<value>, translators_to_bump=<value>},

live=<true/false>

}

Updates the selected translators to run from the selected commit.

Returns:

• {“commit_result”: {“success”: <true/false>}}. MIME type: text/json.

Required parameters:

• guid: The GUID of the Translator project. string.
• commit_id: The ID of the commit the translators should run from. string.
• translators_to_bump: A list of translator GUIDs to be bumped, serialized as a JSON array. string.

Optional parameters: None

Sample Code

-- Save a commit and extract its ID
local CommitResult = net.http.post{url='localhost:6543/sc/commit',
   auth={password='password', username='admin'},
   parameters={translator_guid=GUID, comment='My Milestone', file_paths='["GUID/project.prj", "GUID/main.lua", "shared/resource.lua"]'},
   live=true
}
local CommitTable = json.parse(CommitResult);
local CommitId = CommitResult.new_commit.commit_id
local Success = net.http.post{url='localhost:6543/sc/bump', auth={password='password', username='admin'}, parameters={translator_guid=GUID, commit_id=CommitId, translators_to_bump='["' .. GUID .. '"]'}, live=true }

status [top]

Usage:

net.http.post{url='<value>/status‘,

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

parameters={[action=<value>, name=<value> OR guid=<value>]},

live=<true/false>

}

Returns an XML report with information on the server itself and all the channels within it . It can also be used to start/stop channels by using the action parameter.

Note: It is not possible to retrieve information for a single channel. Information for all channels is always returned (even when the name or guid parameter is specified).

Returns:

• The status of the server and the channels within it. MIME type: application/xml.

Required parameters: None

Optional parameters:

• name OR guid must be used to identify the channel to apply a start/stop action to.
  • name: The name of the channel to view. string.
  • guid: The GUID of the channel to view. string.

• action: The channel action to perform. string.
  • One of:
    • start
    • stop
    • startall (starts all channels)
    • stopall (stops all channels)

Sample Code

-- get the status for the specified server
local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   live=true
}

-- parsing into an XML node tree makes it very easy to 
-- access various status information
XmlTreeStatus = xml.parse(Status)
trace(XmlTreeStatus.IguanaStatus)
local ChannelCount = XmlTreeStatus.IguanaStatus.NumberOfChannels
local Name = XmlTreeStatus.IguanaStatus:child("Channel", 2).Name

-- Construct a list of the channel names in the server.
local IguanaStatus = XmlTreeStatus.IguanaStatus
local ChannelNames = {}
for i=1, IguanaStatus:childCount("Channel") do
   table.insert(ChannelNames, IguanaStatus:child("Channel", i).Name)
end
trace(ChannelNames) -- view the channel names

-- stop and start channels
-- start/stop
local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   parameters={action='start', name='My Channel'},
   -- parameters={action='stop', name='My Channel'}, -- stop: action = 'stop'
   live=true
}
-- start/stop all channels
local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   parameters={action='startall', name='My Channel'},
   -- parameters={action='stopall', name='My Channel'},  -- stop: action = 'stopall'
   live=true
}

-- you can use a channel GUID instead of a channel name
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.guid)

local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   parameters={action='start', guid=GUID},
   live=true
}

update_channel [top]

Usage:

net.http.post{url='<value>/update_channel‘,

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

parameters={config=Config [, source_password=<value>] [, destination_password=<value>] [, compact=<value>]},

live=<true/false>

}

Updates the configuration of an existing channel. This can be used in conjunction with getChannelConfig{}, by first retrieving the configuration for the channel and then modifying it before being passed into this function.

This operation requires the channel to be stopped before being updated. The user must also have edit permission for the channel.

Returns:

• The configuration of the updated channel. MIME type: application/xml.

Required parameters:

• config: The configuration to update the channel with. XML string.

Optional parameters:

• source_password: The password for the source component. Only applicable to channels with a From File or From Database component. string.
• destination_password: The password for the destination component. Only applicable to channels with a To File or To Database component. string.
• compact: If true return XML in compact format, value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- Enable the usage of the Filter in an existing channel ("My Channel")
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password',username='admin'},
   parameters={compact='true', name = 'My Channel'},
   live=true
}
-- Set use_message_filter in Config XML
XmlTreeCfg = xml.parse(Config)
XmlTreeCfg.channel.use_message_filter = 'true'
Config = tostring(XmlTreeCfg)
-- Update the channel
local MyChannelCfg = net.http.post{url='localhost:6543/update_channel',
   auth={password='password', username='admin'},
   parameters={config=Config},
   live=true
} 
trace(MyChannelCfg) -- view config to confirm the change

For More Information

• iguanaServer.lua – Manipulate local or remote Iguana channels from the comfort of the Translator

Monitor API functions [top]

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:

• 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

---

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

Log API functions [top]

There is one function in this module:

• api_query : Returns a table containing Iguana Log Messages

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”. 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/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    = 'messages',   -- of type messages
         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

For More Information

• Programmatically reading Iguana log entries from Lua
• Remove Duplicate Messages in the Tools repository