Provided by: libvuser-google-api-perl_1.0.1-1_all bug

NAME

       VUser::Google::Provisioning::V2_0 - Support for version 2.0 of the Google Provisioning API

SYNOPSIS

        use VUser::Google::ApiProtocol::V2_0;
        use VUser::Google::Provisioning::V2_0;

        my $google = VUser::Google::ApiProtocol::V2_0->new(
            domain   => 'example.com',
            admin    => 'admin_user',
            password => 'secret',
        );

        my $api = VUser::Google::Provisioning::V2_0->new(
            google => $google,
        );

        ## Create user
        my $new_user = $api->CreateUser(
            userName    => 'fflintstone',
            givenName   => 'Fred',
            familyName  => 'Flintstone',
            password    => 'I<3Wilma',
        );

        ## Retrieve a user
        my $user = $api->RetrieveUser('fflintstone');

        ## Retrieve all userr
        my @users = $api->RetrieveAllUsers();

        ## Update a user
        my $updated = $api->UpdateUser(
            userName   => 'fflintstone',
            givenName  => 'Fredrock',
            familyName => 'FlintStone',
            suspended  => 1,
            quota      => 2048,
        );

        ## Change password
        $updated = $api->ChangePassword('fflintstone', 'new-pass');

        $updated = $api->ChangePassword(
            'fflintstone',
            '51eea05d46317fadd5cad6787a8f562be90b4446',
            'SHA-1',
        );

        $updated = $api->ChangePassword(
            'fflintstone',
            'd27117a019717502efe307d110f5eb3d',
            'MD5',
        );

        ## Delete a user
        my $rc = $api->DeleteUser('fflintstone');

DESCRIPTION

       VUser::Google::Provisioning::V2_0 provides support for managing users using version 2.0 of
       the Google Provisioning API.

       In order to use the Google Provisioning API, you must turn on API support from the Google
       Apps for Your Domain control panel. The user that is used to create the
       VUser::Google::ApiProtocol object must have administrative privileges on the domain.

       Note: It's a good idea to log into the web control panel at least once as the API user in
       order to accept the the terms of service and admin terms.  If you don't, you'll get
       intermittent authentication errors when trying to use the API.

   METHODS
       Unless stated otherwise, these methods will die() if there is an API error.

       CreateUser

       CreateUser() takes a hash of create options and returns a
       VUser::Google::Provisioning::UserEntry object if the account was created. CreateUser()
       will die() if there is an error.

       The keys of the hash are:

       userName (required)
           The user name of the account to create

       givenName (required)
           The user's given name

       familyName (required)
           The user's family name

       password (required)
           The user's password. If hashFunctionName is also set, this is the base16-encoded hash
           of the password. Otherwise, this is the user's plaintext password.

           Google required that passwords be, at least, six characters.

       hashFunctionName
           hashFunctionName must be SHA-1 or MD5. If this is set, password is the base16-encoded
           password hash.

       quota
           The user's quota in MB.

           Not all domains will be allowed to set users' quotas. If that's the case, creation
           will still succeed but the quota will be set to the default for your domain.

       changePasswordAtNextLogin
           If set to a true value, e.g. 1, the user will be required to change their password the
           next time they login in. This is the default.  You may turn this off by setting
           changePasswordAtNextLogin to 0.

       admin
           If set to a true value, e.g. 1, the user will be granted administrative privileges. A
           false value, e.g. 0, admin rights will be revoked. By default, users will not be
           granted admin rights.

       RetrieveUser

        my $user = $api->RetrieveUser('fflintstone');

       Retrieves a specified user by the user name. RetieveUser will return a
       VUser::Google::Provisioning::UserEntry if the user exists and undef if it doesn't.

       RetrieveUsers

        my @users = ();

        my %results = $api->RetrieveUsers();
        @users = @{ $results{entries} };

        while ($results{next}) {
            %results = $api->RetrieveUsers($results{next});
            push @users, @{ $results{entries} };
        }

       Fetches one page of users starting at a given user name. Currently, a page is defined as
       100 users. This is useful if you plan on paginating the results yourself or if you have a
       very large number of users.

       The returned result is a hash with the following keys:

       entries
           A list reference containing the user accounts. Each entry is a
           VUser::Google::Provisioning::UserEntry object.

       next
           The user name for the start of the next page. This will be undefined ("undef") if
           there are no more pages.

       See RetrieveAllUsers() if you want to fetch all of the accounts at once.

       RetrievePageOfUsers

       This is a synonym for RetrieveUsers()

       RetrieveAllUsers

        my @users = $api->RetrieveAllUsers();

       Get a list of all the users for the domain. The entries in the list are
       VUser::Google::Provisioning::UserEntry objects.

       UpdateUser

        my $updated = $api->UpdateUser(
            userName  => 'fflintstone',
            givenName => 'Fred',
            # ... other options
        );

       Updates an account. UpdateUser takes the same options as CreateUser() but only userName is
       required.

       UpdateUser() cannot be used to rename an account. See RenameUser().

       RenameUser

        my $user_user = $api->RenameUser($oldname, $newname);

       Rename an account. The first parameter is the old user name; the second is the new user
       name. RenameUser() will die if the old name does not exist.

       DeleteUser

        my $rc = $api->DeleteUser('fflintstone');

       Deletes a given user. Returns true if the delete succeded and dies if there was an error.

       ChangePassword

        $updated = $api->ChangePassword('fflintstone', 'new-pass');

        $updated = $api->ChangePassword(
            'fflintstone',
            '51eea05d46317fadd5cad6787a8f562be90b4446',
            'SHA-1',
        );

        $updated = $api->ChangePassword(
            'fflintstone',
            'd27117a019717502efe307d110f5eb3d',
            'MD5',
        );

       Change a users password.

       ChangePassword takes the user name, password and, optionally, a hash function name. If the
       hash function name is set, the password, is the base16-encoded password, otherwise it is
       the clear text password.

       Accepted values for the has function name are MD5 and SHA-1.

       There is no difference between using this and using UpdateUser to change the user's
       password.

SEE ALSO

       •   VUser::Google::Provisioning

       •   VUser::Google::ApiProtocol::V2_0

       •   VUser::Google::EmailSettings::V2_0

       •   http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_developers_protocol.html

           item *

           http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html

BUGS

       Bugs may be reported at http://code.google.com/p/vuser/issues/list.

AUTHOR

       Randy Smith <perlstalker@vuser.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2009  Randall Smith

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
       Boston, MA  02110-1301, USA.