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. Our experiments showed that a session can expire even after around 2 minutes, so we'll just get a new session every 1 minute.

60
@@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) 


155
156
157
 
# File 'lib/ecircle/api.rb', line 155

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:



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

def create_member user_id, group_id, invite = false, send_message = false
  body = {
    :userId      => user_id,
    :groupId     => group_id,
    :invite      => invite.to_s,
    :sendMessage => send_message.to_s
  }

  request(:createMember, body) do |response|
    { :ecircle_id => response.body[:create_member_response][:create_member_return].to_s }
  end
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:



55
56
57
58
59
60
61
62
63
 
# File 'lib/ecircle/api.rb', line 55

def create_or_update_group group_attributes
  body = {
    :groupXml => Helper.build_group_xml(group_attributes)
  }

  request(:createOrUpdateGroup, body) do |response|
    { :ecircle_id => response[:create_or_update_group_response][:create_or_update_group_return].to_i }
  end
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



70
71
72
73
74
75
76
77
78
79
 
# File 'lib/ecircle/api.rb', line 70

def create_or_update_user_by_email user_attributes
  body = {
    :userXml     => Helper.build_user_xml(user_attributes),
    :sendMessage => 0
  }

  request(:createOrUpdateUserByEmail, body) do |response|
    { :ecircle_id => response.body[:create_or_update_user_by_email_response][:create_or_update_user_by_email_return].to_i }
  end
end

#delete_group(group_id) ⇒ WrappedResponse

Delete a member.

Parameters:

  • group_id (Integer) —

    ecircle group id

Returns:



85
86
87
 
# File 'lib/ecircle/api.rb', line 85

def delete_group group_id
  request(:deleteGroup, :memberId => group_id)
end

#delete_member(member_id) ⇒ WrappedResponse

Delete a member.

Parameters:

  • member_id (Integer) —

    ecircle member id

Returns:



93
94
95
 
# File 'lib/ecircle/api.rb', line 93

def delete_member member_id
  request(:deleteMember, :memberId => member_id)
end

#logon ⇒ String

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

Returns:

  • (String) —

    the session id



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/ecircle/api.rb', line 118

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



140
141
142
143
144
145
146
147
 
# File 'lib/ecircle/api.rb', line 140

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

#obtain_auth_token ⇒ Object 



149
150
151
152
153
 
# File 'lib/ecircle/api.rb', line 149

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:



104
105
106
107
108
109
110
111
112
113
 
# File 'lib/ecircle/api.rb', line 104

def send_parametrized_single_message_to_user user_id, message_id, names = [], values = []
  body = {
    :singleMessageId => message_id,
    :userId          => user_id,
    :names           => names,
    :values          => values
  }

  request(:sendParametrizedSingleMessageToUser, body)
end