This gem provides server-side functionality for the Netfira WebConnect protocol.


gem install web-connect


If you're using Rails, use the web-connect-rails gem.

To take your WebConnect-enabled app online, use the bundled Rack app and request filter middleware.

require 'web-connect'
require 'my-app'

use Netfira::WebConnect::RequestFilter
run Netfira::WebConnect::RackApp

The RequestFilter middleware is not essential, but can provide speed and compatibility advantages for older clients.


This is a typical WebConnect configuration.

Netfira::WebConnect.configure do |c|
  # This database configuration will be used by ActiveRecord
  c.db = {
      adapter: 'sqlite3',
      database: 'test.sqlite3'

  # This string will be prefixed to names of tables created by
  # WebConnect
  c.db_table_prefix = 'nf_'

  # Enabled or disable storage of fields not included in WebConnect's
  # default schema
  c.custom_fields = false

  # Default time zone
  c.time_zone = 'Australia/Sydney'

  # WebConnect activity will be logged here
  c.logger =

  # Use any Paperclip storage configuration you like here. WebConnect
  # provides the :shop_id and :model_type interpolations.
  c.file_store = {
      path: File.dirname(__FILE__) + '/uploads/shop_:shop_id/:model_type/:filename'

  # This block will be passed a shop name and password whenever a client
  # needs to authenticate
  c.on_authenticate do |shop_name, password|
    shop = Shop.find_by(name: shop_name)
    shop && shop.password == password

  # Session lifetime (omit to disable sessions)
  c.session_lifetime = 5.days

  # Send new-data notifications via HTTP. Options are :none, :sync, and :async.
  c.http_notifications = :async

  # AMQP server to use for downstream communications.
  c.amqp = 'amqps://admin:[email protected]:5672'


WebConnect uses ActiveRecord migrations to manage its database. It comes with two rake tasks.

rake wc:migrate   # Migrate the database
rake wc:rollback  # Roll back a single migration

If your application uses ActiveRecord, these migrations will be managed independently of your application's migrations.

Run these migrations when you first install WebConnect, and whenever you update the WebConnect gem.


You can access WebConnect data through the Netfira::WebConnect::Models namespace.

product = Netfira::WebConnect::Models::Product.first

product.unit_price   # BigDecimal         # Netfira::WebConnect::Model::Record::TranslatedString[:en_AU] # String

You can lookup records using their original client-side identifiers using find_by_origin_id.

shop = Netfira::WebConnect::Models::Shop.first

product = Netfira::WebConnect::Models::Product.find_by_origin_id(shop, 'product123')
# Or
product = shop.products.find_by(product_id: 'product123')


Events in WebConnect are handled by delegates. Define your delegates like so:

class MyDelegate
  def on_create_product(product)
    # ...

Then add delegates to WebConnect:

Netfira::WebConnect.event_delegates <<

The event_delegates collection is an array. You can push, merge, delete etc as you would a normal array.

Any object can be an event delegate, and you can add as many as you like. They only need to respond any of the method signatures below.

Delegate Method Signatures

For Example Arguments Remarks
New Records on_create_buyer buyer Dispatched after record is created
Record Updates on_update_image image, previous_values Second argument is a hash of changed columns as they were before they were changed
Deleted Records on_delete_category category Dispatched before records are deleted
New Relations on_add_image_to_product image, product on_add_product_to_image also works, causing the arguments to also be swapped
Deleted Relations on_remove_product_from_category product, category Same as above
Change Setting on_change_setting setting, old setting will have shop, key, and value methods. old is the previous value.

Except for previous_values, all arguments above are instances of Netfira::WebConnect::Model::Record.

Events are dispatched to delegates synchronously, on request threads. Create new threads if you want to prevent your handlers from blocking HTTP responses to WebConnect clients.