The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTTP-QuickBase-1.55
River stage zero No dependents
++
/ HTTP::QuickBase

NAME

HTTP::QuickBase - Create a web shareable database in under a minute

VERSION

$Revision: 1.54 $

SYNOPSIS

 # see https://www.quickbase.com/up/6mztyxu8/g/rc7/en/ for details of the underlying API.
 
 use HTTP::QuickBase;
 $qdb = HTTP::QuickBase->new();
 
 #If you don't want to use HTTPS or your Perl installation doesn't support HTTPS then
 #make sure you have the "Allow non-SSL access (normally OFF)" checkbox checked on your
 #QuickBase database info page. You can get to this page by going to the database "MAIN"
 #page and then clicking on "Administration" under "SHORTCUTS". Then click on "Basic Properties".
 #To use this module in non-SSL mode invoke the QuickBase object like this:
 
 #$qdb = HTTP::QuickBase->new('http://www.quickbase.com/db');

 $username="fred";
 $password="flinstone";

 $qdb->authenticate($username, $password);
 $database_name= "GuestBook Template";
 
 #I don't recommend using the getIDbyName method because there are many tables with the same name.
 #Instead you can discover the database_id of your table empirically.
 #Read the follwing article to find out how:
 #https://www.quickbase.com/db/6mztyxu8?a=dr&r=w
 
 $database_id = "9mztyxu8";
 $clone_name = "My Guest Book";
 $database_clone_id = $qdb->cloneDatabase($database_id, $clone_name, "Description of my new database.");


  #Let's put something into the new guest book
 $Name = "Fred Flinstone";
 $dphone = "978-533-2189";
 $ephone = "781-839-1555";
 $email = "fred\@bedrock.com";
 $address1 = "Rubble Court";
 $address2 = "Pre Historic Route 1";
 $city = "Bedrock";
 $state = "Stonia";
 $zip = "99999-1234";
 $comments = "Hanna Barbara the king of Saturday morning cartoons.";
 #if you want to attach a file you need to create an array with the first member of the array set to the literal string "file" and the second 
 #member of the array set to the full path of the file.
 $attached_file = ["file", "c:\\my documents\\bedrock.txt"];
 %record_data=("Name" => $Name,"Daytime Phone" => $dphone, "Evening Phone" =>$ephone,"Email Address" => $email, "Street Address 1" => $address1,"Street Address 2" => $address2,"City" => $city,"State"=>$state,"Zip Code"=>$zip, "Comments" => $comments , "Attached File" => $attached_file );

 $record_id = $qdb->AddRecord($database_clone_id, %record_data);

 #Let's get that information back out again
 %new_record=$qdb->GetRecord($database_clone_id, $record_id);
 #Now let's edit that record!
 $new_record{"Daytime Phone"} = "978-275-2189";
 $qdb->EditRecord($database_clone_id, $record_id, %new_record);
 
 #Let's print out all records in the database.

 @records = $qdb->doQuery($database_clone_id, "{0.CT.''}");
 foreach $record (@records){
        foreach $field (keys %$record){
                print "$field -> $record->{$field}\n";
                }
        }

 #Let's save the entire database to a local comma separated values (CSV) file.
 
 open( CSV, ">my_qbd_snapshot.csv");
 print CSV $qdb->getCompleteCSV($database_clone_id);
 close CSV;     
        
 #Where field number 10 contains Wilma (the query)
 #let's print out fields 10, 11, 12 and 15 (the clist)
 #sorted by field 14 (the slist)
 #in descending order (the options)

 @records = $qdb->doQuery($database_clone_id, "{10.CT.'Wilma'}", "10.11.12.15", "14", "sortorder-D");
 foreach $record (@records){
        foreach $field (keys %$record){
                print "$field -> $record->{$field}\n";
                }
        }

 #You can find out what you need in terms of the query, clist, slist and options by
 #going to the View design page of your QuickBase database and filling in the form. Hit the "Display" button and
 #look at the URL in the browser "Address" window. The View design page is accessible from any database home
 #page by clicking on VIEWS at the top left and then clicking on "New View..." in the lower left.

REQUIRES

Perl5.005, LWP::UserAgent, Crypt::SSLeay (optional unless you want to talk to QuickBase via HTTPS)

SEE ALSO

https://www.quickbase.com/up/6mztyxu8/g/rc7/en/ for details of the underlying QuickBase HTTP API

EXPORTS

Nothing

DESCRIPTION

HTTP::QuickBase allows you to manipulate QuickBase databases. Methods are provided for cloning databases, adding records, editing records, deleting records and retrieving records. All you need is a valid QuickBase account, although with anonymous access you can read from publically accessible QuickBase databases. To learn more about QuickBase please visit http://www.quickbase.com/ This module supports a single object that retains login state. You call the authenticate method only once.

METHODS

Creation

$qdb = new HTTP::QuickBase($URLprefix)

Creates and returns a new HTTP::QuickBase object. Use the optional $URLprefix to connect to QuickBase via HTTP instead of HTTPS. call the constructor with a URLprefix parameter of "http://www.quickbase.com/db/". QuickBase databases are by default not accessible via HTTP. To allow HTTP access to a QuickBase database go to its main page and click on "Administration" under "SHORTCUTS". Then click on "Basic Properties". Next to "Options" you'll see a checkbox labeled "Allow non-SSL access (normally unchecked)". You'll need to check this box to allow HTTP access to the database.

Authentication/Permissions

$qdb->authenticate($username, $password)

Sets the username and password used for subsequent method invocations

Finding IDs

$qdb->getIDbyName($dbName)

Returns the database ID of the database whose full name matches $dbName. I don't recommend using the getIDbyName method because there are many tables with the same name. Instead you can discover the database_id of your table empirically. Read the follwing article to find out how: https://www.quickbase.com/db/6mztyxu8?a=dr&r=w

$qdb->GetRIDs ($QuickBaseID)

Returns an array of all record IDs in the database identified by database ID $QuickBaseID.

Cloning and Creating from Scratch

$qdb->cloneDatabase($QuickBaseID, $Name, $Description)

Clones the database identified by $QuickBaseID and gives the clone the name $Name and description $Description

Returns the dbid of the new database.

$qdb->createDatabase($Name, $Description)

Creates a database with the name $Name and description $Description

Returns the dbid of the new database.

$qdb->addField($QuickBaseID, $label, $type, $mode)

Creates a field with the label $label of label, a type of $type and if the field is to be a formula field then set $mode to 'virtual' otherwise set it to the empty string.

Returns the fid of the new field.

$qdb->deleteField($QuickBaseID, $fid)

Deletes the field with the field identifier of $fid.

Returns nothing.

$qdb->setFieldProperties($QuickBaseID, $fid, %properties)

Modifies the field with the field identifier of $fid using the name-value pairs in %properties. Please see the QuickBase HTTP API document for more details.

Returns nothing.

Adding Information

$qdb->AddRecord($QuickBaseID, %recorddata)

Returns the record id of the new record. The keys of the associative array %recorddata are scanned for matches with the field names of the database. If the key begins with the number one through nine and contains only numbers then the field identifiers are scanned for a match instead. If a particular key matches then the corresponding field in the new record is set to the value associated with the key. If you want to attach a file you need to create an array with the first member of the array set to the string literal 'file' and the second member of the array set to the full path of the file. Then the value of the key corresponding to the file attachment field should be set to a reference which points to this two member array.

Deleting Information

$qdb->DeleteRecord($QuickBaseID, $rid)

Deletes the record identified by the record identifier $rid.

$qdb->PurgeRecords($QuickBaseID, $query)

Deletes the records identified by the query, qname or qid in $query. Use the qid of '1' to delete all the records in a database.

Please refer to https://www.quickbase.com/db/6mztyxu8?a=dr&r=2 for more details on the query parameter.

Editing Information

$qdb->EditRecord($QuickBaseID, $rid, %recorddata)

Modifies the record defined by record id $rid in the database defined by database ID $QuickBaseID.

Any field in the database that can be modified and that has its field label or field identifer as a key in the associative array %recorddata will be modified to the value associated with the key. The keys of the associative array %recorddata are scanned for matches with the field names of the database. If the key begins with the number one through nine and contains only numbers then the field identifiers are scanned for a match instead. If a particular key matches then the corresponding field in the record is set to the value associated with the key. If you want to modify a file attachment field, you need to create an array with the first member of the array set to the string literal 'file' and the second member of the array set to the full path of the file. Then the value of the key corresponding to the file attachment field should be set to a reference which points to this two member array.

Use $qdb->EditRecordWithUpdateID($QuickBaseID, $rid, $update_id, %recorddata) to take advantage of conflict detection. If $update_id is supplied then the edit will only succeed if the record's current update_id matches.

Returns the XML response from QuickBase after modifying every valid field refered to in %recorddata.

Not all fields can be modified. Built-in and formula (virtual) fields cannot be modified. If you attempt to modify them with EditRecord you will get an error and no part of the record will have been modified.

Retrieving Information

$qdb->GetRecord($QuickBaseID, $rid)

From the database identified by $QuickBaseID, returns an associative array of field names and values of the record identified by $rid.

$qdb->doQuery($QuickBaseID, $query, $clist, $slist, $options)

From the database identified by $QuickBaseID, returns an array of associative arrays of field names and values of the records selected by $query, which can either be an actual query in QuickBase's query language, or a view name or number (qid or qname).

The columns (fields) returned are determined by $clist, a period delimited list of field identifiers.

The sorting of the records is determined by $slist, a period delimited list of field identifiers.

Ascending or descending order of the sorts defined by $slist is controlled by $options.

Please refer to https://www.quickbase.com/db/6mztyxu8?a=dr&r=2 for more details on the parameters for API_DoQuery.

$qdb->getCompleteCSV($QuickBaseID)

From the database identified by $QuickBaseID, returns a scalar containing the comma separated values of all fields including built in fields.

The first row of the comma separated values (CSV) contains the field labels.

$qdb->GetFile($QuickBaseDBid, $filename, $rid, $fid)

From the database identified by $QuickBaseID, returns an array where the first element is the contents of the file $filename uploaded to the record identified by record ID $rid in the field identified by field indentifier $fid.

The second element of the returned array is return value from the headers method of the corresponding LWP::UserAgent object.

Errors

$qdb->error()

Retrieve the error code returned from QuickBase. Please refer to the <a href="https://www.quickbase.com/up/6mztyxu8/g/rc7/en/"> Appendix A for error code details.

$qdb->errortext()

Retrieve the error text returned from QuickBase. Please refer to <a href="https://www.quickbase.com/up/6mztyxu8/g/rc7/en/"> Appendix A for all possible error messages.

New API calls added in 2008

CreateTable($QuickBaseDBid, $pnoun)

Add a table to an existing application.

Returns the dbid of the new table.

AddUserToRole($QuickBaseDBid, $userid, $roleid)

Add a user to a role in an application.

ChangeUserRole($QuickBaseDBid, $userid, $roleid, $newroleid)

Change the role of a user in an application.

GetDBvar($QuickBaseDBid, $varname)

Retrieve the value of an application variable.

GetRoleInfo($QuickBaseDBid)

Retrieve the list of Roles defined for an application.

GetUserInfo($email)

Retrieve a hash containing the login, name, and id of a user, given the user's email address.

GetUserRole($QuickBaseDBid,$userid)

Retrieve the Role information for a user

ProvisionUser($QuickBaseDBid,$roleid, $email, $fname, $lname)

Add the user information to QuickBase in preparation for inviting the user for the first time to view a QuickBase application.

GetOneTimeTicket

Retrieve a ticket valid for the next 5 minutes only. Designed for uploading files.

RemoveUserFromRole($QuickBaseDBid, $userid, $roleid)

Remove a user from a role in an application.

RenameApp($QuickBaseDBid,$newappname)

Change the name of an application.

SetDBvar($QuickBaseDBid, $varname, $value)

Set the value of an application variable.

SendInvitation($QuickBaseDBid, $userid)

Send an email from QuickBase inviting a user to an application.

UserRoles($QuickBaseDBid)

Returns an Xml Document of information about the roles defined for an application.

CLASS VARIABLES

None

DIAGNOSTICS

All errors are reported by the methods error and errortext. For a complete list of errors, please visit https://www.quickbase.com/up/6mztyxu8/g/rc7/en/ and scroll down to Appendix A.

AUTHOR

Claude von Roesgen, claude_von_roesgen@intuit.com

COPYRIGHT

Copyright (c) 1999-2008 Intuit, Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.