.\" 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::ProvisioningAPI::V2_0 3pm"
.TH VUser::Google::ProvisioningAPI::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::ProvisioningAPI::V2_0 \- Perl module that implements version 2.0 of the Google Apps for Your Domain Provisioning API
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use VUser::Google::ProvisioningAPI;
\& my $google = new VUser::Google::ProvisioningAPI($domain, $admin, $passwd, \*(Aq2.0\*(Aq);
\& 
\& $google\->CreateUser($userName, $givenName, $familyName, $password, $quotaMB);
\& my $user = $google\->RetrieveUser($userName);
.Ve
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
VUser::Google::ProvisioningAPI requires the following modules to be installed:
.IP "\(bu" 4
\&\f(CW\*(C`LWP::UserAgent\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`HTTP::Request\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`Encode\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`XML::Simple\*(C'\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
VUser::Google::ProvisioningAPI provides a simple interface to the Google Apps for Your Domain Provisioning \s-1API.\s0
It uses the \f(CW\*(C`LWP::UserAgent\*(C'\fR module for the \s-1HTTP\s0 transport, and the \f(CW\*(C`HTTP::Request\*(C'\fR module for the \s-1HTTP\s0 request and response.
.SS "Examples"
.IX Subsection "Examples"
Adding a user:
.PP
.Vb 5
\& use VUser::Google::ProvisioningAPI;
\& my $google = VUser::Google::ProvisioningAPI\->new(\*(Aqyourdomain.com\*(Aq,
\&                                          \*(Aqadmin\*(Aq,
\&                                          \*(Aqyour password\*(Aq,
\&                                          \*(Aq2.0\*(Aq);
\&
\& my $entry = $google\->CreateUser(\*(Aqjoeb\*(Aq, \*(AqJoe\*(Aq, \*(AqBlow\*(Aq, \*(Aqjoespassword\*(Aq);
\& if (defined $entry) {
\&   print $entry\->User, " created\en";
\& } else {
\&   die "Add failed: ".$google\->{result}{reason};
\& }
.Ve
.PP
Updating a user:
.PP
.Vb 4
\& my $new_entry = VUser::Google::ProvisioningAPI::V2_0::UserEntry\->new();
\& $new_entry\->Password(\*(Aqheresmynewpassword\*(Aq);
\& $new_entry\->GivenName(\*(AqJoseph\*(Aq);
\& my $entry = $google\->UpdateUser(\*(Aqjoeb\*(Aq, $new_entry);
.Ve
.PP
Delete a user:
.PP
.Vb 4
\& my $rc = $google\->DeleteUser(\*(Aqjoeb\*(Aq);
\& if (not $rc) {
\&   die "Can\*(Aqt delete user: ".$google\->{result}{reason};
\& }
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
new ($domain, \f(CW$admin\fR, \f(CW$adminpasswd\fR)
.PP
This is the constructor for a new VUser::Google::ProvisioningAPI object.
\&\f(CW$domain\fR is the domain name registered with Google Apps For Your Domain,
\&\f(CW$admin\fR is an account in the above domain that has the right to manage that domain, and
\&\f(CW$adminpassword\fR is the password for that account.
.PP
Note that the constructor will \s-1NOT\s0 attempt to perform the 'ClientLogin' call to the Google Provisioning \s-1API\s0 (see below).
Authentication happens automatically when the first \s-1API\s0 call is performed. The token will be remembered for the duration of the object, and will be automatically refreshed as needed.
If you want to verify that you can get a valid token before performing any operations, follow the constructor with a call to \fBIsAuthenticated()\fR as such:
.PP
.Vb 1
\&        print "Authentication OK\en" unless not $google\->IsAuthenticated();
.Ve
.SH "METHODS"
.IX Header "METHODS"
Below are all the methods available on the object. For the Google \s-1API\s0 specific methods, see the Google \s-1API\s0 documentation for more details.
.PP
When a request is properly handed by Google's \s-1API\s0 engine, the results of the
action are returned as the content of the request.
.PP
If the request fails (as determined by the \f(CW\*(C`HTTP::Request\*(C'\fR method
\&\fBis_success()\fR), it could mean a couple of things. If it's a failure within
the Google \s-1API,\s0 the content will contain an \s-1XML\s0 encoded error message. All
other \s-1HTTP\s0 errors are still possible.
.SS "Checking Authentication"
.IX Subsection "Checking Authentication"
\&\fBIsAuthenticated()\fR
.Sp
.RS 4
will check if the object has been able to authenticate with Google's api engine, and get an authentication ticket.
Returns 1 if successful, 0 on failure. To see why it may fail, see the $@ variable, and the \f(CW$google\fR\->{results}\->{reason} hash, and parse the returned page (see the 'content' and 'header' variables.)
.RE
.PP
\&\fBRelogin()\fR
.Sp
.RS 4
Performs a login if required. \fBRelogin()\fR will be called but the \s-1API\s0 methods
and \fBIsAuthenticated()\fR. You should not need to call this directly.
.RE
.SS "User Methods"
.IX Subsection "User Methods"
These are the acutual \s-1API\s0 calls. These calls match up with the client
library methods described for the .Net and Java libraries.
.PP
CreateUser($userName, \f(CW$givenName\fR, \f(CW$familyName\fR, \f(CW$password\fR, \f(CW$quota\fR, \f(CW$forceChange\fR, \f(CW$hashName\fR)
.Sp
.RS 4
Creates a user in your Google Apps domain. The first four arguments are
required. The \f(CW$quota\fR argument is optional and may not do anything unless
your agreement with Google allows you to change quotas.
.Sp
If \f(CW$forceChange\fR is true, the user will be required to change their
password after log in.
.Sp
\&\f(CW$hashName\fR, if set, must be \fIsha\-1\fR or \fImd5\fR.
.Sp
\&\fBCreateUser()\fR returns a \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::UserEntry\*(C'\fR object if
the request was successful and \f(CW\*(C`undef\*(C'\fR otherwise.
.RE
.PP
RetrieveUser($userName)
.Sp
.RS 4
Get the passed user from Google. Returns a
\&\f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::UserEntry\*(C'\fR object.
.RE
.PP
\&\fBRetrieveAllUsers()\fR
.Sp
.RS 4
Returns a list of all users in your domain. The entries are
\&\f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::UserEntry\*(C'\fR objects.
.RE
.PP
RetrievePageOfUsers($startUser)
.Sp
.RS 4
Google Provisioning \s-1API 2.0\s0 supports returning lists of users 100 at a time.
\&\f(CW$startUser\fR is optional. When used, it will be the list will start at
that user. Otherwise, it will return the first 100 users.
.Sp
\&\fBRetrievePageOfUsers()\fR returns a list of
\&\f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::UserEntry\*(C'\fR objects.
.RE
.PP
UpdateUser($userName, \f(CW$newUserEntry\fR)
.Sp
.RS 4
\&\f(CW$userName\fR is the mandatory name of the user account. \f(CW$newUserEntry\fR is a
\&\f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::UserEntry\*(C'\fR object with the changes to the
account. You only need to set the elements of \f(CW$newUserEntry\fR that are being
changed. \fBNote:\fR According to the Google \s-1API\s0 docs, you should not set the
password unless you are actually changing the password.
.RE
.PP
SuspendUser($userName)
.Sp
.RS 4
\&\f(CW$userName\fR is the name of the user that you want to suspend.
.Sp
Returns a \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::UserEntry\*(C'\fR object if successful.
.RE
.PP
RestoreUser($userName)
.Sp
.RS 4
Unsuspend the user's account. \f(CW$userName\fR is required.
.Sp
Returns a \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::UserEntry\*(C'\fR object if successful.
.RE
.PP
DeleteUser($userName)
.Sp
.RS 4
\&\f(CW$userName\fR is the required user name to delete.
.Sp
Returns '1' on success.
.RE
.PP
\fINickname methods\fR
.IX Subsection "Nickname methods"
.PP
CreateNickname($userName, \f(CW$nickName\fR)
.Sp
.RS 4
Creates a nickname (or alias) for a user. \f(CW$userName\fR is the existing user
and \f(CW$nickName\fR is the user's new nickname.
.Sp
Returns a \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::NicknameEntry\*(C'\fR object on success.
.RE
.PP
RetrieveNickname($nickName)
.Sp
.RS 4
Returns a \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::NicknameEntry\*(C'\fR if the \f(CW$nickName\fR
exists.
.RE
.PP
RetrieveNicknames($userName)
.Sp
.RS 4
Get all nicknames for \f(CW$userName\fR.
.Sp
Returns a list of \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::NicknameEntry\*(C'\fR objects.
.RE
.PP
\&\fBRetrieveAllNicknames()\fR
.Sp
.RS 4
Get all of the nick names for your domain.
.Sp
Returns a list of \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::NicknameEntry\*(C'\fR objects.
.RE
.PP
RetrievePageOfNicknames($startNick)
.Sp
.RS 4
Get 100 of the nick names for your domain. If \f(CW$startNick\fR is defined,
the list will start with that nick name, otherwise, the first 100 nicks
will be returned.
.Sp
Returns a list of \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::NicknameEntry\*(C'\fR objects.
.RE
.PP
DeleteNickname($nickName)
.Sp
.RS 4
Delete \f(CW$nickName\fR from your domain. Returns 1 if the request succeeds.
.RE
.PP
\fIEmail list methods\fR
.IX Subsection "Email list methods"
.PP
CreateEmailList($listName)
.Sp
.RS 4
Create an email list named \f(CW$listName\fR.
.Sp
Returns a \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::EmailListEntry\*(C'\fR on success.
.RE
.PP
RetrieveEmailLists($recipient)
.Sp
.RS 4
Get a list of all local email lists that \f(CW$recipient\fR is subscribed to.
\&\f(CW$recipient\fR is limited to users at your domain.
.Sp
Returns a list of \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::EmailListEntry\*(C'\fR objects.
.RE
.PP
\&\fBRetrieveAllEmailLists()\fR
.Sp
.RS 4
Get a list of all email lists for your domain.
.Sp
Returns a list of \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::EmailListEntry\*(C'\fR objects.
.RE
.PP
RetrievePageOfEmailLists($startList)
.Sp
.RS 4
Get a single page (100 lists) of email lists.
.RE
.PP
DeleteEmailList($emailList)
.Sp
.RS 4
Delete \f(CW$emailList\fR from your domain.
.Sp
Returns 1 on success.
.RE
.PP
AddRecipientToEmailList($recipient, \f(CW$emailList\fR)
.Sp
.RS 4
Adds a recipient to a mail list. \f(CW$recipient\fR is the address you want to
add and \f(CW$emailList\fR is the list to add to.
.Sp
Returns a \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry\*(C'\fR object on
success.
.RE
.PP
RetrieveAllRecipients($emailList)
.Sp
.RS 4
Get a list of the recipients of the specified email list.
.Sp
Returns a list of \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry\*(C'\fR objects.
.RE
.PP
RetrievePageOfRecipients($emailList, \f(CW$startRecpt\fR)
.Sp
.RS 4
Get a page of recipients for that given list (\f(CW\*(C`$emailList)\*(C'\fR starting with
\&\f(CW$startRecpt\fR or the beginning if \f(CW$startRecpt\fR is not defined.
.Sp
Returns a list of \f(CW\*(C`VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry\*(C'\fR objects.
.RE
.PP
RemoveRecipientFromEmailList($recipient, \f(CW$emailList\fR)
.Sp
.RS 4
Remove \f(CW$recipient\fR from the given email list (\f(CW$emailList\fR).
.Sp
Returns 1 in success.
.RE
.SH "ACCESSING RESULTING DATA"
.IX Header "ACCESSING RESULTING DATA"
Most \s-1API\s0 calls return an object so that you don't have to screw around with the
\&\s-1XML\s0 data. The parsed \s-1XML\s0 (by XML::Simple) is available in \f(CW\*(C`$google\-\*(C'\fR{result}>.
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The perldocs for VUser::Google::ProvisioningAPI::V2_0::UserEntry;
VUser::Google::ProvisioningAPI::V2_0::NicknameEntry;
VUser::Google::ProvisioningAPI::V2_0::EmailListEntry;
and VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry.
.PP
The official Google documentation can be found at
http://code.google.com/apis/apps\-for\-your\-domain/google_apps_provisioning_api_v2.0_reference.html
.PP
http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html
.PP
For support, see the Google Group at
http://groups.google.com/group/apps\-for\-your\-domain\-apis
.PP
For additional support specific to this modules, email me at johan at reinalda dot net.
.SH "AUTHOR"
.IX Header "AUTHOR"
Johan Reinalda, johan at reinalda dot net
Randy Smith, perlstalker at vuser dot org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Johan Reinalda, johan at reinalda dot net
Copyright (C) 2007 by Randy Smith, perlstalker at vuser dot org
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.5 or,
at your option, any later version of Perl 5 you may have available.
.PP
If you make useful modification, kindly consider emailing then to me for inclusion in a future version of this module.