developergarden_sdk

This library provides access to open development services of the Deutsche Telekom AG. For more details about the services see

http://www.developergarden.com

Depending on your operating system you might want to skip the “sudo” command prior to the commands listed here.

Dependencies

In order to use this library the following dependencies need to be met: 

Ruby 1.8.6
Ruby Gems >= 1.3.1

There might be issues with Ruby 1.8.7 regarding to curb so it is highly recommended to use Ruby 1.8.6.

Gems

The following gems need to be installed:

  • handsoap (Version 0.2.8)

  • nokogiri

  • httpclient (Version 2.1.14)

  • htmlentities

Install the handsoap gem

For production use the official release of handsoap should be installed. More information about handsoap can be found at:

http://github.com/troelskn/handsoap/tree/master

Install official handsoap release

gem sources -a http://gems.github.com
sudo gem install troelskn-handsoap

Install handsoap developer version

If you want to use the bleeding edge version of handsoap proceed as follows. Note that you do not need to perform these steps if you have already installed the official release!

Checkout handsoap from github

git clone git://github.com/troelskn/handsoap.git

Install jeweler

sudo gem install jeweler

Build handsoap package

cd handsoap_git_repo
rake build

Install the resulting gem file

cd pkg
sudo gem install handsoap-0.2.7.gem

Attention: if you you use the development version you might need to change the gem statement in

basic_service.rb from

gem 'troelskn-handsoap'

to

gem 'handsoap'

Installation of the developergarden_sdk Gem

Install the gem using the following command

gem install developergarden_sdk-0.0.x.gem

Where x stands for the current version. For the version 0.0.4 this could look like this:

gem install developergarden_sdk-0.0.x.gem

Basic usage

You can use the gem from pure Ruby applications and of course from Ruby on Rails apps as well.

To use the gem from your Ruby app:

require 'rubygems'
gem 'developergarden_sdk'
require 'token_Service/token_service'
require 'sms_service/sms_service'
require 'voice_call_service/voice_call_service'
require 'quota_service/quota_service'
require 'service_environment'

Ruby Example to send a sms

#!/usr/bin/env ruby -d

require 'rubygems'
gem 'developergarden_sdk'
require 'token_Service/token_service'
require 'sms_service/sms_service'
require 'service_environment'

sms = SmsService::SmsService.new("<USER>@t-online.de", "<PASSWORD>")
sms_response = sms.send_sms("+49177 0000001", "Your message text.", "RubySDK", ServiceEnvironment.PRODUCTION, "")

To use your gem from your Ruby on Rails app

In your environment.rb add the following line in the config block:

config.gem 'developergarden_sdk'

Ruby on Rails Example

class SmsNotification

  USERNAME = "<USER>@t-online.de"
  PASSWORD = "<PASSWORD>"

  # Send SMS to Numbers.
  def send_sms(number, message, originator, environment = 2)

  # Create new SmsService instance
  @sms = SmsService::SmsService.new(USERNAME, PASSWORD)

  # Send SMS to cell phone
  @sms.send_sms(number, message, originator, environment)

  end

end

More Examples

In order to see more examples have a look the unit tests included in the gem’s source code. You might also want to have a look at the actual source code and source code comments.

Debug

Per default all generated and received soap xml messages are not visible. These can be print to stdout for debugging purposes by starting the ruby interpreter with the -d option. You will then see all http xml soap requests and responses. This can be done by invoking your ruby app by using a shebang like this:

#!/usr/bin/ruby -d

Testing

Before you run the tests you will need to modify config/test_settings.yml by entering your developer garden credentials.

Executing tests will be done in the “sandbox” or “mock” environment which are free of charge. Be ware that the services itself have quotas on these test environments so your tests may fail after a while. The quotas are on a daily basis so they should pass again the next day.

Failures when reaching the SANDBOX QUOTA might look like this:

0030 quotas have exceeded

Phone numbers in test files are fictive and for testing purposes only.

The testsuite can be run by invoking the test raketask.

cd /home/yourhome/developergarden_sdk
rake test

In order to run a single test perform the following command:

cd /home/yourhome/developergarden_sdk/lib
ruby -d ../test/voice_call_service_test.rb --name teardown_call

QuotaService

  • QuotaService can be tested as it is. There is no need to pass an environment such as “production” or “sandbox” because

it is free of charge.

SmsService

  • SmsService can be tested using the “sandbox” environment. Be aware that there is a 5 credit quota per day. So you can

send 5 test sms per day. After that you will receive a corresponding quota error message.

VoiceCallService

  • In the “sandbox” environment there is a quota limit of 5 calls per day (each up to 10 sec) for the VoiceCallService

  • In the “production” environment a call may not last more than 60 minutes. After 60 min the call will be cancelled.

  • There is also a quota for the “mock” environment.

For more information about service environments have a look at the documentation at www.developergarden.com

Build the developergarden_sdk gem

You can build the gem by invoking the gem rake task

rake gem

The resulting gem will be generated to the pkg/ directory and can be installed like this:

sudo gem install developergarden_sdk-0.0.6.gem

Depending on the current version number you will need to adapt the gem filename correspondingly.

More Information

More information about developer garden services can be found at:

http://www.developergarden.com

FAQ

Did not understand “MustUnderstand” header(s)

Handsoap::Fault: Handsoap::Fault { :code => 'soapenv:MustUnderstand', :reason => 'Did not understand "MustUnderstand" header(s):{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}Security' }

You will receive this error message if a mandatory header element is not present or the remote service was unable to process it. Most likely this will happen if something is wrong during the authentication process such as missing parameters like username, password.