.\" 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::V1_0 3pm"
.TH VUser::Google::ProvisioningAPI::V1_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::V1_0 \- Perl module that implements version 1.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,$password);
\&
\&  $google\->CreateAccount($userName, $firstName, $lastName, $password);
\&  $google\->RetrieveAccount($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"
For a complete description of the meaning of the following methods, see the Google \s-1API\s0 documentation referenced in the \s-1SEE ALSO\s0 section.
.PP
.Vb 2
\&        #create the object
\&        $google = new Google:ProvisioningAPI($domain,$admin,$password) || die "Cannot create google object";
\&        
\&        print \*(AqModule version: \*(Aq . $google\->VERSION . "\enAPI Version: " . $google\->version() . "\en";
\&        
\&        #create a hosted account
\&        if( $google\->CreateAccount( $userName, $firstName, $lastName, $password ) ) 
\&        {
\&                print "Account created!\eN";
\&        }
\&        
\&        #add email services to the account
\&        $google\->UpdateAccountEmail($userName);
\&        
\&        #retrieving account data
\&        if($google\->RetrieveAccount($userName))
\&        {
\&                print \*(AqUsername: \*(Aq . $google\->{result}\->{RetrievalSection}\->{userName} . "\en";
\&                print \*(AqfirstName: \*(Aq . $google\->{result}\->{RetrievalSection}\->{firstName} . "\en";
\&                print \*(AqlastName: \*(Aq . $google\->{result}\->{RetrievalSection}\->{lastName} . "\en";
\&                print \*(AqaccountStatus: \*(Aq . $google\->{result}\->{RetrievalSection}\->{accountStatus} . "\en";
\&                
\&        }
\&        
\&        #see what the result hash after a request looks like
\&        use Data::Dumper;
\&        print Dumper($google\->{result});
\&        
\&        #delete an account
\&        $ret = DeleteAccount($userName);
\&        
\&        #accessing the HTML data as it was received from the Google servers:
\&        print $google\->replyheaders();
\&        print $google\->replycontent();
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
new ( \f(CW$domain\fR, \f(CW$admin\fR, \f(CW$adminpassword\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.
When a request is properly handled by Google's \s-1API\s0 engine, the webpost to the \s-1API\s0 succeeds. This results in a valid page being returned. The content of this page then defines whether the request succeeded or not.
All pages returing the 'Success(2000)' status code will result in the \s-1API\s0 method succeeding, and returning a 1. All failures return 0.
Please see the section below on how to access the result data, and how to determine the reasons for errors.
.PP
If the web post fails (as determined by the \f(CW\*(C`HTTP::Request\*(C'\fR method \fBIsSuccess()\fR ), the method returns 0, and the {reason} hash is set to a descriptive error.
You can then examine the raw data to get an idea of what went wrong.
.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
.SS "Methods to Create/Retrieve/Delete"
.IX Subsection "Methods to Create/Retrieve/Delete"
\fI'Hosted account' methods\fR
.IX Subsection "'Hosted account' methods"
.PP
CreateAccountEmail(  \f(CW$userName\fR, \f(CW$firstName\fR, \f(CW$lastName\fR, \f(CW$password\fR, \f(CW$quota\fR )
.Sp
.RS 4
Creates a hosted account with email services in your domains name space.
The first 4 arguments are required. The \f(CW$quota\fR argument is optional. If \f(CW$quota\fR is given, the <quota> tag will be sent with the request, otherwize is will be omitted.
See the Google \s-1API\s0 docs for the \s-1API\s0 call for more details.
.RE
.PP
CreateAccount(  \f(CW$userName\fR, \f(CW$firstName\fR, \f(CW$lastName\fR, \f(CW$password\fR )
.Sp
.RS 4
Creates a hosted account in your domains name space. This account does \s-1NOT\s0 have email services by default.
You need to call \fBUpdateAccountEmail()\fR to add email services.
\&\s-1NOTE:\s0 this \s-1API\s0 call may be discontinued! See \fBCreateAccountEmail()\fR for a replacement.
.RE
.PP
UpdateAccount( \f(CW$username\fR, \f(CW$firstName\fR, \f(CW$lastName\fR, \f(CW$password\fR )
.Sp
.RS 4
\&\f(CW$username\fR is the mandatory name of the hosted account. The remaining paramaters are optional, and can be set to 'undef' if you do not wish to change them
Eg. to change the password on an account, call this as;
.RE
.PP
.Vb 1
\&        UpdateAccount( $username, undef, undef, \*(Aqnewpassword\*(Aq );
.Ve
.Sp
.RS 4
to change names only, you would call it as such:
.RE
.PP
.Vb 1
\&        UpdateAccount( $username, \*(Aqnewfirstname\*(Aq, \*(Aqnewlastname\*(Aq, undef );
.Ve
.PP
UpdateAccountEmail( \f(CW$userName\fR )
.Sp
.RS 4
Adds email services to a hosted account created with \fBCreateAccount()\fR.
\&\s-1NOTE:\s0 this \s-1API\s0 call may be discontinued! See \fBCreateAccountEmail()\fR for a replacement.
.RE
.PP
UpdateAccountStatus( \f(CW$userName\fR, \f(CW$status\fR )
.Sp
.RS 4
\&\f(CW$status\fR is either 'locked' or 'unlocked'
.RE
.PP
RetrieveAccount( \f(CW$userName\fR )
.PP
DeleteAccount( \f(CW$userName\fR )
.PP
RenameAccount( \f(CW$oldName\fR, \f(CW$newName\fR, \f(CW$alias\fR )
.Sp
.RS 4
\&\f(CW$alias\fR is either '1' or '0'
.Sp
\&\s-1WARNING:\s0 this method is derived from the Python sample code provided by Google:
(Ie. this may not work yet)
"Username change. Note that this feature must be explicitly enabled by the domain administrator, and is not enabled by default.
Args:
.Sp
.RS 4
oldname: user to rename
newname: new username to set for the user
alias: if 1, create an alias of oldname for newname"
.RE
.RE
.RS 4
.RE
.PP
\fI'Alias' methods\fR
.IX Subsection "'Alias' methods"
.PP
CreateAlias( \f(CW$userName\fR, \f(CW$alias\fR )
.PP
RetrieveAlias( \f(CW$userName\fR );
.PP
DeleteAlias( \f(CW$alias\fR );
.PP
\fI'Mailing List' methods\fR
.IX Subsection "'Mailing List' methods"
.PP
CreateMailingList( \f(CW$mailingListName\fR )
.PP
UpdateMailingList( \f(CW$mailingListName\fR, \f(CW$userName\fR, \f(CW$listOperation\fR )
.Sp
.RS 4
\&\f(CW$listOperation\fR is either 'add' or 'remove'
.RE
.PP
RetrieveMailingList( \f(CW$mailingListName\fR )
.PP
DeleteMailingList( \f(CW$mailingListName\fR )
.SS "Methods to set/get variables"
.IX Subsection "Methods to set/get variables"
After creating the object you can get/set the administrator account and set the password with these methods.
Note this will cause a re-authentication next time a Google \s-1API\s0 method is called.
.PP
admin( \f(CW$admin\fR )
.Sp
.RS 4
set the administrative user, and will return administator username.
.RE
.PP
password( \f(CW$string\fR )
.Sp
.RS 4
set the password, returns an empty string
.RE
.SS "Miscelleaneous statistics methods"
.IX Subsection "Miscelleaneous statistics methods"
There are a few methods to access some statistics data that is collected while the object performing Google \s-1API\s0 calls.
.PP
\&\fBauthtime()\fR
.Sp
.RS 4
returns the time of last authentication, as generated by the \fBtime()\fR function
.RE
.PP
\&\fBctime()\fR
.Sp
.RS 4
returns the create time of the object, as generated by the \fBtime()\fR function
.RE
.PP
\&\fBrtime()\fR
.Sp
.RS 4
returns the time of the most recent request, as generated by the \fBtime()\fR function
.RE
.PP
\&\fBlogins()\fR
.Sp
.RS 4
returns the number of \s-1API\s0 logins that have been performed
.RE
.PP
\&\fBrequests()\fR
.Sp
.RS 4
returns the numbers of \s-1API\s0 requests that have been submitted to Google
.RE
.PP
\&\fBsuccess()\fR
.Sp
.RS 4
returns the numbers of successful api request performed
.RE
.PP
And finally,
.PP
\&\fBversion()\fR
.Sp
.RS 4
returns a string with the api version implemented. This is currently '1.0'
.RE
.SH "ACCESSING RESULTING DATA"
.IX Header "ACCESSING RESULTING DATA"
Valid return data from Google is parsed into a hash named 'result', available through the object. In this hash you can find all elements as returned by Google.
This hash is produced by XML::Simple. See the Google \s-1API\s0 documentation in the \s-1SEE ALSO\s0 section for complete details.
Some of the more useful elements you may need to look at are:
.PP
.Vb 4
\&        $google\->{result}\->{reason}             #this typically has the textual reason for a failure
\&        $google\->{result}\->{extendedMessage}    #a more extensive description of the failure reason may be here
\&        $google\->{result}\->{result}             #typically empty!
\&        $google\->{result}\->{type}               #should be same of query type, eg \*(AqAccount\*(Aq, \*(AqAlias\*(Aq, \*(AqMailingList\*(Aq
.Ve
.PP
The retrieval section contains data when you are querying. Here is what this section looks like when you call the RetrieveAccount method:
.PP
.Vb 5
\&        $google\->{result}\->{RetrievalSection}\->{firstName}
\&        $google\->{result}\->{RetrievalSection}\->{lastName}
\&        $google\->{result}\->{RetrievalSection}\->{accountStatus}
\&        $google\->{result}\->{RetrievalSection}\->{aliases}\->{alias}
\&        $google\->{result}\->{RetrievalSection}\->{emailLists}\->{emailList}
.Ve
.PP
To see the structure of the result hash, use the Data::Dumper module as such:
.PP
.Vb 2
\&        use Data::Dumper;
\&        print Dumper($google\->{result});
.Ve
.SH "ACCESSING RAW GOOGLE POST AND RESULT DATA"
.IX Header "ACCESSING RAW GOOGLE POST AND RESULT DATA"
The data from the most recent post to the Google servers is available. You can access it as:
.PP
.Vb 1
\&        print $google\->requestcontent();
.Ve
.PP
The most recent received \s-1HTML\s0 data is stored in two parts, the headers and the content. Both are strings. They can be accessed as such:
.PP
.Vb 2
\&        print $google\->replyheaders();
\&        print $google\->replycontent();
.Ve
.PP
Note the headers are new-line separated and can easily be parsed:
.PP
.Vb 4
\&        foreach my $headerline ( split/\en/, $g\->replyheaders() )
\&        {
\&                my ($header, $value) = split/:/, $headerline;
\&        }
.Ve
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The official Google documentation can be found at
http://code.google.com/apis/apps\-for\-your\-domain/google_apps_provisioning_api_v1.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
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Johan Reinalda, johan at reinalda dot net
.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.