📚 InfoWorks ICM Ruby API Documentation

Introduction to Ruby Scripting in InfoWorks

InfoWorks ICM provides a powerful Ruby scripting interface for automating tasks, manipulating network data, and performing batch operations. This documentation covers the complete API reference.

Getting Started

Introduction to Scripts

Ruby scripts in InfoWorks ICM allow you to:

• Automate repetitive tasks
• Process large amounts of network data
• Import and export data in various formats
• Perform custom calculations and analysis
• Integrate with external tools and databases

Running Scripts

From the User Interface

To run a script from the InfoWorks ICM interface:

1. Open a network in InfoWorks ICM
2. Go to Network → Run Ruby Script
3. Select your .rb script file
4. View output in the Script Output window

From Exchange (Command Line)

IExchange.exe --net="NetworkName" --script="path/to/script.rb"

Command line options allow for automation and batch processing.

Working with the Database

Access and manipulate the InfoWorks database using Ruby scripts:

# Open database
db = WSApplication.open('C:/path/to/database.icmm')

# List model objects
objects = db.list_model_objects

# Get specific object
network = db.model_object_from_type_and_id('Model Network', 'MyNetwork')

Working with Networks

Network manipulation is the core of ICM Ruby scripting:

# Get current network
net = WSApplication.current_network

# Access nodes
nodes = net.row_objects('_nodes')
nodes.each do |node|
  puts "Node: #{node.id} at (#{node.x}, #{node.y})"
end

# Access links
links = net.row_objects('_links')
links.each do |link|
  puts "Link: #{link.id}, Diameter: #{link['diameter']}"
end

# Commit changes
net.commit('Updated network data')

Dates and Times

Handle temporal data in ICM scripts:

# Ruby Time objects
start_time = Time.new(2024, 1, 1, 0, 0, 0)
end_time = Time.new(2024, 12, 31, 23, 59, 59)

# Format for ICM
formatted = start_time.strftime('%Y-%m-%d %H:%M:%S')

WSApplication

The top-level class providing access to the InfoWorks application.

Key Methods

WSOpenNetwork

Represents an open network and provides access to network objects.

Key Methods

Common Table Names

• _nodes - All nodes in network
• _links - All links in network
• _subcatchments - All subcatchments
• hw_node - Hydraulic nodes
• hw_conduit - Conduits/pipes
• cams_manhole - Manholes (collection networks)
• hw_pump - Pumps
• hw_orifice - Orifices
• hw_weir - Weirs

WSRowObject

Represents a single network object (node, link, subcatchment, etc.).

Field Access

# Get field value
elevation = node['ground_level']
diameter = link['diameter']

# Set field value
node['ground_level'] = 100.0
link['diameter'] = 300

# Write changes
node.write

# Alternative syntax (if no name conflicts)
x_coord = node.x
y_coord = node.y

Key Properties

WSNode

Specialized class for node objects with navigation capabilities.

Navigation Methods

# Get upstream links
upstream = node.us_links
upstream.each { |link| puts link.id }

# Get downstream links
downstream = node.ds_links
downstream.each { |link| puts link.id }

WSLink

Specialized class for link objects with navigation capabilities.

Navigation Methods

# Get upstream node
us_node = link.us_node
puts "Upstream: #{us_node.id}"

# Get downstream node
ds_node = link.ds_node
puts "Downstream: #{ds_node.id}"

WSDatabase

Provides access to the InfoWorks database and model objects.

Key Methods

# Open database
db = WSApplication.open('database.icmm')

# List all model objects
objects = db.list_model_objects

# Get specific object by type and ID
network = db.model_object_from_type_and_id('Model Network', 'NetworkID')

# Create new object
new_net = db.new_model_object('Model Network', 'NewNetwork')

WSModelObject

Represents database objects like networks, simulations, and stored queries.

Properties

• id - Object identifier
• type - Object type (Network, Simulation, etc.)
• path - Database path

WSNumbatNetworkObject

Extended network object with import/export capabilities.

ODIC/ODEC Methods

# Import data
net.odic_import_ex(
  'CSV',                    # File type
  'config.cfg',             # Config file
  {'Error File' => 'err.txt'},  # Options
  'hw_node',                # Table
  'nodes.csv'               # Source file
)

# Export data
net.odec_export_ex(
  'CSV',
  'export_config.cfg',
  {'Use Display Names' => true},
  'hw_node', 'exported_nodes.csv',
  'hw_conduit', 'exported_conduits.csv'
)

WSSimObject

Represents simulation objects and run configurations.

Running Simulations

# Get simulation object
sim = db.model_object_from_type_and_id('Sim', 'MySimulation')

# Run simulation
sim.run

WSValidation

Validation object for checking network integrity.

# Run validation
validation = net.validate

# Check results
validation.validations.each do |v|
  puts "#{v.level}: #{v.message}"
end

WSTableInfo

Provides metadata about network tables.

Properties

table_info = net.table_info('hw_node')

puts table_info.name          # Table name
puts table_info.description   # Description
table_info.fields.each do |field|
  puts field.name             # Field name
end

WSFieldInfo

Metadata about individual table fields.

Properties

• name - Field name
• description - Field description
• data_type - Data type (String, Double, Integer, etc.)
• read_only - Whether field is read-only

Add-ons

Ruby scripts can be added to the InfoWorks interface as custom menu items.

Creating Add-ons

1. Place .rb files in the Add-ons directory
2. Scripts appear in Tools → Ruby Addons menu
3. Limited to 10 addon scripts

Character Encoding

InfoWorks ICM supports UTF-8 character encoding for international characters.

# Set UTF-8 encoding at start of script
# encoding: utf-8

# Handle special characters
node_name = "Nœud Spécial"

Network Tables Reference

Hydraulic Tables

• hw_node - Nodes
• hw_conduit - Conduits
• hw_pump - Pumps
• hw_orifice - Orifices
• hw_weir - Weirs
• hw_subcatchment - Subcatchments
• hw_land_use - Land use

Collection Network Tables

• cams_manhole - Manholes
• cams_pipe - Pipes
• cams_cso - CSO structures
• cams_pump - Pump stations

Import/Export (ODIC/ODEC) Scripts

Open Data Import Centre (ODIC) and Export Centre (ODEC) allow custom Ruby scripts for data transformation.

ODIC Import Script Structure

class Importer
  def self.OnBeginNode(importer)
    # Initialize before import
  end
  
  def self.OnBeginRecordNode(importer)
    # Before each record
  end
  
  def self.OnEndRecordNode(importer)
    # Modify imported data
    # Access: importer['field_name']
    importer['custom_field'] = calculated_value
  end
  
  def self.OnEndNode(importer)
    # Cleanup after import
  end
end

ODEC Export Script Structure

class Exporter
  def self.OnBeginNode(exporter)
    # Initialize before export
  end
  
  def self.OnRecordNode(exporter)
    # Custom export logic per record
    # Access: exporter['field_name']
  end
  
  def self.OnEndNode(exporter)
    # Cleanup after export
  end
end

Supported File Types

• CSV - Comma-separated values
• SHP - ESRI Shapefile
• MIF - MapInfo Interchange Format
• TAB - MapInfo TAB format
• GDB - ESRI Geodatabase