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, , originator, environment = 2)
# Create new SmsService instance
@sms = SmsService::SmsService.new(USERNAME, PASSWORD)
# Send SMS to cell phone
@sms.send_sms(number, , 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.