Class GAppsProvisioning::ProvisioningApi
In: provisioningapi.rb
Parent: Object

Administrative object for accessing your domain

Examples

     adminuser = "root@mydomain.com"
     password  = "PaSsWo4d!"
     myapps = ProvisioningApi.new(adminuser,password)
     (see examples in  ProvisioningApi.new documentation for handling proxies)

     new_user = myapps.create_user("jsmith", "john", "smith", "secret", nil, "2048")
     puts new_user.family_name
     puts new_user.given_name

Want to update a user ?

     user = myapps.retrieve_user('jsmith')
     user_updated = myapps.update_user(user.username, user.given_name, user.family_name, nil, nil, "true")

Want to add an alias or nickname ?

     new_nickname = myapps.create_nickname("jsmith", "john.smith")

Want to manage groups ? (i.e. mailing lists)

     new_group = myapps.create_group("sales-dep", ['Sales Departement'])
     new_member1 = myapps.add_member_to_group("john.doe@somedomain.com", "sales-dep")
     new_member2 = myapps.add_member_to_group("jsmith", "sales-dep")
     new_owner = myapps.add_owner_to_group("jsmith", "sales-dep")
              (ATTENTION: an owner is added only if it's already member of the group!)

Want to handle errors ?

     begin
             user = myapps.retrieve_user('noone')
             puts "givenName : "+user.given_name, "familyName : "+user.family_name, "username : "+user.username"
             puts "admin ? : "+user.admin
     rescue GDataError => e
             puts "errorcode = " +e.code, "input : "+e.input, "reason : "+e.reason
     end

Methods

Attributes

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

Public Class methods

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('root@mydomain.com','PaSsWoRd')
     proxy :
     myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd','domain.proxy.com',8080)
     authenticated proxy :
     myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd','domain.proxy.com',8080,'foo','bAr')

Public Instance methods

addMemberToGroup(email_address, group_id)
addOwnerToGroup(email_address, group_id)

Alias for add_owner_to_group

Deprecated. Please use Group management instead.

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('root@mydomain.com','PaSsWoRd')
            new_member = myapps.add_member_to_group('example@otherdomain.com', 'mygroup')

Adds a owner (user or group) to a mailing list in your domain and returns a OwnerEntry instance. You can add addresses from other domains to your mailing list. Omit "@mydomain.com" in the group name. ATTENTION: a owner is added only if it‘s already member of the group, otherwise no action is done!

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            new_member = myapps.add_owner_to_group('example@otherdomain.com', 'mygroup')
createGroup(group_id, properties)

Alias for create_group

createNickname(username,nickname)

Alias for create_nickname

createUser(username, given_name, family_name, password, passwd_hash_function=nil, quota=nil)

Alias for create_user

Deprecated. Please use Group management instead.

Creates a group in your domain and returns a GroupEntry (ATTENTION: the group name is necessary!).

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            group= myapps.create_group("mygroup", ["My Group name", "My Group description", "<emailPermission>"])

Creates a nickname for the username in your domain and returns a NicknameEntry instance

            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            mynewnick = myapps.create_nickname('jsmith', 'john.smith')

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('root@mydomain.com','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.

deleteGroup(group_id)

Alias for delete_group

deleteNickname(nickname)

Alias for delete_nickname

deleteUser(username)

Alias for delete_user

Deprecated. Please use Group management instead.

Deletes a group in your domain.

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            myapps.delete_group("mygroup")

Deletes the nickname in your domain

            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            myapps.delete_nickname('john.smith')

Deletes an account in your domain

            ex :
                    myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
                    myapps.delete('jsmith')
isMember(email_address, group_id)

Alias for is_member

isOwner(email_address, group_id)

Alias for is_owner

Returns true if the email address (user or group) is member of the group, false otherwise.

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            boolean = myapps.is_member('example@otherdomain.com', 'mylist')

Returns true if the email address (user or group) is owner of the group, false otherwise.

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            boolean = myapps.is_owner('example@otherdomain.com', 'mylist')
removeMemberFromGroup(email_address, group_id)
removeOwnerFromGroup(email_address, group_id)
removeRecipientFromEmailList(address,email_list)

Deprecated. Please use Group management instead.

Removes an email address (user or group) from a mailing list. Omit "@mydomain.com" in the group name.

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            myapps.remove_member_from_group('example@otherdomain.com', 'mygroup')

Removes an owner from a mailing list. Omit "@mydomain.com" in the group name. ATTENTION: when a owner is removed, it loses the privileges but still remains member of the group!

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            myapps.remove_owner_from_group('example@otherdomain.com', 'mygroup')
renameUser(username, new_username)

Alias for rename_user

Renames a user, returns a UserEntry instance

            ex :

                    myapps = ProvisioningApi.new('root@mydomain.com','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.
restoreUser(username)

Alias for restore_user

Restores a suspended account in your domain, returns a UserEntry instance

            ex :
                    myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
                    user = myapps.restore('jsmith')
                    puts user.suspended               => "false"
retrieveAllGroups()
retrieveAllMembers(group_id)
retrieveAllNicknames()
retrieveAllOwners(group_id)
retrieveAllRecipients(email_list)
retrieveAllUsers()

Alias for retrieve_all_users

retrieveGroups(user)

Alias for retrieve_groups

retrieveNickname(nickname)

Alias for retrieve_nickname

retrieveNicknames(username)

Alias for retrieve_nicknames

retrievePageOfNicknames(start_nickname)
retrievePageOfRecipients(email_list, start_recipient)
retrievePageOfUsers(start_username)
retrieveUser(username)

Alias for retrieve_user

Deprecated. Please use Group management instead.

Returns a GroupEntry array for the whole domain.

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            all_lists = myapps.retrieve_all_groups
            all_lists.each {|list| puts list.group_id }

Returns a MemberEntry array with the members of a group.

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            list = myapps.retrieve_all_members('mygroup')
            lists.each {|list| puts list.member_id }

Returns a NicknameEntry array for the whole domain. May take a while depending on the number of users in your domain.

    myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
    allnicks = myapps.retrieve_all_nicknames
    allnicks.each {|nick| puts nick.nickname }

Returns a OwnerEntry array with the owners of a group.

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            list = myapps.retrieve_all_owners('mygroup')
            lists.each {|list| puts list.owner_id }

Deprecated. Please use Group management instead.

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('root@mydomain.com','PaSsWoRd')
                    list= myapps.retrieve_all_users
                    list.each{ |user| puts user.username}
                    puts 'nb users : ',list.size

Deprecated. Please use Group management instead.

Returns a GroupEntry array for a particular member of the domain (ATTENTION: it doesn‘t work for members of other domains!). The user parameter can be a complete email address or can be written without "@mydomain.com".

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            mylists = myapps.retrieve_groups('jsmith')   # you can search for 'jsmith@mydomain.com' too
            mylists.each {|list| puts list.group_id }

Returns a NicknameEntry instance from a nickname

    ex :
                    myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
                    nickname = myapps.retrieve_nickname('jsmith')
                    puts "login : "+nickname.login

Returns a NicknameEntry array from a username

    ex : lists jsmith's nicknames
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            mynicks = myapps.retrieve('jsmith')
            mynicks.each {|nick| puts nick.nickname }

Deprecated. Please use Group management instead.

Returns a NicknameEntry array populated with 100 nicknames, starting from a nickname

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            list= myapps.retrieve_page_of_nicknames("joe")
            list.each{ |nick| puts nick.login}

Deprecated. Please use Group management instead.

Returns a UserEntry array populated with 100 users, starting from a username

    ex :
                    myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
                    list= myapps.retrieve_page_of_users("jsmtih")
            list.each{ |user| puts user.username}

Returns a UserEntry instance from a username

    ex :
                    myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
                    user = myapps.retrieve_user('jsmith')
                    puts "givenName : "+user.given_name
                    puts "familyName : "+user.family_name
suspendUser(username)

Alias for suspend_user

Suspends an account in your domain, returns a UserEntry instance

            ex :
                    myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
                    user = myapps.suspend('jsmith')
                    puts user.suspended               => "true"
updateGroup(group_id, properties)

Alias for update_group

updateUser(username, given_name, family_name, password=nil, passwd_hash_function=nil, admin=nil, suspended=nil, changepasswd=nil, quota=nil)

Alias for update_user

Updates a group in your domain and returns a GroupEntry (ATTENTION: the group name is necessary!).

    ex :
            myapps = ProvisioningApi.new('root@mydomain.com','PaSsWoRd')
            group= myapps.update_group("mygroup", ["My Group name", "My Group description", "<emailPermission>"])

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('root@mydomain.com','PaSsWoRd')
                    user = myapps.update('jsmith', 'John', 'Smith', nil, nil, "true", nil, "true", nil)
                    puts user.admin           => "true"

[Validate]