Class: GAppsProvisioning::ProvisioningApi

Inherits:
Object
  • Object
show all
Defined in:
lib/gappsprovisioning/provisioningapi.rb

Constant Summary collapse

@@google_host =
'apps-apis.google.com'
@@google_port =
443

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mail, passwd, proxy = nil, proxy_port = nil, proxy_user = nil, proxy_passwd = nil) ⇒ ProvisioningApi

Creates a new ProvisioningApi object

mail : Google Apps domain administrator e-mail (string) passwd : Google Apps domain administrator password (string) proxy : (optional) host name, or IP, of the proxy (string) proxy_port : (optional) proxy port number (numeric) proxy_user : (optional) login for authenticated proxy only (string) proxy_passwd : (optional) password for authenticated proxy only (string)

The domain name is extracted from the mail param value.

Examples : standard : no proxy myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') proxy : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd','domain.proxy.com',8080) authenticated proxy : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd','domain.proxy.com',8080,'foo','bAr')


157
158
159
160
161
162
163
164
165
# File 'lib/gappsprovisioning/provisioningapi.rb', line 157

def initialize(mail, passwd, proxy=nil, proxy_port=nil, proxy_user=nil, proxy_passwd=nil)
	domain = mail.split('@')[1]
	@action = setup_actions(domain)
	conn = Connection.new(@@google_host, @@google_port, proxy, proxy_port, proxy_user, proxy_passwd)
	@connection = conn
	@token = (mail, passwd)
	@headers = {'Content-Type'=>'application/atom+xml', 'Authorization'=> 'GoogleLogin auth='+token}
	return @connection
end

Instance Attribute Details

#tokenObject (readonly)

authentication token, valid up to 24 hours after the last connection


136
137
138
# File 'lib/gappsprovisioning/provisioningapi.rb', line 136

def token
  @token
end

Instance Method Details

#add_address_to_email_list(email_list, address) ⇒ Object

Deprecated. Please use Group management instead.


395
396
397
# File 'lib/gappsprovisioning/provisioningapi.rb', line 395

def add_address_to_email_list(email_list,address)
	puts("add_address_to_email_list : deprecated. Please use Group management instead.")
end

#add_member_to_group(email_address, group_id) ⇒ Object Also known as: addMemberToGroup

Adds an email address (user or group) to a mailing list in your domain and returns a MemberEntry instance. You can add addresses from other domains to your mailing list. Omit “@mydomain.com” in the group name. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') new_member = myapps.add_member_to_group('[email protected]', 'mygroup')


462
463
464
465
466
467
# File 'lib/gappsprovisioning/provisioningapi.rb', line 462

def add_member_to_group(email_address, group_id)
	msg = RequestMessage.new
	msg.about_member(email_address)
	response  = request(:membership_add, group_id+'/member', @headers, msg.to_s)
	member_entry = MemberEntry.new(response.elements["entry"])
end

#add_owner_to_group(email_address, group_id) ⇒ Object Also known as: addOwnerToGroup

ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') new_member = myapps.add_owner_to_group('[email protected]', 'mygroup')


507
508
509
510
511
512
# File 'lib/gappsprovisioning/provisioningapi.rb', line 507

def add_owner_to_group(email_address, group_id)
	msg = RequestMessage.new
	msg.about_owner(email_address)
	response  = request(:ownership_add, group_id+'/owner', @headers, msg.to_s)
	owner_entry = OwnerEntry.new(response.elements["entry"])
end

#create_email_list(name) ⇒ Object

Deprecated. Please use Group management instead.


375
376
377
# File 'lib/gappsprovisioning/provisioningapi.rb', line 375

def create_email_list(name)
	puts("create_email_list : deprecated. Please use Group management instead.")
end

#create_group(group_id, properties) ⇒ Object Also known as: createGroup

Creates a group in your domain and returns a GroupEntry (ATTENTION: the group name is necessary!). ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') group= myapps.create_group(“mygroup”, [“My Group name”, “My Group description”, “<emailPermission>”])


408
409
410
411
412
413
# File 'lib/gappsprovisioning/provisioningapi.rb', line 408

def create_group(group_id, properties)
	msg = RequestMessage.new
	msg.about_group(group_id, properties)
	response  = request(:group_create, nil, @headers, msg.to_s)
	group_entry = GroupEntry.new(response.elements["entry"])
end

#create_nickname(username, nickname) ⇒ Object Also known as: createNickname

Creates a nickname for the username in your domain and returns a NicknameEntry instance myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') mynewnick = myapps.create_nickname('jsmith', 'john.smith')


333
334
335
336
337
338
339
# File 'lib/gappsprovisioning/provisioningapi.rb', line 333

def create_nickname(username,nickname)
	msg = RequestMessage.new
	msg.(username)
	msg.about_nickname(nickname)
	response  = request(:nickname_create,nil,@headers, msg.to_s)
	nickname_entry = NicknameEntry.new(response.elements["entry"])
end

#create_user(username, given_name, family_name, password, passwd_hash_function = nil, quota = nil) ⇒ Object Also known as: createUser

Creates an account in your domain, returns a UserEntry instance params : username, given_name, family_name and password are required passwd_hash_function (optional) : nil (default) or “SHA-1” quota (optional) : nil (default) or integer for limit in MB ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') user = myapps.create('jsmith', 'John', 'Smith', 'p455wD')

By default, a new user must change his password at first login. Please use update_user if you want to change this just after the creation.


213
214
215
216
217
218
219
220
# File 'lib/gappsprovisioning/provisioningapi.rb', line 213

def create_user(username, given_name, family_name, password, passwd_hash_function=nil, quota=nil)
	msg = RequestMessage.new
	msg.(username,password,passwd_hash_function,"false","false", "true")
	msg.about_name(family_name, given_name)
	msg.about_quota(quota.to_s) if quota
	response  = request(:user_create,nil,@headers, msg.to_s)
	user_entry = UserEntry.new(response.elements["entry"])
end

#delete_email_list(name) ⇒ Object

Deprecated. Please use Group management instead.


380
381
382
# File 'lib/gappsprovisioning/provisioningapi.rb', line 380

def delete_email_list(name)
	puts("delete_email_list : deprecated. Please use Group management instead.")
end

#delete_group(group_id) ⇒ Object Also known as: deleteGroup

Deletes a group in your domain. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') myapps.delete_group(“mygroup”)


430
431
432
# File 'lib/gappsprovisioning/provisioningapi.rb', line 430

def delete_group(group_id)
	response  = request(:group_delete,group_id,@headers)
end

#delete_nickname(nickname) ⇒ Object Also known as: deleteNickname

Deletes the nickname in your domain myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') myapps.delete_nickname('john.smith')


344
345
346
# File 'lib/gappsprovisioning/provisioningapi.rb', line 344

def delete_nickname(nickname)
	response  = request(:nickname_delete,nickname,@headers)
end

#delete_user(username) ⇒ Object Also known as: deleteUser

Deletes an account in your domain ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') myapps.delete('jsmith')


295
296
297
# File 'lib/gappsprovisioning/provisioningapi.rb', line 295

def delete_user(username)
	response  = request(:user_delete,username,@headers)
end

#is_member(email_address, group_id) ⇒ Object Also known as: isMember

Returns true if the email address (user or group) is member of the group, false otherwise. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') boolean = myapps.is_member('[email protected]', 'mylist')


481
482
483
484
485
486
487
488
# File 'lib/gappsprovisioning/provisioningapi.rb', line 481

def is_member(email_address, group_id)
	xml_response = request(:membership_confirm, group_id+'/member/'+email_address, @headers)
                      # if the email_address is not member of the group, an error is raised, otherwise true is returned 
                      return true

                      rescue GDataError => e
                      return false if e.reason.eql?("EntityDoesNotExist")
end

#is_owner(email_address, group_id) ⇒ Object Also known as: isOwner

Returns true if the email address (user or group) is owner of the group, false otherwise. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') boolean = myapps.is_owner('[email protected]', 'mylist')


527
528
529
530
531
532
533
534
# File 'lib/gappsprovisioning/provisioningapi.rb', line 527

def is_owner(email_address, group_id)
	xml_response = request(:ownership_confirm, group_id+'/owner/'+email_address, @headers)
                      # if the email_address is not member of the group, an error is raised, otherwise true is returned 
                      return true

                      rescue GDataError => e
                      return false if e.reason.eql?("EntityDoesNotExist")
end

#remove_address_from_email_list(address, email_list) ⇒ Object Also known as: removeRecipientFromEmailList

Deprecated. Please use Group management instead.


400
401
402
# File 'lib/gappsprovisioning/provisioningapi.rb', line 400

def remove_address_from_email_list(address,email_list)
	puts("remove_address_from_email_list : deprecated. Please use Group management instead.")
end

#remove_member_from_group(email_address, group_id) ⇒ Object Also known as: removeMemberFromGroup

Removes an email address (user or group) from a mailing list. Omit “@mydomain.com” in the group name. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') myapps.remove_member_from_group('[email protected]', 'mygroup')


473
474
475
# File 'lib/gappsprovisioning/provisioningapi.rb', line 473

def remove_member_from_group(email_address, group_id)
	response  = request(:membership_remove, group_id+'/member/'+email_address,@headers)
end

#remove_owner_from_group(email_address, group_id) ⇒ Object Also known as: removeOwnerFromGroup

ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') myapps.remove_owner_from_group('[email protected]', 'mygroup')


519
520
521
# File 'lib/gappsprovisioning/provisioningapi.rb', line 519

def remove_owner_from_group(email_address, group_id)
	response  = request(:ownership_remove, group_id+'/owner/'+email_address,@headers)
end

#rename_user(username, new_username) ⇒ Object Also known as: renameUser

Renames a user, returns a UserEntry instance ex :

myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') user = myapps.rename_user('jsmith','jdoe')

It is recommended to log out rhe user from all browser sessions and service before renaming.

Once renamed, the old username becomes a nickname of the new username.

Note from Google: Google Talk will lose all remembered chat invitations after renaming. The user must request permission to chat with friends again. Also, when a user is renamed, the old username is retained as a nickname to ensure continuous mail delivery in the case of email forwarding settings. To remove the nickname, you should issue an HTTP DELETE to the nicknames feed after renaming.


258
259
260
261
262
263
# File 'lib/gappsprovisioning/provisioningapi.rb', line 258

def rename_user(username, new_username)
	msg = RequestMessage.new
	msg.(new_username)
	msg.add_path('https://'+@@google_host+@action[:user_rename][:path]+username)
	response  = request(:user_update,username,@headers, msg.to_s)
end

#restore_user(username) ⇒ Object Also known as: restoreUser

Restores a suspended account in your domain, returns a UserEntry instance ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') user = myapps.restore('jsmith') puts user.suspended => “false”


283
284
285
286
287
288
289
# File 'lib/gappsprovisioning/provisioningapi.rb', line 283

def restore_user(username)
	msg = RequestMessage.new
	msg.(username,nil,nil,nil,"false")
	msg.add_path('https://'+@@google_host+@action[:user_update][:path]+username)
	response  = request(:user_update,username,@headers, msg.to_s)
	user_entry = UserEntry.new(response.elements["entry"])
end

#retrieve_all_email_listsObject

Deprecated. Please use Group management instead.


365
366
367
# File 'lib/gappsprovisioning/provisioningapi.rb', line 365

def retrieve_all_email_lists
	puts("retrieve_all_email_lists : deprecated. Please use Group management instead.")
end

#retrieve_all_groupsObject Also known as: retrieveAllGroups

Returns a GroupEntry array for the whole domain. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') all_lists = myapps.retrieve_all_groups all_lists.each {|list| puts list.group_id }


451
452
453
454
455
# File 'lib/gappsprovisioning/provisioningapi.rb', line 451

def retrieve_all_groups
	xml_response = request(:all_groups_retrieve, nil, @headers)
	list_feed = Feed.new(xml_response.elements["feed"], GroupEntry) 
	list_feed = add_next_feeds(list_feed, xml_response, GroupEntry)
end

#retrieve_all_members(group_id) ⇒ Object Also known as: retrieveAllMembers

Returns a MemberEntry array with the members of a group. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') list = myapps.retrieve_all_members('mygroup') lists.each {|list| puts list.member_id }


495
496
497
498
499
# File 'lib/gappsprovisioning/provisioningapi.rb', line 495

def retrieve_all_members(group_id)
	xml_response = request(:all_members_retrieve, group_id+'/member', @headers)
	list_feed = Feed.new(xml_response.elements["feed"], MemberEntry)
	list_feed = add_next_feeds(list_feed, xml_response, MemberEntry)
end

#retrieve_all_nicknamesObject Also known as: retrieveAllNicknames

Returns a NicknameEntry array for the whole domain. May take a while depending on the number of users in your domain. myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') allnicks = myapps.retrieve_all_nicknames allnicks.each {|nick| puts nick.nickname }


324
325
326
327
328
# File 'lib/gappsprovisioning/provisioningapi.rb', line 324

def retrieve_all_nicknames
	xml_response = request(:nickname_retrieve_all_in_domain, nil, @headers)
	nicknames_feed = Feed.new(xml_response.elements["feed"],  NicknameEntry)
	nicknames_feed = add_next_feeds(nicknames_feed, xml_response, NicknameEntry)
end

#retrieve_all_owners(group_id) ⇒ Object Also known as: retrieveAllOwners

Returns a OwnerEntry array with the owners of a group. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') list = myapps.retrieve_all_owners('mygroup') lists.each {|list| puts list.owner_id }


541
542
543
544
545
# File 'lib/gappsprovisioning/provisioningapi.rb', line 541

def retrieve_all_owners(group_id)
	xml_response = request(:all_owners_retrieve, group_id+'/owner', @headers)
	list_feed = Feed.new(xml_response.elements["feed"], OwnerEntry)
	list_feed = add_next_feeds(list_feed, xml_response, OwnerEntry)
end

#retrieve_all_recipients(email_list) ⇒ Object Also known as: retrieveAllRecipients

Deprecated. Please use Group management instead.


385
386
387
# File 'lib/gappsprovisioning/provisioningapi.rb', line 385

def retrieve_all_recipients(email_list)
	puts("retrieve_all_recipients : deprecated. Please use Group management instead.")
end

#retrieve_all_usersObject Also known as: retrieveAllUsers

Returns a UserEntry array populated with all the users in the domain. May take a while depending on the number of users in your domain. ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') list= myapps.retrieve_all_users list.each{ |user| puts user.username} puts 'nb users : ',list.size


186
187
188
189
190
# File 'lib/gappsprovisioning/provisioningapi.rb', line 186

def retrieve_all_users
	response = request(:user_retrieve_all,nil,@headers)
	user_feed = Feed.new(response.elements["feed"],  UserEntry)
	user_feed = add_next_feeds(user_feed, response, UserEntry)
end

#retrieve_email_lists(email_adress) ⇒ Object

Deprecated. Please use Group management instead.


360
361
362
# File 'lib/gappsprovisioning/provisioningapi.rb', line 360

def retrieve_email_lists(email_adress)
	puts("retrieve_email_lists : deprecated. Please use Group management instead.")
end

#retrieve_groups(user) ⇒ Object Also known as: retrieveGroups

ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') mylists = myapps.retrieve_groups('jsmith') # you can search for '[email protected]' too mylists.each {|list| puts list.group_id }


440
441
442
443
444
# File 'lib/gappsprovisioning/provisioningapi.rb', line 440

def retrieve_groups(user)
	xml_response = request(:groups_retrieve, user, @headers)
	list_feed = Feed.new(xml_response.elements["feed"], GroupEntry) 
	list_feed = add_next_feeds(list_feed, xml_response, GroupEntry)
end

#retrieve_nickname(nickname) ⇒ Object Also known as: retrieveNickname

Returns a NicknameEntry instance from a nickname ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') nickname = myapps.retrieve_nickname('jsmith') puts “login : ”+nickname.login


304
305
306
307
# File 'lib/gappsprovisioning/provisioningapi.rb', line 304

def retrieve_nickname(nickname)
	xml_response = request(:nickname_retrieve, nickname, @headers)
	nickname_entry = NicknameEntry.new(xml_response.elements["entry"])
end

#retrieve_nicknames(username) ⇒ Object Also known as: retrieveNicknames

Returns a NicknameEntry array from a username ex : lists jsmith's nicknames myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') mynicks = myapps.retrieve('jsmith') mynicks.each {|nick| puts nick.nickname }


314
315
316
317
318
# File 'lib/gappsprovisioning/provisioningapi.rb', line 314

def retrieve_nicknames(username)
	xml_response = request(:nickname_retrieve_all_for_user, username, @headers)
	nicknames_feed = Feed.new(xml_response.elements["feed"],  NicknameEntry)
	nicknames_feed = add_next_feeds(nicknames_feed, xml_response, NicknameEntry)
end

#retrieve_page_of_email_lists(start_listname) ⇒ Object

Deprecated. Please use Group management instead.


370
371
372
# File 'lib/gappsprovisioning/provisioningapi.rb', line 370

def retrieve_page_of_email_lists(start_listname)
	puts("retrieve_page_of_email_lists : deprecated. Please use Group management instead.")
end

#retrieve_page_of_nicknames(start_nickname) ⇒ Object Also known as: retrievePageOfNicknames

Returns a NicknameEntry array populated with 100 nicknames, starting from a nickname ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') list= myapps.retrieve_page_of_nicknames(“joe”)

		list.each{ |nick| puts nick.}

353
354
355
356
357
# File 'lib/gappsprovisioning/provisioningapi.rb', line 353

def retrieve_page_of_nicknames(start_nickname)
	param='?startNickname='+start_nickname
	xml_response = request(:nickname_retrieve_all_in_domain, param, @headers)
	nicknames_feed = Feed.new(xml_response.elements["feed"],  NicknameEntry)
end

#retrieve_page_of_recipients(email_list, start_recipient) ⇒ Object Also known as: retrievePageOfRecipients

Deprecated. Please use Group management instead.


390
391
392
# File 'lib/gappsprovisioning/provisioningapi.rb', line 390

def retrieve_page_of_recipients(email_list, start_recipient)
	puts("Deprecated. Please use Group management instead.")
end

#retrieve_page_of_users(start_username) ⇒ Object Also known as: retrievePageOfUsers

Returns a UserEntry array populated with 100 users, starting from a username ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') list= myapps.retrieve_page_of_users(“jsmtih”)

		list.each{ |user| puts user.username}

197
198
199
200
201
# File 'lib/gappsprovisioning/provisioningapi.rb', line 197

def retrieve_page_of_users(start_username)
	param='?startUsername='+start_username
	response = request(:user_retrieve_all,param,@headers)
	user_feed = Feed.new(response.elements["feed"],  UserEntry)
end

#retrieve_user(username) ⇒ Object Also known as: retrieveUser

Returns a UserEntry instance from a username ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') user = myapps.retrieve_user('jsmith') puts “givenName : ”+user.given_name puts “familyName : ”+user.family_name


175
176
177
178
# File 'lib/gappsprovisioning/provisioningapi.rb', line 175

def retrieve_user(username)
	xml_response = request(:user_retrieve, username, @headers) 
	user_entry = UserEntry.new(xml_response.elements["entry"])
end

#suspend_user(username) ⇒ Object Also known as: suspendUser

Suspends an account in your domain, returns a UserEntry instance ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') user = myapps.suspend('jsmith') puts user.suspended => “true”


270
271
272
273
274
275
276
# File 'lib/gappsprovisioning/provisioningapi.rb', line 270

def suspend_user(username)
	msg = RequestMessage.new
	msg.(username,nil,nil,nil,"true")
	msg.add_path('https://'+@@google_host+@action[:user_update][:path]+username)
	response  = request(:user_update,username,@headers, msg.to_s)
	user_entry = UserEntry.new(response.elements["entry"])
end

#update_group(group_id, properties) ⇒ Object Also known as: updateGroup

Updates a group in your domain and returns a GroupEntry (ATTENTION: the group name is necessary!). ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') group= myapps.update_group(“mygroup”, [“My Group name”, “My Group description”, “<emailPermission>”])


419
420
421
422
423
424
# File 'lib/gappsprovisioning/provisioningapi.rb', line 419

def update_group(group_id, properties)
	msg = RequestMessage.new
	msg.about_group(group_id, properties)
	response  = request(:group_update, group_id, @headers, msg.to_s)
	group_entry = GroupEntry.new(response.elements["entry"])
end

#update_user(username, given_name, family_name, password = nil, passwd_hash_function = nil, admin = nil, suspended = nil, changepasswd = nil, quota = nil) ⇒ Object Also known as: updateUser

Updates an account in your domain, returns a UserEntry instance params : username is required and can't be updated. given_name and family_name are required, may be updated. if set to nil, every other parameter won't update the attribute. passwd_hash_function : string “SHA-1”, “MD5” or nil (default) admin : string “true” or string “false” or nil (no boolean : true or false). suspended : string “true” or string “false” or nil (no boolean : true or false) change_passwd : string “true” or string “false” or nil (no boolean : true or false) quota : limit en MB, ex : string “2048” ex : myapps = ProvisioningApi.new('[email protected]','PaSsWoRd') user = myapps.update('jsmith', 'John', 'Smith', nil, nil, “true”, nil, “true”, nil) puts user.admin => “true”


236
237
238
239
240
241
242
243
244
# File 'lib/gappsprovisioning/provisioningapi.rb', line 236

def update_user(username, given_name, family_name, password=nil, passwd_hash_function=nil, admin=nil, suspended=nil, changepasswd=nil, quota=nil)
	msg = RequestMessage.new
	msg.(username,password,passwd_hash_function,admin,suspended, changepasswd)
	msg.about_name(family_name, given_name)
	msg.about_quota(quota) if quota
	msg.add_path('https://'+@@google_host+@action[:user_update][:path]+username)
	response  = request(:user_update,username,@headers, msg.to_s)
	user_entry = UserEntry.new(response.elements["entry"])
end