+
+ Using Google Apps Provisioning+ Google Apps is a service which allows domain administrators to offer + their users managed access to Google services such as Mail, Calendar, + and Docs & Spreadsheets. The Provisioning API offers a programmatic + interface to configure this service. Specifically, this API allows + administrators the ability to create, retrieve, update, and delete + user accounts, nicknames, groups, and email lists. + + ++ This library implements version 2.0 of the Provisioning API. Access to + your account via the Provisioning API must be manually enabled for + each domain using the Google Apps control panel. Only certain + account types are able to enable this feature. + + ++ For more information on the Google Apps Provisioning API, including + instructions for enabling API access, refer to the » Provisioning + API V2.0 Reference. + + ++ + Setting the current domain+ In order to use the Provisioning API, the domain being + administered needs to be specified in all request URIs. In order + to ease development, this information is stored within both the + Gapps service and query classes to use when constructing + requests. + + +Setting the domain for the service class+ To set the domain for requests made by the service class, + either call setDomain() or specify the domain + when instantiating the service class. For example: + + +
Setting the domain for query classes+ Setting the domain for requests made by query classes is + similar to setting it for the service class-either call + setDomain() or specify the domain when creating + the query. For example: + + +
+ When using a service class factory method to create a query, + the service class will automatically set the query's domain to + match its own domain. As a result, it is not necessary to + specify the domain as part of the constructor arguments. + + +
Interacting with users+ Each user account on a Google Apps hosted domain is represented as + an instance of Zend_Gdata_Gapps_UserEntry. This class provides + access to all account properties including name, username, + password, access rights, and current quota. + + +Creating a user account+ User accounts can be created by calling the + createUser() convenience method: + + +
+ Users can also be created by instantiating UserEntry, + providing a username, given name, family name, and password, + then calling insertUser() on a service object to + upload the entry to the server. + + +
+ The user's password should normally be provided as cleartext. + Optionally, the password can be provided as an SHA-1 digest if + login->passwordHashFunction is set to + 'SHA-1'. + +Retrieving a user account+ Individual user accounts can be retrieved by calling the + retrieveUser() convenience method. If the user is + not found, NULL will be returned. + + ++ Users can also be retrieved by creating an + instance of Zend_Gdata_Gapps_UserQuery, setting its username + property to equal the username of the user that is to be + retrieved, and calling getUserEntry() on a + service object with that query. + + ++ If the specified user cannot be located a ServiceException + will be thrown with an error code of + Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST. + ServiceExceptions will be covered in the exceptions chapter. + +Retrieving all users in a domain+ To retrieve all users in a domain, call the + retrieveAllUsers() convenience method. + + +
+ This will create a Zend_Gdata_Gapps_UserFeed object which + holds each user on the domain. + + ++ Alternatively, call getUserFeed() with no + options. Keep in mind that on larger + domains this feed may be paged by the server. For more + information on paging, see the paging chapter. + + +
Updating a user account+ The easiest way to update a user account is to retrieve the + user as described in the previous sections, make any desired + changes, then call save() on that user. Any + changes made will be propagated to the server. + + +
Resetting a user's password+ A user's password can be reset to a new value by updating + the login->password property. + + +
+ Note that it is not possible to recover a password in this + manner as stored passwords are not made available via the + Provisioning API for security reasons. + +Forcing a user to change their password+ A user can be forced to change their password at their + next login by setting the + login->changePasswordAtNextLogin property to + TRUE. + + +
+ Similarly, this can be undone by setting the + login->changePasswordAtNextLogin property to + FALSE. + +Suspending a user account+ Users can be restricted from logging in without deleting + their user account by instead + suspending their user account. + Accounts can be suspended or restored by using the + suspendUser() and + restoreUser() convenience methods: + + +
+ Alternatively, you can set the UserEntry's + login->suspended property to + TRUE. + + +
+ To restore the user's access, set the + login->suspended property to + FALSE. + +Granting administrative rights+ Users can be granted the ability to administer your domain + by setting their login->admin property to + TRUE. + + +
+ And as expected, setting a user's login->admin + property to FALSE revokes their + administrative rights. + +Deleting user accounts+ Deleting a user account to which you already hold a UserEntry + is a simple as calling delete() on that + entry. + + +
+ If you do not have access to a UserEntry object for an + account, use the deleteUser() convenience method. + + +
Interacting with nicknames+ Nicknames serve as email aliases for existing users. Each nickname + contains precisely two key properties: its name and its owner. Any + email addressed to a nickname is forwarded to the user who owns + that nickname. + + ++ Nicknames are represented as an instances of + Zend_Gdata_Gapps_NicknameEntry. + + +Creating a nickname+ Nicknames can be created by calling the + createNickname() convenience method: + + +
+ Nicknames can also be created by instantiating NicknameEntry, + providing the nickname with a name and an owner, then calling + insertNickname() on a service object to upload + the entry to the server. + + +
Retrieving a nickname+ Nicknames can be retrieved by calling the + retrieveNickname() convenience method. This will + return NULL if a user is not found. + + +
+
+
+ + Individual nicknames can also be retrieved by creating an + instance of Zend_Gdata_Gapps_NicknameQuery, setting its + nickname property to equal the nickname that is to be + retrieved, and calling getNicknameEntry() on a + service object with that query. + + +
+
+
+ + As with users, if no corresponding nickname is found a + ServiceException will be thrown with an error code of + Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST. Again, these + will be discussed in the exceptions chapter. + +Retrieving all nicknames for a user+ To retrieve all nicknames associated with a given user, call + the convenience method retrieveNicknames(). + + +
+ This will create a Zend_Gdata_Gapps_NicknameFeed object which + holds each nickname associated with the specified user. + + ++ Alternatively, create a new Zend_Gdata_Gapps_NicknameQuery, + set its username property to the desired user, and submit the + query by calling getNicknameFeed() on a service + object. + + +
Retrieving all nicknames in a domain+ To retrieve all nicknames in a feed, simply call the + convenience method retrieveAllNicknames() + + +
+ This will create a Zend_Gdata_Gapps_NicknameFeed object which + holds each nickname on the domain. + + ++ Alternatively, call getNicknameFeed() on a + service object with no arguments. + + +
Deleting a nickname+ Deleting a nickname to which you already hold a NicknameEntry + for is a simple as calling delete() on that + entry. + + +
+ For nicknames which you do not hold a NicknameEntry for, use + the deleteNickname() convenience method. + + +
Interacting with groups+ Google Groups allows people to post messages like an email list. Google + is depreciating the Email List API. Google Groups provides some neat + features like nested groups and group owners. If you want to start + a new email lst, it is advisable to use Google Groups instead. + Google's Email List is not compatible with Google Groups. So if you + create an email list, it will not show up as a group. The opposite is + true as well. + + ++ Each group on a domain is represented as an instance of + Zend_Gdata_Gapps_GroupEntry. + + +Creating a group+ Groups can be created by calling the + createGroup() convenience method: + + +
+ Groups can also be created by instantiating + GroupEntry, providing a group id and name for the group, + then calling insertGroup() on a service + object to upload the entry to the server. + + +
Retrieving an individual group+ To retrieve an individual group, call the + retrieveGroup() convenience method: + + +
+
+
+ + This will create a Zend_Gdata_Gapps_GroupEntry + object which holds the properties about the group. + + ++ Alternatively, create a new Zend_Gdata_Gapps_GroupQuery, + set its groupId property to the desired group id, and + submit the query by calling getGroupEntry() + on a service object. + + + + +Retrieving all groups in a domain+ To retrieve all groups in a domain, call the convenience + method retrieveAllGroups(). + + +
+
+
+ + This will create a Zend_Gdata_Gapps_GroupFeed + object which holds each group on the domain. + + ++ Alternatively, call getGroupFeed() on a + service object with no arguments. + + + + +Deleting a group+ To delete a group, call the deleteGroup() convenience + method: + + +
Updating a group+ Groups can be updated by calling the + updateGroup() convenience method: + + +
+ The first parameter is required. The second, third and fourth parameter, + representing the group name, group descscription, and email permission, + respectively are optional. Setting any of these optional parameters + to null will not update that item. + +Retrieving all groups to which a person is a member+ To retrieve all groups to which a particular person is a + member, call the retrieveGroups() + convenience method: + + +
+
+
+ + This will create a Zend_Gdata_Gapps_GroupFeed + object which holds each group associated with the specified member. + + ++ Alternatively, create a new Zend_Gdata_Gapps_GroupQuery, + set its member property to the desired email address, and + submit the query by calling getGroupFeed() + on a service object. + + + + +Interacting with group members+ Each member subscribed to a group is represented by an + instance of Zend_Gdata_Gapps_MemberEntry. + Through this class, individual recipients can be added and removed + from groups. + + +Adding a member to a group+ To add a member to a group, simply call the + addMemberToGroup() convenience method: + + +
Check to see if member belongs to group+ To check to see if member belongs to group, simply call the + isMember() convenience method: + + +
+ The method returns a boolean value. If the member belongs to the + group specified, the method returns true, else it returns false. + +Removing a member from a group+ To remove a member from a group, call the + removeMemberFromGroup() convenience + method: + + +
Retrieving the list of members to a group+ The convenience method retrieveAllMembers() + can be used to retrieve the list of members of a group: + + +
+
+
+ + Alternatively, construct a new MemberQuery, set its groupId + property to match the desired group id, and call + getMemberFeed() on a service object. + + +
+
+
+ + This will create a Zend_Gdata_Gapps_MemberFeed + object which holds each member for the selected group. + +Interacting with group owners+ Each owner associated with a group is represented by an + instance of Zend_Gdata_Gapps_OwnerEntry. + Through this class, individual owners can be added and removed + from groups. + + +Adding an owner to a group+ To add an owner to a group, simply call the + addOwnerToGroup() convenience method: + + +
Retrieving the list of the owner of a group+ The convenience method retrieveGroupOwners() + can be used to retrieve the list of the owners of a group: + + +
+
+
+ + Alternatively, construct a new OwnerQuery, set its groupId + property to match the desired group id, and call + getOwnerFeed() on a service object. + + +
+
+
+ + This will create a Zend_Gdata_Gapps_OwnerFeed + object which holds each member for the selected group. + +Check to see if an email is the owner of a group+ To check to see if an email is the owner of a group, simply call + the isOwner() convenience method: + + +
+ The method returns a boolean value. If the email is the owner of + the group specified, the method returns true, else it returns false. + +Removing an owner from a group+ To remove an owner from a group, call the + removeOwnerFromGroup() convenience + method: + + +
Interacting with email lists+ Email lists allow several users to retrieve email addressed to a + single email address. Users do not need to be a + member of this domain in order to subscribe to an email list + provided their complete email address (including domain) is used. + + ++ Each email list on a domain is represented as an instance of + Zend_Gdata_Gapps_EmailListEntry. + + +Creating an email list+ Email lists can be created by calling the + createEmailList() convenience method: + + +
+ Email lists can also be created by instantiating + EmailListEntry, providing a name for the list, then calling + insertEmailList() on a service object to upload + the entry to the server. + + +
Retrieving all email lists to which a recipient is subscribed+ To retrieve all email lists to which a particular recipient is + subscribed, call the retrieveEmailLists() + convenience method: + + +
+ This will create a Zend_Gdata_Gapps_EmailListFeed object + which holds each email list associated with the specified recipient. + + ++ Alternatively, create a new Zend_Gdata_Gapps_EmailListQuery, + set its recipient property to the desired email address, and + submit the query by calling getEmailListFeed() on + a service object. + + +
Retrieving all email lists in a domain+ To retrieve all email lists in a domain, call the convenience + method retrieveAllEmailLists(). + + +
+ This will create a Zend_Gdata_Gapps_EmailListFeed object + which holds each email list on the domain. + + ++ Alternatively, call getEmailListFeed() on a + service object with no arguments. + + +
Deleting an email list+ To delete an email list, call the deleteEmailList() + convenience method: + + +
Interacting with email list recipients+ Each recipient subscribed to an email list is represented by an + instance of Zend_Gdata_Gapps_EmailListRecipient. Through this + class, individual recipients can be added and removed from email + lists. + + +Adding a recipient to an email list+ To add a recipient to an email list, simply call the + addRecipientToEmailList() convenience method: + + +
Retrieving the list of subscribers to an email list+ The convenience method retrieveAllRecipients() + can be used to retrieve the list of subscribers to an email list: + + +
+ Alternatively, construct a new EmailListRecipientQuery, set + its emailListName property to match the desired email list, + and call getEmailListRecipientFeed() on a service + object. + + +
+ This will create a Zend_Gdata_Gapps_EmailListRecipientFeed + object which holds each recipient for the selected email list. + +Removing a recipient from an email list+ To remove a recipient from an email list, call the + removeRecipientFromEmailList() convenience + method: + + +
Handling errors+ In addition to the standard suite of exceptions thrown by + Zend_Gdata, requests using the Provisioning + API may also throw a + Zend_Gdata_Gapps_ServiceException. These exceptions + indicate that a API specific error occurred which prevents the + request from completing. + + ++ Each ServiceException instance may hold one or more Error objects. + Each of these objects contains an error code, reason, and + (optionally) the input which triggered the exception. A complete + list of known error codes is provided in Zend Framework's API + documentation under Zend_Gdata_Gapps_Error. Additionally, the + authoritative error list is available online at » Google + Apps Provisioning API V2.0 Reference: Appendix D. + + ++ While the complete list of errors received is available within + ServiceException as an array by calling getErrors(), + often it is convenient to know if one specific error occurred. For + these cases the presence of an error can be determined by calling + hasError(). + + ++ The following example demonstrates how to detect if a requested + resource doesn't exist and handle the fault gracefully: + + +
+ +
|
+
+
|
+