Symgate - Ruby client for the Widgit symbolisation service

Build Status Code Climate Dependency Status Gem Version Apache License

This gem provides a wrapper around the Symgate SOAP API, providing a simple Ruby interface that matches the remote API as much as possible.

The API provides a client for each of the sections of API functionality. These are:

  • Symgate::Auth::Client for authentication, user and group management
  • Symgate::Wordlist::Client for per-user/group metadata storage
  • Symgate::Metadata::Client for per-user/group wordlist management

Please note that a symbolisation client is scheduled for a future release.


This gem works with Ruby 2.1 and above


Add this line to your application's Gemfile:

gem 'symgate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install symgate



To call any Symgate methods you must create a client of the relevant type. These can be instantiated in the following ways:


require 'symgate/auth'

auth_client = 'my_account', key: 'secret')


require 'symgate/wordlist'

wordlist_client = 'my_account', 
                                                user: 'group/user',
                                                password: 'secret')


You need to call the authenticate method in order to obtain a token:

require 'symgate/auth'
require 'symgate/metadata'

# obtain a token from the authentication client

auth_client = 'my_account', 
                                        user: 'group/user',
                                        password: 'secret')

  token = auth_client.authenticate
rescue Symgate::Error => e
  puts "Authentication failed with the following error: #{e.message}"

 = 'my_account',
                                                user: 'group/user',
                                                token: token)

Other initialisation options

You can also initialise a client with the following options:

:endpoint Specifies the symbolisation SOAP endpoint to use, if not the public symbolisation server.
:savon_opts Specifies options to pass to the underlying savon engine. e.g. { log_level: :debug }


If any method call fails, it will raise a Symgate::Error exception. Examine the exception for further information on what went wrong.

Further documentation

For more information, see the documentation at:


After checking out the repository, run bundle install to obtain the necessary development gems.

Run rake test to run the tests, which consist of

  • rubocop
  • rspec (with coverage)

Successful PRs require 100% code coverage and all tests and cops passing.

Integration tests

If you want to run the integration tests (test the gem against a running server):

  1. Install Vagrant 1.8 or later, if not already installed
  2. Run rake vagrant:up to set up a local VM running the latest symboliser.
  3. Run rake spec:integration to run the integration tests.

To pause testing until later, run rake vagrant:halt which will suspend your virtual machine. To resume testing run rake vagrant:up again.

To shut down and destroy the VM completely, run rake vagrant:destroy

Note that you need access to the Widgit CI server for this to work.


This project is licensed under the Apache License 2.0.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request