Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
The ecircle gem: Eases the pain when dealing with the most horrible API on this planet
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
.rvmrc
.travis.yml
.yardopts
Gemfile
Gemfile.lock
README.md
Rakefile
ecircle.gemspec

README.md

Travis Build Status

Build Status

Synopsis

This gem aims to be a full-fledged solution for the ecircle API, the synchronous one and the asynchronous one.

The API coverage is far from complete, however as far as I can see the most useful / frequent methods are covered.

The existing API methods can be considered stable and are used in production.

Features

Synchronous API

The following methods are implemented:

  • createMember
  • createOrUpdateGroup
  • createOrUpdateUserByEmail
  • deleteGroup
  • deleteMember
  • logon (only for debugging purposes)
  • logout
  • sendParametrizedSingleMessageToUser

See the online API documentation for details on arguments and return values

Asnchronous API

Since the asynchronous API is neither documented by ecircle nor intuitive at all, you're on your own. Jump to the examples section and good luck.

To do

  • Fix TODOs in source code
  • Implement missing API methods:
    • deleteUser
    • deleteUserByEmail
    • lookupGroups
  • Write specs

Installation

Either as a gem:

gem install ecircle

or via Bundler by adding it to your Gemfile.

Configuration

Ecircle.configure do |config|
  config.user       = 'your@user.com'
  config.sync_realm = 'http://your.realm.com'
  config.password   = 'your_password'
end

The reason for the unusual configuration setting "sync_realm" is that there is also an asynchronous ecircle API with a different realm.

Logon

The ecircle gem does the session handling for you, there is no need to logon explicitly. Session tokens will be re-used to keep the number of session related traffic to a minimum.

Response

The ecircle gem will always return a wrapped response for all API methods, except for the logon method (see examples below or the API doc).

The wrapped response object is just a neat abstraction to hide Ecircle's horrible, horrible error handling from you and provides several methods for doing so.

The most usefull (and self-explanatory) would be:

  • success?
  • error_message
  • fault_code
  • ecircle_id IF the API returns an ID an success, e.g. for create_member and create_or_update_user_by_email
  • convenience methods which depend on your (failed request), e.g.:
    • member_does_not_exist? (relevant for create_member requests)
    • TODO Explain all convenience methods.

For details see here

Examples

Synchronous API

# Given you have called Ecircle.configure appropriatly...

# 1.) Create a user
r = Ecircle.create_or_update_user_by_email 'your@email.com'
uid = r.ecircle_id
puts "Ecircle user ID: #{uid}"

# 2.) Create a group
r = Ecircle.create_or_update_group :name => 'ecircletestgroup', :description => 'ecircletestgroup', :email => 'email@your.ecircle.domain.de'
gid = r.ecircle_id
puts "Ecircle group ID: #{gid}"

# 3.) Add this user as a member to a group - e.g. for newsletters
r = Ecircle.create_member uid, gid
mid = r.ecircle_id
puts "Ecircle member Id: #{mid}"

# 4.) Delete member from group - e.g. when he unsubscribes
Ecircle.delete_member mid

# 5.) Send the user a transactional email:
Ecircle.send_parametrized_single_message_to_user uid,
                                                your_template_id_at_ecircle,
                                                [ :name, :message ],
                                                [ 'Tom', 'welcome!' ]

# 6.) Delete the group
Ecircle.delete_group your_group_id

# 7.) Log out
Ecircle.logout

Asynchronous API

Note the async_realm in the configure block, this another realm as for the sync API.

Ecircle.configure do |config|
  config.user        = 'your@user.com'
  config.async_realm = 'http://your.async.realm.com' # IMPORTANT - different realm.
  config.password    = 'your_password'
end

@options = {
  :endpoint                     => 'http://your.domain/eC-MessageService',
  :request_id                   => '1234',
  :group_id                     => '5678',
  :send_out_date                => 70.minutes.from_now, # Must be at least one hour in the future!
  :send_date_for_report         => 140.minutes.from_now,  # Must be at least one hour in the future *after* dispatching!
  :report_email                 => 'your@report.de',
  :report_email_name            => 'Your name',
  :subject                      => 'Newsletter',
  :text                         => 'Newsletter text content',
  :html                         => 'Newsletter html content'
}

Ecircle::JobPackage.send_async_message_to_group @options

Documentation

Something went wrong with that request. Please try again.