iguanaServer.lua

Manipulate channels on local or remote Iguana instances:

• addChannel : Adds a new channel to the Iguana server
• cloneChannel : Clones a channel within the same Iguana server or to a remote one
• exportProject : Retrieves a zip file containing the contents of a Translator project
• getChannelConfig : Retrieves the configuration for a channel serialized as XML
• getDefaultConfig : Returns the default configuration for a channel with the specified components
• getServerSalt : Retrieves the salt used by the Iguana server for encryption purposes
• importProject : Sets the contents of a Translator project to the contents of a project zip file
• isLive : Returns true if the connection to the Iguana server is “live”
• listChannels : Returns a XML report with information on the server itself and the channels within it
• pollChannelStatus : Continuously polls the server until the specified channel reaches a particular status, or until the number of retries is exceeded
• removeChannel : Removes a channel from the Iguana server
• saveProjectMilestone : Saves a milestone for the specified Translator project
• startAllChannels : Starts all channels in the Iguana server
• startChannel : Starts a channel in the Iguana server
• stopAllChannels : Stops all channels in the Iguana server
• stopChannel : Stops a channel in the Iguana server
• updateChannel : Updates the configuration of an existing channel
• updateProject : Copies a source Translator project to a destination Translator project
• versionInfo : Returns a table containing version information for the Iguana server

---

The iguanaServer.lua module contains functions used to manipulate channels on local or remote Iguana instances. This module is a Lua wrapper for our HTTP Channel API.

The code for this module can be downloaded from our code repository.

iguanaServer.addChannel{} [top]

Usage: Server:addChannel{config=<xml node tree>[, source_password=<string>][, destination_password=<string>][, salt=<string>][, live=<boolean>]}orServer:addChannel(<xml node tree>)

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.

Returns:

• The configuration of the newly added channel. xml node tree.

Accepts a table with the following required entries:

• config : The configuration for the new channel. xml node tree.

The following optional parameters can be added to the table:

• 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.
• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

-- Add a new LLP Listener -> To Translator channel with
-- the default configuration.
local Config = Server:getDefaultConfig{
   source=iguanaServer.LLP_LISTENER,
   destination=iguanaServer.TO_TRANSLATOR
}
Config.channel.name = "My Channel"
Server:addChannel(Config)

-- Clone a channel within the same server and give it a unique name.
local Config = Server:getChannelConfig{name="My Channel"}.channel
Config.name = Config.name .. " (Clone)"
Server:addChannel(Config)

 

iguanaServer.cloneChannel{} [top]

Usage: Server:cloneChannel{name=<string> OR guid=<string> [, other=<Iguana server object>] [, new_name=<string>] [, configurator=<function>] [, live=<boolean>]}

Clones a channel within the same Iguana server or to a remote one. The “configurator” parameter can be used to make modifications to the configuration of the new channel before it gets added.

Returns:

• The configuration of the newly added channel. xml node tree.

Accepts a table with the following required entries:

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

The following optional parameters can be added to the table:

• other: The Iguana server to clone the channel to. If this is left unspecified then the clone will be made locally. Iguana server object.
• new_name: The new name to use for the channel. If the clone is being made locally then this parameter is required, since the channel would be invalid otherwise. string.
• configurator: A function that accepts the XML configuration for the channel being cloned as an argument. function.
• sample_data: Specifies how sample data will be cloned from the channel’s Translator project(s). Should be “append”, “replace”, or unspecified (meaning sample data will not be cloned). string.
• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

-- Simple example whereby a channel is cloned locally and no changes are made
-- to the configuration for the new channel (except for the name).
Server:cloneChannel{name="My Channel", new_name="My Other Channel"}

-- A more advanced example where the channel is cloned to a remote server and changes
-- are made to the new channel's configuration using the "configurator" function.
-- Assume that the variable Remote is an Iguana server object returned by
-- iguanaServer.connect{} and that "My Channel" has a LLP Listener source component.
-- Notice how the anonymous "configurator" function is able to access variables
-- within its closure (e.g. the PortNum variable).
local PortNum = 5350
Server:cloneChannel{name="My Channel", other=Remote, sample_data="replace", configurator=function(Config)
      Config.channel.from_llp_listener.port = PortNum
   end}

iguanaServer.exportProject{} [top]

Usage: Server:exportProject{guid=<string> [, milestone_name=<string>] [, sample_data=<boolean>] [, destination_file=<string>] [, live=<boolean>]} or Server:exportProject(<string>)

Retrieves a zip file containing the contents of a Translator project. The function can return the base64-encoded contents of the zip file, or write the file out to disk.

Returns:

• The base64-encoded contents of the project zip file, or the path to which the zip file was written if destination_file was provided. string.

Accepts a table with the following required entries:

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

The following optional parameters can be added to the table:

• 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. Default is true. boolean.
• destination_file: If present, project zip will be written out to this specified location. string.
• live: If true, the function will be executed in the editor. Default is true. boolean.

Sample Code

-- Download the project to <Guid>.zip.
-- Alternatively omit the destination_file parameter to simply get the
-- base64-encoded contents of the zip file.
Server:exportProject{guid=Guid, sample_data=true, destination_file=Guid..'.zip'}

iguanaServer.getChannelConfig{} [top]

Usage: Server:getChannelConfig{name=<string> OR guid=<string> [, live=<boolean>]}

Retrieves the configuration for a channel serialized as XML. This operation requires the user to have view permission for the channel.

Returns:

• The configuration of the specified channel. xml node tree.

Accepts a table with the following required entries:

• 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.

The following optional parameters can be added to the table:

• live: If true, the function will be executed in the editor. Default is true. boolean.

Sample Code

-- Get the configuration of the channel named "My Channel".
Server:getChannelConfig{name="My Channel"}

 

iguanaServer.getDefaultConfig{} [top]

Usage: Server:getDefaultConfig{source=<string>, destination=<string> [, live=<boolean>]}

Returns the default configuration for a channel with the specified components. You can use the constants provided by the iguanaServer module to specify the component types.

This function can be used in conjunction with addChannel{} to add new channels to an Iguana server.

Returns:

• The default configuration for a channel with the specified components. xml node tree.

Accepts a table with the following required entries:

• source: The source component type for the channel. string.
• destination: The destination component type for the channel. string.

The following optional parameters can be added to the table:

• live: If true, the function will be executed in the editor. Default is true. boolean.

Sample Code

-- Retrieve the default configuration for a LLP Listener -> To Translator
-- channel and increment the port number in the source component by one.
local Config = Server:getDefaultConfig{
   source=iguanaServer.LLP_LISTENER,
   destination=iguanaServer.TO_TRANSLATOR
}
local Port = Config.channel.from_llp_listener.port
Port:setInner(Port:nodeValue() + 1)

 

iguanaServer.getServerSalt{} [top]

Usage: Server:getServerSalt{[live=<boolean>]} or Server:getServerSalt([<boolean>])

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. string.

Accepts a table with the following optional entry:

• live: If true, the function will be executed in the editor. Default is true. boolean.

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 = Server:getChannelConfig{name="My Channel"}
local Salt = Server:getServerSalt()
Remote:addChannel{config=Config, salt=Salt}

 

iguanaServer.importProject{} [top]

Usage: Server:importProject{guid=<string> [, source_file=<string>] [, project=<string>] [, sample_data=<string>] [, live=<boolean>]}

Sets the contents of a Translator project to the contents of a project zip file. The function can accept the base64-encoded contents of the zip file, or read the file from disk.

Returns:

• The GUID of the Translator project into which the zip file was imported. string.

Accepts a table with the following required entries:

• guid:The GUID of the target Translator project to import into. string.

The following optional parameters can be added to the table:

• project: Base64-encoded project zip file contents. string.
• source_file: Location of the project zip file on disk. string.
• sample_data: Should be “append”, “replace”, or unspecified (meaning sample data will not be included). string.
• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

-- Import a base64-encoded zip file (as received from exportProject()).
Server:importProject{guid=DestGuid, project=B64Proj, sample_data='replace', live=true}
-- or, import from a zip file on disk.
Server:importProject(guid=DestGuid, source_file='my_template.zip', sample_data='replace', live=true}

iguanaServer.isLive{} [top]

Usage: Server:isLive()

Returns true if the connection to the Iguana server is “live”. This is set in iguanaServer.connect().

Returns:

• true if the connection is live, false otherwise. boolean.

Sample Code

Server:cloneChannel{name="My Channel", new_name="My Other Channel"}
if Server:isLive() then
   print(""My Other Channel" successfully created.")
end

 

iguanaServer.listChannels{} [top]

Usage: Server:listChannels{[live=<boolean>]} or Server:listChannels([<boolean>])

Returns an XML report with information on the server itself and the channels within it.

Returns:

• The status of the server and the channels within it. xml node tree.

Accepts a table with the following optional entry:

• live: If true, the function will be executed in the editor. Default is true. boolean.

Sample Code

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

 

iguanaServer.pollChannelStatus{} [top]

Usage: Server:pollChannelStatus{name=<string> OR guid=<string>, channel_status=<string> [, num_retries=<number>] [, interval=<number>] [, status=<xml node tree>] [, live=<boolean>]}

Continuously polls the server until the specified channel reaches a particular status, or until the number of retries is exceeded. This is useful when starting or stopping channels since these are asynchronous operations and may not take effect right away.

There are constants defined in the iguanaServer module that can be used for the “channel_status” parameter.

Returns:

• true if the specified channel reached the desired status within the alloted number of retry attempts, false otherwise. This function always returns true when “live” has been set to false. boolean.
• The last viewed status of the channel, if the first return value is false. string.

Accepts a table with the following required entries:

• name OR guid must be used to identify the channel to poll for a status change.
  • name: The name of the channel to poll. string.
  • guid: The GUID of the channel to poll. string.
• channel_status: The status of the channel to poll until. Can be either “on” or “off”. string.

The following optional parameters can be added to the table:

• num_retries: The number of times to poll the server before returning. Default is 10. number.
• interval: The length of time to sleep between poll attempts. Default is 100 milliseconds. number.
• status: The status of the Iguana server returned from a previous function call, such as listChannels(), startChannel{}, etc. If this argument is given then it will be checked first for the desired status before sending any additional network requests. xml node tree.
• live: If true, the function will be executed in the editor. Default is true. boolean.

Sample Code

-- Wait for the channel to reach the "on" status after issuing a start request.
-- Notice how the return value of startChannel{} is passed in as an argument
-- to pollChannelStatus{}. Some types of channels start immediately, which will
-- alleviate the need to send any additional network requests in pollChannelStatus{}.
local Name = "My Channel"
local Status = Server:startChannel{name=Name}
Server:pollChannelStatus{name=Name, channel_status=iguanaServer.CHANNEL_ON,
   status=Status}

 

iguanaServer.removeChannel{} [top]

Usage: Server:removeChannel{name=<string> OR guid=<string> [, live=<boolean>]}

Removes a channel from the Iguana server. This operation requires the user to have administrator privileges.

Returns:

• The configuration of the channel that was removed. xml node tree.

Accepts a table with the following required entries:

• 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.

The following optional parameters can be added to the table:

• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

-- Remove a channel with a specific GUID.
Server:removeChannel{guid="2E89ECEDEBC53A7E6977DA1AB3F4E08C"}

-- An example where pcall() is used while removing the channel to log any errors
-- that occur.
local Success, Result = pcall(Server.removeChannel, Server, {name="My Channel"})
if not Success then
   iguana.logError(Result)
end

 

iguanaServer.saveProjectMilestone{} [top]

Usage: Server:saveProjectMilestone{guid=<string> milestone_name=<string>}

Saves a milestone for the specified Translator project.

Returns:

• The name of the milestone that was saved. string.

Accepts a table with the following required entries:

• guid: The GUID of the Translator project. string.
• milestone_name: The name of the milestone. string.

The following optional parameters can be added to the table:

• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

local Now = tostring(os.time())
Server:saveProjectMilestone{guid=DestGuid, milestone_name=Now..' - imported', live=true}

 

iguanaServer.startAllChannels{} [top]

Usage: Server:startAllChannels{[live=<boolean>]} or Server:startAllChannels([<boolean>])

Starts all channels in the Iguana server.

Returns:

• The status of the server and the channels within it. xml node tree.

Accepts a table with the following optional entry:

• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

Server:startAllChannels()

 

iguanaServer.startChannel{} [top]

Usage: Server:startChannel{name=<string> OR guid=<string> [, live=<boolean>]}

Starts a channel in the Iguana server.

Tip: Starting channels is performed asynchronously, so to determine if the channel has been successfully started you will need to poll the status of the channel using the pollChannelStatus{} function.

Returns:

• The status of the server and the channels within it. xml node tree.

Accepts a table with the following required entries:

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

The following optional parameters can be added to the table:

• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

Server:startChannel{name="My Channel"}

 

iguanaServer.stopAllChannels{} [top]

Usage: Server:stopAllChannels{[live=<boolean>]} or Server:stopAllChannels([<boolean>])

Stops all channels in the Iguana server.

Returns:

• The status of the server and the channels within it. xml node tree.

Accepts a table with the following optional entry:

• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

Server:stopAllChannels()

 

iguanaServer.stopChannel{} [top]

Usage: Server:stopChannel{name=<string> OR guid=<string> [, live=<boolean>]}

Stops a channel in the Iguana server.

Returns:

• The status of the server and the channels within it. xml node tree.

Accepts a table with the following required entries:

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

The following optional parameters can be added to the table:

• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

Server:stopChannel{name="My Channel"}

 

iguanaServer.updateChannel{} [top]

Usage: Server:updateChannel{config=<xml node tree> [, source_password=<string>] [, destination_password=<string>] [, live=<boolean>]} or Server:updateChannel(<xml node tree>)

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. xml node tree.

Accepts a table with the following required entries:

• config: The configuration to update the channel with. xml node tree.

The following optional parameters can be added to the table:

• 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.
• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

-- Enable the usage of the Filter in an existing channel.
local Config = Server:getChannelConfig{name="My Channel"}
Config.channel.use_message_filter = "true"
Server:updateChannel(Config)

iguanaServer.updateProject{} [top]

Usage: Server:updateProject{source_guid=<string>, destination_guid=<string>, new_milestone_name=<string> [, source_milestone_name=<string>] [, sample_data=<string>], [, live=<boolean>]}

Copies a source Translator project to a destination Translator project. The function will read a specific milestone from the source project, and save a new milestone for the destination project. The destination project can be local or remote (specified through the “other” parameter).

Returns:

• The name of the milestone that was saved.

Accepts a table with the following required entries:

• source_guid: The GUID of the source Translator project. string.
• destination_guid: The GUID of the destination Translator project. string.
• new_milestone_name: The name of the new milestone for the destination Transaltor project. string.

The following optional parameters can be added to the table:

• other: The Iguana server to on which the destination Translator project is found. If this is left unspecified then the update will be performed locally. Iguana server object.
• source_milestone_name: The name of the milestone to export from the source Translator project. string.
• sample_data: Should be “append”, “replace”, or unspecified (meaning sample data will not be included). string.
• live: If true, the function will be executed in the editor. Default is false. boolean.

Sample Code

local Now = tostring(os.time())
Server:updateProject{
   source_guid=SourceGuid,
   destination_guid=DestGuid,
   new_milestone_name=Now..' - imported',
   sample_data='replace'
}

iguanaServer.versionInfo{} [top]

Usage: Server:versionInfo()

Returns a table containing version information for the Iguana server. If the connection isn’t live then the table will be empty.

Returns:

• Version information for the Iguana server. table.

Sample Code

local Version = Server:versionInfo()
if Version.Major == 5 and Version.Minor == 6 then
   -- perform an operation on the server specific to this Iguana version
end

 

For More Information

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