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

NAME

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

VERSION

$Revision: 1.53 $

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.");


 #The values for View are 'Read', 'ReadOwn' and  'ReadNone'
 #The values for Modify are 'Modify', 'ModifyOwn' and  'ModifyNone'
 #The values for View and Administer are just either blank or something other than blank
 %permissions=("view" => "", "add" => "1", "modify" => "","admin" => "");
 # Let anyone on the Internet add new records to my guest book
 $qdb->ChangePermissions($database_clone_id, "Anyone with Internet access", %permissions );
 %permissions=("view" => "any", "add" => "1", "modify" => "any","admin" => "1");
 # Let the user Barney do anything he wants with the database
 $qdb->ChangePermissions($database_clone_id, "Barney", %permissions );
 
 #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

$qdb->ChangePermissions($QuickBaseDBid, $usergroup, %permissions)

Adds users or groups to a database's access control list, or modifies the permissions levels for existing members of a database's access control list. $QuickBaseID identifies the database. $usergroup is either a QuickBase screen name, an email address of a registered QuickBase user or the name of a QuickBase group. Only users with administrator permissions on a database can change the permissions of other users with respect to that same database.

The keys of the input %permissions, along with their valid values is as follows:

view none, own, any

modify none, own, any

create false, true

admin false, true

If one or more of the four permission is not included in %permissions, its setting is not changed. If you just want to check on the permission settings for a user or group, just call ChangePermission with an empty %permissions. The return associative array follows the same convention as the input associative array except that every permission level is reported.

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.

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