Note: The Provisioning API is only available to Google Apps Premier Edition and Google Apps Education Edition customers. To enable the API, log in to your admin account, and click the Users and groups tab. Then click the Settings subtab, select the checkbox to enable the Provisioning API and save your changes. (You will need to complete the steps for setting up Google Apps before you can log in to your admin account.)

Using the Java Client Library

The following subsections explain how to use the Google Apps Java client library to access Provisioning API functionality. Each subsection explains the Java client library methods for specific API functionality. These methods can be found in the sample.appsforyourdomain.AppsForYourDomainClient class.

Setup Getting Started Authenticating to your Domain Methods for User Accounts Creating a User Account Retrieving a User Account Retrieving all Users in a Domain Retrieving List of 100 Users Updating a User Account Suspending a User Account Restoring a User Account Deleting a User Account Methods for Nicknames Creating a Nickname Retrieving a Nickname Retrieving all Nicknames for a User Retrieving all Nicknames in a Domain Retrieving List of 100 Nicknames Deleting a Nickname

Methods for Groups New! Creating a Group Retrieving a Group Updating a Group Retrieving all Groups for a Member Retrieving all Groups in a Domain Deleting a Group Methods for Group Members New! Adding a Member to a Group Retrieving All Members of a Group Deleting a Member from a Group Methods for Group Owners New! Adding a Owner to a Group Querying if a User or Group is Owner Querying for All Owners of a Group Deleting an Owner from a Group Methods for Handling Errors Identifying Errors in API Responses

Getting Started

Before using the Provisioning API, you will need an administrator username and password for your Google Apps domain. You will also need to enable the Provisioning API for your Google Apps domain.

Follow the Getting Started article to install the necessary software for compiling and running Java programs which use Google Data APIs (including the Provisioning API).

Authenticating to your Domain

Before making API calls with the Java client library, you must construct a new AppsForYourDomainClient object. In the constructor, set your authentication information as follows:

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(adminEmail, adminPassword, domain);

Here, replace adminEmail with your domain administrator email, password with your domain administrator password, and domain with the domain to which you are authenticating.

Methods for User Accounts

Creating a User Account

To create a user account using the Java client library, call one of the following methods. These methods all return a UserEntry XML response, which the Java client library converts to a UserEntry object.

client.createUser(String username, String givenName, String familyName, String password)
client.createUser(String username, String givenName, String familyName, String password, Integer quotaLimitInMb)
client.createUser(String username, String givenName, String familyName, String password, String passwordHashFunction)
client.createUser(String username, String givenName, String familyName, String password, String passwordHashFunction, Integer quotaLimitInMb)

Note: Not all partners have the ability to adjust the disk space quota allocated to users. This method takes the following arguments:

• The username argument contains the unique name that identifies the account owner and cannot be a nickname of another user.
• The givenName argument contains the user's first name.
• The familyName argument contains the user's last name.
• The password argument contains the password for the user account.
• The passwordHashFunction argument specifies the hash format of the password parameter.
• The quotaLimitInMb argument identifies the amount of disk space in MB that will be allocated to the user account.

Retrieving a User Account

To retrieve information about a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

client.retrieveUser(String username)

The only argument that you need to pass to the method is the username associated with the account that you wish to retrieve.

Retrieving all Users in a Domain

To retrieve all of the users in a domain, you can call the following method in the Java client library. This method returns a UserFeed XML response, which the Java client library converts to a UserFeed object.

client.retrieveAllUsers()

Retrieving List of 100 Users

This method allows you to control the size of your result set when you request all of the users in your domain. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 users in your domain, you can call the following method in the Java client library. This method returns a UserFeed XML response, which the Java client library converts to a UserFeed object.

client.retrievePageOfUsers(String startUsername)

The only argument that you need to pass to the method is the first username that should appear in your result set. Usernames are ordered case-insensitively by ASCII value.

Updating a User Account

To update a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

client.updateUser(String username, UserEntry userEntry)

This method takes two arguments:

• The username argument identifies the account that you are updating.
• The userEntry object contains information about a user account, including the user's first name, last name, username and password. The createUser and retrieveUser methods both return a UserEntry object.

The common use case for this method will be to retrieve a user account, modify the UserEntry object that contains information about that account, and then submit the modified object to the updateUser method.

To rename the user, update the UserEntry object with the new username and then invoke client.updateUser(String username, UserEntry userEntry) passing the old username as the first parameter. Before renaming a user, it is recommended that you logout the user from all browser sessions and services. For instance, you can get the user on your support desk telephone line during the rename process to ensure they have logged out. The process of renaming can take up to 10 minutes to propagate across all services.

Note: 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 and will not be available as a new username. To remove the nickname, you should call client.deleteUser(String username) after renaming.

Suspending a User Account

To suspend a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

client.suspendUser(String username)

The only argument that you need to pass to the method is the name of the user whose account you wish to suspend.

Restoring a User Account

To restore a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.

client.restoreUser(String username)

The only argument that you need to pass to the method is the name of the user whose account you wish to restore.

Deleting a User Account

To delete a user account using the Java client library, call the following method:

client.deleteUser(String username)

The only argument that you need to pass to the method is the name of the user whose account you wish to delete.

Methods for Nicknames

Creating a Nickname

To create a nickname using the Java client library, call the following method. This method returns a NicknameEntry XML response, which the Java client library converts to a NicknameEntry object.

client.createNickname(String username, String nickname)

This method takes two arguments:

• The username argument identifies the user account for which you are creating a nickname.
• The nickname argument identifies the nickname for the user account.

Retrieving a Nickname

To retrieve information about a nickname using the Java client library, call the following method. This method returns a NicknameEntry XML response, which the Java client library converts to a NicknameEntry object.

client.retrieveNickname(String nickname)

The only argument that you need to pass to the method is the nickname you wish to retrieve.

Retrieving all Nicknames for a User Account

To retrieve all of the nicknames created for a user account, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.

client.retrieveNicknames(String username)

The only argument that you need to pass to the method is the username for which you wish to retrieve nicknames.

Retrieving all Nicknames in a Domain

To retrieve all of the nicknames in a domain, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.

client.retrieveAllNicknames()

Retrieving List of 100 Nicknames

This method allows you to control the size of your result set when you request all of the nicknames in your domain. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 nicknames in your domain, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.

client.retrievePageOfNicknames(String startNickname)

The only argument that you need to pass to the method is the first nickname that should appear in your result set. Nicknames are ordered case-insensitively by ASCII value.

Deleting a Nickname

To delete a nickname using the Java client library, call the following method:

client.deleteNickname(String nickname)

The only argument that you need to pass to the method is the name of the nickname that you wish to delete.

Methods for Groups

The following methods are used to create, retrieve, and update groups. Note that all Group methods are called using the following:

AppsGroupsService groupsService = client.getGroupService(); and then, groupService.anygroupsmethod().

Creating a Group

To create a group using the Java client library, call the following method. This method returns a GroupFeed XML response, which the Java client library converts to an Group object.

groupsService.createGroup(String groupId, String groupName, String groupDescription, String emailPermission)

This method takes four arguments:

• The groupId (required) argument identifies the ID of the new group.
• The groupName (required) argument identifies the name of the group being added.
• The description argument provides a general description of the group.
• The emailPermission argument sets the permissions level of the group.

Note: A newly created group does not have any subscribers. You must call the addMemberToGroup method to add members to a group.

This method, in turn, issues an HTTP POST request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)

Retrieving a Group

To retrieve information about a group using the Java client library, call the following method. This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.

groupsService.retrieveGroup(String groupId)

The only argument that you need to pass to the method is the name of the group that you wish to retrieve.

This method, in turn, issues an HTTP GET request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)

Updating a Group

To update a group, you can call the following method in the Java client library.

This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.

groupsService.updateGroup(String groupId, String groupName, String description, String emailPermission)

This method takes four arguments:

• The groupId (required) argument identifies the ID of the new group.
• The groupName (required) argument identifies the name of the group to which the member is being added.
• The description argument provides a general description of the group.
• The emailPermission argument sets the permissions level of the group.

Retrieving all Groups for a Member

To retrieve all of the groups that a user is a recipient of, you can call the following method in the Java client library.

This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.

groupsService.retrieveGroups(String memberId, Boolean directOnly)

This method takes two arguments:

• The memberId (required) argument identifies the ID of a hosted user for which you want to retrieve group subscriptions.
• If true, directOnly identifies only members with direct association.

This method, in turn, issues an HTTP GET request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)?member=(memberId)[&[directOnly=(true|false)]]

Retrieving all Groups in a Domain

To retrieve all of the groups in a domain, you can call the following method in the Java client library. This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.

groupsService.retrieveAllGroups()

This method, in turn, issues an HTTP GET request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)[?[start=(startKey)]]

Deleting a Group

To delete a group using the Java client library, call the following method. We assume service is an authenticated AppsService object.

groupsService.deleteGroup(String groupId)

The only argument that you need to pass to the method is the name of the group that you wish to delete.

Note: When you delete a group, the Provisioning API will automatically delete all recipients from the group as well.

This method, in turn, issues an HTTP DELETE request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)

Methods for Group Members

Adding a Member to a Group

To add a member (email address) to a group using the Java client library, call the following method. This method returns a MemberEntry XML response, which the Java client library converts to a MemberEntry object.

groupsService.addMemberToGroup(String groupId, String memberName)

This method takes two arguments:

• The groupId argument identifies the group to which the address is being added.
• The memberName argument identifies the name of the member that is being added to a group.

This method, in turn, issues an HTTP POST request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/member

Note: If you add a group as a member of another group, there may be a delay of up to 10 minutes before the child group's members appear as members of the parent group.

Retrieving all Members of a Group

To retrieve a list of all of the subscribers to a group, you can call the following method in the Java client library. This method returns a MemberFeed XML response, which the Java client library converts to a MemberFeed object.

groupsService.retrieveAllMembers(String groupId)

The only argument that you need to pass to the method is the name of the group for which you wish to retrieve a member list.

This method, in turn, issues an HTTP GET request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/member

Deleting a Member from an Group

To delete a member (email address) from a group using the Java client library, call the following method.

groupsService.deleteMemberFromGroup(String groupId, String memberName)

This method takes two arguments:

• The groupId argument identifies the member from which the address is being removed.
• The memberName argument identifies the member that is being removed from a group.

This method, in turn, issues an HTTP DELETE request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/member/(memberId)

Methods for Group Owners

Assigning an Owner to a Group

To assign an owner to a group using the Java client library, call the following method.

groupsService.addOwnerToGroup(String groupId, String ownerName)

This method takes two arguments:

• The groupId argument identifies the group to which the address is being added.
• The ownerName argument identifies the name that is being added to a group as the owner.

This method, in turn, issues an HTTP POST request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/owner

Querying for all Owners of a Group

To query a group to find out who owns the group using the Java client library, call the following method.

client.retrieveGroupOwners(String groupId)

The only argument that you need to pass to the method is the name of the group for which you want to retrieve an owner list.

This method, in turn, issues an HTTP GET request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/owner

Querying if a User or Group is Owner

To query a group to find out if a user or group owns a group using the Java client library, call the following method.

groupsService.isOwner(String groupId, String email)

Deleting an Owner from a Group

To delete an owner from a group using the Java client library, call the following method.

groupsService.removeOwnerFromGroup(String email, String groupId)

This method takes two arguments:

• The email argument identifies the email address that is being removed as the owner of the group.
• The groupId argument identifies the group from which the address is being removed.

Methods for Handling Errors

Identifying Errors in API Responses

The Java client library will throw an AppsForYourDomainException when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log an AppsForYourDomainException, we recommend that you call the getErrorCode method on that object to determine the type of error that the Provisioning API returned. The sample code below demonstrates how you would catch an AppsForYourDomainException in the Provisioning API:

try {
    // Some API actions
} catch (AppsForYourDomainException e) {
    if (e.getErrorCode() == AppsForYourDomainErrorCode.EntityDoesNotExist ) {
        // Do some post-error processing or logging.
    }
}

A complete list of error codes is provided in Appendix D - GData Error Codes.