VUser:...::V1_0(3pm)

💖 VUser::Google::ProvisioningAPI::V1_0 💖

okay bestie, sit down, hydrate, because we're about to talk about a Perl module — and the manual name on this one is VUser::Google::ProvisioningAPI::V1_0, shipped as user-contributed Perl documentation in the 3pm section. It's giving very specific, very useful, very 2000s-Google-API energy. Let's go. ✨

---

🌸 NAME 🌸

VUser::Google::ProvisioningAPI::V1_0 — a Perl module that implements version 1.0 of the Google Apps for Your Domain Provisioning API. no cap, that's literally the whole job. 💅

---

🦋 SYNOPSIS 🦋

here's the vibe in code form:

use VUser::Google::ProvisioningAPI;
my $google = new VUser::Google::ProvisioningAPI($domain,$admin,$password);

$google->CreateAccount($userName, $firstName, $lastName, $password);
$google->RetrieveAccount($userName);

so you make the object, then you start bossing Google around. iconic behavior. 👑

---

🎀 REQUIREMENTS 🎀

VUser::Google::ProvisioningAPI needs these modules installed first, bestie, don't skip this part:

• "LWP::UserAgent"
• "HTTP::Request"
• "Encode"
• "XML::Simple"

four little guys. that's the whole squad. 🫶

---

✨ DESCRIPTION ✨

VUser::Google::ProvisioningAPI gives you a simple interface to the Google Apps for Your Domain Provisioning API. For the HTTP transport it uses the "LWP::UserAgent" module, and for the HTTP request and response it uses the "HTTP::Request" module. that's the whole architecture. it's giving minimal. it's giving focused. it's giving slay. 💖

💫 Examples 💫

so for a complete description of what all the following methods actually mean, go read the Google API documentation linked down in SEE ALSO, okay? but here's the whole flow in one code block:

#create the object
$google = new Google:ProvisioningAPI($domain,$admin,$password) || die "Cannot create google object";

print 'Module version: ' . $google->VERSION . "\nAPI Version: " . $google->version() . "\n";

#create a hosted account
if( $google->CreateAccount( $userName, $firstName, $lastName, $password ) )
{
    print "Account created!\N";
}

#add email services to the account
$google->UpdateAccountEmail($userName);

#retrieving account data
if($google->RetrieveAccount($userName))
{
    print 'Username: ' . $google->{result}->{RetrievalSection}->{userName} . "\n";
    print 'firstName: ' . $google->{result}->{RetrievalSection}->{firstName} . "\n";
    print 'lastName: ' . $google->{result}->{RetrievalSection}->{lastName} . "\n";
    print 'accountStatus: ' . $google->{result}->{RetrievalSection}->{accountStatus} . "\n";

}

#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();

okay the Dumper bit? that's your bestie move, fr fr — peek at the hash instead of guessing. 🌈

---

👑 CONSTRUCTOR 👑

new ( $domain, $admin, $adminpassword )

this is the constructor for a new VUser::Google::ProvisioningAPI object. here's who's who:

• $domain — the domain name registered with Google Apps For Your Domain
• $admin — an account in the above domain that has the right to manage that domain
• $adminpassword — the password for that account

now listen, important detail: the constructor will NOT attempt to perform the 'ClientLogin' call to the Google Provisioning API (see below, bestie, keep reading). authentication happens automatically when the first API call is performed. the token gets remembered for the duration of the object, and it will be automatically refreshed as needed. so chill. 🧚

but if you do want to verify you can get a valid token before performing any operations? follow the constructor with a call to IsAuthenticated() like this:

print "Authentication OK\n" unless not $google->IsAuthenticated();

lowkey elegant. highkey useful. 💜

---

⭐ METHODS ⭐

below are all the methods available on the object. for the Google API specific methods, check the Google API documentation for more details. here's the tea on how responses work, and this part matters:

when a request is properly handled by Google's API engine, the webpost to the API succeeds. this results in a valid page being returned. the content of this page then defines whether the request succeeded or not. all pages returning the 'Success(2000)' status code will result in the API 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. 💀

and if the web post fails (as determined by the "HTTP::Request" method IsSuccess() ), 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. no guessing required, the data is right there. 🔍

🔐 Checking Authentication 🔐

IsAuthenticated()

• 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.

and to see why it may fail? look at the $@ variable, and the $google->{results}->{reason} hash, and parse the returned page (see the 'content' and 'header' variables.) three places to look. she's thorough. 💅

🌸 Methods to Create/Retrieve/Delete 🌸

'Hosted account' methods

CreateAccountEmail( $userName, $firstName, $lastName, $password, $quota )

• Creates a hosted account with email services in your domains name space.
• The first 4 arguments are required. The $quota argument is optional.
• If $quota is given, the <quota> tag will be sent with the request, otherwize is will be omitted.
• See the Google API docs for the API call for more details.

CreateAccount( $userName, $firstName, $lastName, $password )

• Creates a hosted account in your domains name space.
• This account does NOT have email services by default. You need to call UpdateAccountEmail() to add email services.
• > NOTE: this API call may be discontinued! See CreateAccountEmail() for a replacement.

UpdateAccount( $username, $firstName, $lastName, $password )

• $username 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;

UpdateAccount( $username, undef, undef, 'newpassword' );

to change names only, you would call it as such:

UpdateAccount( $username, 'newfirstname', 'newlastname', undef );

UpdateAccountEmail( $userName )

• Adds email services to a hosted account created with CreateAccount().
• > NOTE: this API call may be discontinued! See CreateAccountEmail() for a replacement.

UpdateAccountStatus( $userName, $status )

• $status is either 'locked' or 'unlocked'

RetrieveAccount( $userName )

DeleteAccount( $userName )

RenameAccount( $oldName, $newName, $alias )

• $alias is either '1' or '0'
• > WARNING: 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:

oldname: user to rename newname: new username to set for the
user alias: if 1, create an alias of oldname for newname

so yeah, she's experimental. be careful with her. 🙈

🦋 'Alias' methods

CreateAlias( $userName, $alias )

RetrieveAlias( $userName );

DeleteAlias( $alias );

💌 'Mailing List' methods

CreateMailingList( $mailingListName )

UpdateMailingList( $mailingListName, $userName, $listOperation )

• $listOperation is either 'add' or 'remove'

RetrieveMailingList( $mailingListName )

DeleteMailingList( $mailingListName )

⚙️ 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 API method is called. so like, don't be surprised. 💅

admin( $admin )

• set the administrative user, and will return administator username.

password( $string )

• set the password, returns an empty string

📊 Miscelleaneous statistics methods 📊

there are a few methods to access some statistics data that is collected while the object performing Google API calls. she's keeping receipts. 📝

authtime()

• returns the time of last authentication, as generated by the time() function

ctime()

• returns the create time of the object, as generated by the time() function

rtime()

• returns the time of the most recent request, as generated by the time() function

logins()

• returns the number of API logins that have been performed

requests()

• returns the numbers of API requests that have been submitted to Google

success()

• returns the numbers of successful api request performed

and finally, 🌟

version()

• returns a string with the api version implemented. this is currently '1.0'

---

🔮 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 API documentation in the SEE ALSO section for complete details.

some of the more useful elements you may need to look at are:

$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 'Account', 'Alias', 'MailingList'

and the retrieval section contains data when you are querying. here is what this section looks like when you call the RetrieveAccount method:

$google->{result}->{RetrievalSection}->{firstName}
$google->{result}->{RetrievalSection}->{lastName}
$google->{result}->{RetrievalSection}->{accountStatus}
$google->{result}->{RetrievalSection}->{aliases}->{alias}
$google->{result}->{RetrievalSection}->{emailLists}->{emailList}

to see the structure of the result hash, use the Data::Dumper module as such:

use Data::Dumper;
print Dumper($google->{result});

ngl, Dumper is the move here. just look at it. the hash will explain itself. 🔥

---

🌈 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:

print $google->requestcontent();

the most recent received HTML data is stored in two parts, the headers and the content. both are strings. they can be accessed as such:

print $google->replyheaders();
print $google->replycontent();

and note: the headers are new-line separated and can easily be parsed:

foreach my $headerline ( split/\n/, $g->replyheaders() )
{
    my ($header, $value) = split/:/, $headerline;
}

splitting on newlines then on colons. classic. she's a simple girlie and that's the point. 💖

---

📦 EXPORT 📦

None by default. that's it. that's the whole section. no sneaky exports. 🙅♀️

---

👀 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

for support, see the Google Group at http://groups.google.com/group/apps-for-your-domain-apis

for additional support specific to this modules, email me at johan at reinalda dot net.

---

💜 AUTHOR 💜

Johan Reinalda, johan at reinalda dot net

---

💖 COPYRIGHT AND LICENSE 💖

Okay bestie, legal bit, but make it cute. 🎀

Copyright (C) 2006 by Johan Reinalda, johan at reinalda dot net

This library is free software — like, actually free, not "free trial" free. You can redistribute it and/or modify it under the same terms as Perl itself, and that means either Perl version 5.8.5, or — at your option — any later version of Perl 5 you happen to have lying around. Your call, no pressure. 🫶

---

And listen, if you make a useful modification? The author is literally asking, so politely: kindly consider emailing them to him for inclusion in a future version of this module. That's it. That's the ask. He's not being weird about it, he just wants your glow-up in the next release. ✨

---

And that's a wrap on VUser:...::V1_0(3pm), bestie — you made it to the end and honestly? 👑 This one's a User Contributed Perl Documentation page, riding with perl v5.32.0, dated 2021-01-09, and fr fr you now know this module better than half the internet. Go forth and slay. 💅🌸🦋