.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "VUser::Google::Provisioning::V2_0 3pm"
.TH VUser::Google::Provisioning::V2_0 3pm "2021-01-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
VUser::Google::Provisioning::V2_0 \- Support for version 2.0 of the Google Provisioning API
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use VUser::Google::ApiProtocol::V2_0;
\& use VUser::Google::Provisioning::V2_0;
\& 
\& my $google = VUser::Google::ApiProtocol::V2_0\->new(
\&     domain   => \*(Aqexample.com\*(Aq,
\&     admin    => \*(Aqadmin_user\*(Aq,
\&     password => \*(Aqsecret\*(Aq,
\& );
\& 
\& my $api = VUser::Google::Provisioning::V2_0\->new(
\&     google => $google,
\& );
\& 
\& ## Create user
\& my $new_user = $api\->CreateUser(
\&     userName    => \*(Aqfflintstone\*(Aq,
\&     givenName   => \*(AqFred\*(Aq,
\&     familyName  => \*(AqFlintstone\*(Aq,
\&     password    => \*(AqI<3Wilma\*(Aq,
\& );
\& 
\& ## Retrieve a user
\& my $user = $api\->RetrieveUser(\*(Aqfflintstone\*(Aq);
\& 
\& ## Retrieve all userr
\& my @users = $api\->RetrieveAllUsers();
\& 
\& ## Update a user
\& my $updated = $api\->UpdateUser(
\&     userName   => \*(Aqfflintstone\*(Aq,
\&     givenName  => \*(AqFredrock\*(Aq,
\&     familyName => \*(AqFlintStone\*(Aq,
\&     suspended  => 1,
\&     quota      => 2048,
\& );
\& 
\& ## Change password
\& $updated = $api\->ChangePassword(\*(Aqfflintstone\*(Aq, \*(Aqnew\-pass\*(Aq);
\& 
\& $updated = $api\->ChangePassword(
\&     \*(Aqfflintstone\*(Aq,
\&     \*(Aq51eea05d46317fadd5cad6787a8f562be90b4446\*(Aq,
\&     \*(AqSHA\-1\*(Aq,
\& );
\& 
\& $updated = $api\->ChangePassword(
\&     \*(Aqfflintstone\*(Aq,
\&     \*(Aqd27117a019717502efe307d110f5eb3d\*(Aq,
\&     \*(AqMD5\*(Aq,
\& );
\& 
\& ## Delete a user
\& my $rc = $api\->DeleteUser(\*(Aqfflintstone\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
VUser::Google::Provisioning::V2_0 provides support for managing users
using version 2.0 of the Google Provisioning \s-1API.\s0
.PP
In order to use the Google Provisioning \s-1API,\s0 you must turn on \s-1API\s0 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.
.PP
\&\fBNote:\fR It's a good idea to log into the web control panel at least once
as the \s-1API\s0 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 \s-1API.\s0
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
Unless stated otherwise, these methods will \fBdie()\fR if there is an \s-1API\s0 error.
.PP
\fICreateUser\fR
.IX Subsection "CreateUser"
.PP
\&\fBCreateUser()\fR takes a hash of create options and returns a
VUser::Google::Provisioning::UserEntry object if the account
was created. \fBCreateUser()\fR will \fBdie()\fR if there is an error.
.PP
The keys of the hash are:
.IP "userName (required)" 4
.IX Item "userName (required)"
The user name of the account to create
.IP "givenName (required)" 4
.IX Item "givenName (required)"
The user's given name
.IP "familyName (required)" 4
.IX Item "familyName (required)"
The user's family name
.IP "password (required)" 4
.IX Item "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.
.Sp
Google required that passwords be, at least, six characters.
.IP "hashFunctionName" 4
.IX Item "hashFunctionName"
hashFunctionName must be \fI\s-1SHA\-1\s0\fR or \fI\s-1MD5\s0\fR. If this is set,
password is the base16\-encoded password hash.
.IP "quota" 4
.IX Item "quota"
The user's quota in \s-1MB.\s0
.Sp
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.
.IP "changePasswordAtNextLogin" 4
.IX Item "changePasswordAtNextLogin"
If set to a true value, e.g. \f(CW1\fR, 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 \f(CW0\fR.
.IP "admin" 4
.IX Item "admin"
If set to a true value, e.g. \f(CW1\fR, the user will be granted
administrative privileges. A false value, e.g. \f(CW0\fR, admin rights will
be revoked. By default, users will not be granted admin rights.
.PP
\fIRetrieveUser\fR
.IX Subsection "RetrieveUser"
.PP
.Vb 1
\& my $user = $api\->RetrieveUser(\*(Aqfflintstone\*(Aq);
.Ve
.PP
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.
.PP
\fIRetrieveUsers\fR
.IX Subsection "RetrieveUsers"
.PP
.Vb 1
\& my @users = ();
\& 
\& my %results = $api\->RetrieveUsers();
\& @users = @{ $results{entries} };
\& 
\& while ($results{next}) {
\&     %results = $api\->RetrieveUsers($results{next});
\&     push @users, @{ $results{entries} };
\& }
.Ve
.PP
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.
.PP
The returned result is a hash with the following keys:
.IP "entries" 4
.IX Item "entries"
A list reference containing the user accounts. Each entry
is a VUser::Google::Provisioning::UserEntry object.
.IP "next" 4
.IX Item "next"
The user name for the start of the next page. This will be
undefined (\f(CW\*(C`undef\*(C'\fR) if there are no more pages.
.PP
See \fBRetrieveAllUsers()\fR if you want
to fetch all of the accounts at once.
.PP
\fIRetrievePageOfUsers\fR
.IX Subsection "RetrievePageOfUsers"
.PP
This is a synonym for \fBRetrieveUsers()\fR
.PP
\fIRetrieveAllUsers\fR
.IX Subsection "RetrieveAllUsers"
.PP
.Vb 1
\& my @users = $api\->RetrieveAllUsers();
.Ve
.PP
Get a list of all the users for the domain. The entries in the
list are VUser::Google::Provisioning::UserEntry objects.
.PP
\fIUpdateUser\fR
.IX Subsection "UpdateUser"
.PP
.Vb 5
\& my $updated = $api\->UpdateUser(
\&     userName  => \*(Aqfflintstone\*(Aq,
\&     givenName => \*(AqFred\*(Aq,
\&     # ... other options
\& );
.Ve
.PP
Updates an account. UpdateUser takes the same options as \fBCreateUser()\fR but
only userName is required.
.PP
\&\fBUpdateUser()\fR cannot be used to rename an account. See \fBRenameUser()\fR.
.PP
\fIRenameUser\fR
.IX Subsection "RenameUser"
.PP
.Vb 1
\& my $user_user = $api\->RenameUser($oldname, $newname);
.Ve
.PP
Rename an account. The first parameter is the old user name; the
second is the new user name. \fBRenameUser()\fR will die if the old name
does not exist.
.PP
\fIDeleteUser\fR
.IX Subsection "DeleteUser"
.PP
.Vb 1
\& my $rc = $api\->DeleteUser(\*(Aqfflintstone\*(Aq);
.Ve
.PP
Deletes a given user. Returns true if the delete succeded and dies
if there was an error.
.PP
\fIChangePassword\fR
.IX Subsection "ChangePassword"
.PP
.Vb 1
\& $updated = $api\->ChangePassword(\*(Aqfflintstone\*(Aq, \*(Aqnew\-pass\*(Aq);
\& 
\& $updated = $api\->ChangePassword(
\&     \*(Aqfflintstone\*(Aq,
\&     \*(Aq51eea05d46317fadd5cad6787a8f562be90b4446\*(Aq,
\&     \*(AqSHA\-1\*(Aq,
\& );
\& 
\& $updated = $api\->ChangePassword(
\&     \*(Aqfflintstone\*(Aq,
\&     \*(Aqd27117a019717502efe307d110f5eb3d\*(Aq,
\&     \*(AqMD5\*(Aq,
\& );
.Ve
.PP
Change a users password.
.PP
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.
.PP
Accepted values for the has function name are \fI\s-1MD5\s0\fR and \fI\s-1SHA\-1\s0\fR.
.PP
There is no difference between using this and using UpdateUser to change
the user's password.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
VUser::Google::Provisioning
.IP "\(bu" 4
VUser::Google::ApiProtocol::V2_0
.IP "\(bu" 4
VUser::Google::EmailSettings::V2_0
.IP "\(bu" 4
http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_developers_protocol.html
.Sp
item *
.Sp
http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html
.SH "BUGS"
.IX Header "BUGS"
Bugs may be reported at http://code.google.com/p/vuser/issues/list.
.SH "AUTHOR"
.IX Header "AUTHOR"
Randy Smith <perlstalker@vuser.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2009  Randall Smith
.PP
This program is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0  02110\-1301, \s-1USA.\s0