Class: Ecircle::Api

Inherits:
Object
  • Object
show all
Defined in:
lib/ecircle/api.rb

Constant Summary collapse

AUTH_TOKEN_TIMEOUT =

According to http://developer.ecircle-ag.com/apiwiki/wiki/SynchronousSoapAPI#section-SynchronousSoapAPI-SampleProtocolExcerpt, a session expires after 10 minutes (600 seconds) of idleness. We give ourselves a 30-second margin.

570
@@help = 
<<-doc
!!!
Got an authentication exception, chances are good that you're credentials are wrong, so better double check that.
You can explicitly check for it by calling something like:
Ecircle.configure do..
Ecircle.logon
!!!
doc

Instance Method Summary collapse

Instance Method Details

#auth_token_valid? ⇒ Boolean

Returns:

  • (Boolean) 


182
183
184
 
# File 'lib/ecircle/api.rb', line 182

def auth_token_valid?
  @auth_token_last_used_at && Time.now - @auth_token_last_used_at < AUTH_TOKEN_TIMEOUT
end

#create_member(user_id, group_id, invite = false, send_message = false) ⇒ WrappedResponse

Creates a member, which basically is just an association between a user and a group.

Parameters:

  • user_id (Integer) —

    ecircle user_id

  • group_id (Integer) —

    ecircle group_id

  • invite (Boolean) (defaults to: false) —

    send an additional invite mail

  • send_message (Boolean) (defaults to: false) —

    send a message by ecircle

Returns:



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/ecircle/api.rb', line 34

def create_member user_id, group_id, invite = false, send_message = false
  response = client.request :createMember do
    soap.body = {
      :session     => obtain_auth_token,
      :userId      => user_id,
      :groupId     => group_id,
      :invite      => invite.to_s,
      :sendMessage => send_message.to_s
    }
  end
  WrappedResponse.new :success => true,
                      :ecircle_id => response.body[:create_member_response][:create_member_return].to_s
rescue Savon::SOAP::Fault => e
  WrappedResponse.new(e)
end

#create_or_update_group(group_attributes) ⇒ WrappedResponse

Create or update group see http://developer.ecircle-ag.com/apiwiki/wiki/SynchronousSoapAPI#section-SynchronousSoapAPI-GroupObjectExample for an example of the group xml Important note: email must be unique across all groups AND must be a subdomain of the system you registered at ecircle.

Parameters:

  • group_xml, (Hash) —

    in it's most simple form a { :name => 'your name', :description => 'desc', ':email => '[email protected]' } is sufficient

Returns:



56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/ecircle/api.rb', line 56

def create_or_update_group group_attributes
  response = client.request :createOrUpdateGroup do
    soap.body = {
      :session   => obtain_auth_token,
      :groupXml  => Helper.build_group_xml(group_attributes)
    }
  end
  WrappedResponse.new :success => true,
                      :ecircle_id => response[:create_or_update_group_response][:create_or_update_group_return].to_i
rescue Savon::SOAP::Fault => e
  WrappedResponse.new(e)
end

#create_or_update_user_by_email(user_attributes) ⇒ Integer

Create or update user by email see http://developer.ecircle-ag.com/apiwiki/wiki/SynchronousSoapAPI#section-SynchronousSoapAPI-UserObjectExample for an example of the user xml

Parameters:

  • user_xml, (Hash) —

    in it's most simple form a { :email => '[email protected]' } is sufficient

Returns:

  • (Integer) —

    the user id



74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/ecircle/api.rb', line 74

def create_or_update_user_by_email user_attributes
  response = client.request :createOrUpdateUserByEmail do
    soap.body = {
      :session     => obtain_auth_token,
      :userXml     => Helper.build_user_xml(user_attributes),
      :sendMessage => 0
    }
  end
  WrappedResponse.new :success => true,
                      :ecircle_id => response.body[:create_or_update_user_by_email_response][:create_or_update_user_by_email_return].to_i
rescue Savon::SOAP::Fault => e
  WrappedResponse.new(e)
end

#delete_group(group_id) ⇒ WrappedResponse

Delete a member.

Parameters:

  • group_id (Integer) —

    ecircle group id

Returns:



92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/ecircle/api.rb', line 92

def delete_group group_id
  response = client.request :deleteGroup do
    soap.body = {
      :session  => obtain_auth_token,
      :memberId => group_id
    }
  end
  WrappedResponse.new(:success => true)
rescue Savon::SOAP::Fault => e
  WrappedResponse.new(e)
end

#delete_member(member_id) ⇒ WrappedResponse

Delete a member.

Parameters:

  • member_id (Integer) —

    ecircle member id

Returns:



108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/ecircle/api.rb', line 108

def delete_member member_id
  client.request :deleteMember do
    soap.body = {
      :session  => obtain_auth_token,
      :memberId => member_id
    }
  end
  WrappedResponse.new(:success => true)
rescue Savon::SOAP::Fault => e
  WrappedResponse.new(e)
end

#logon ⇒ String

Logon. You don't need to call this explicitly but it's useful for debugging.

Returns:

  • (String) —

    the session id



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/ecircle/api.rb', line 123

def logon
  response = client.request :logon do
    soap.body = {
      :user   => Ecircle.configuration.user,
      :realm  => Ecircle.configuration.sync_realm,
      :passwd => Ecircle.configuration.password
    }
  end
  response.body[:logon_response][:logon_return].to_s
rescue Savon::SOAP::Fault => e
  wrapped_response = WrappedResponse.new(e)
  if wrapped_response.not_authenticated? || wrapped_response.permission_problem?
    puts @@help
    raise InvalidLoginCredentials
  else
    raise
  end
end

#logout ⇒ Object

Log out. Uses the last session token.

Returns:

  • nil



145
146
147
148
149
150
151
152
 
# File 'lib/ecircle/api.rb', line 145

def logout
  client.request :logout do
    soap.body = {
      :session  => auth_token,
    }
  end
  WrappedResponse.new(:success => true)
end

#obtain_auth_token ⇒ Object 



176
177
178
179
180
 
# File 'lib/ecircle/api.rb', line 176

def obtain_auth_token
  @auth_token = logon unless auth_token_valid?
  @auth_token_last_used_at = Time.now
  @auth_token
end

#send_parametrized_single_message_to_user(user_id, message_id, names = [], values = []) ⇒ WrappedResponse

Send a parametrized single message to user - you need an existing ecircle template ID for this.

Parameters:

  • user_id (Integer) —

    ecircle user_id

  • message_id (Integer) —

    the ecircle template ID

  • the (Array) —

    names of the variables you want to interpolate in the template

  • the (Array) —

    values of the variables you want to interpolate in the template

Returns:



161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/ecircle/api.rb', line 161

def send_parametrized_single_message_to_user user_id, message_id, names = [], values = []
  client.request :sendParametrizedSingleMessageToUser do
    soap.body = {
      :session           => obtain_auth_token,
      :singleMessageId   => message_id,
      :userId            => user_id,
      :names             => names,
      :values            => values
    }
  end
  WrappedResponse.new(:success => true)
rescue Savon::SOAP::Fault => e
  WrappedResponse.new(e)
end