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";
$database_id = "9mztyxu8";
$clone_name = "My Guest Book";
$database_clone_id = $qdb->clone_database($database_id, $clone_name, "Description of my new database.");
# Let's put something into the new guest book
$record_id = $qdb->add_record(
$database_clone_id,
{
"Name" => "Fred Flinstone",
"Daytime Phone" => "978-533-2189",
"Evening Phone" => "781-839-1555",
"Email Address" => "fred\@bedrock.com",
"Street Address 1" => "Rubble Court",
"Street Address 2" => "Pre Historic Route 1",
"City" => "Bedrock",
"State" => "Stonia",
"Zip Code" => "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"]
}
);
# Let's get that information back out again
%new_record=$qdb->get_record($database_clone_id, $record_id);
# Now let's edit that record!
$new_record{"Daytime Phone"} = "978-275-2189";
$qdb->edit_record($database_clone_id, $record_id, \%new_record);
# Let's print out all records in the database.
@records = $qdb->do_query($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_qdb_snapshot.csv";
print CSV $qdb->get_complete_csv($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->do_query($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.
Perl5.005, LWP::UserAgent, Crypt::SSLeay (optional unless you want to talk to QuickBase via HTTPS)
https://www.quickbase.com/up/6mztyxu8/g/rc7/en/ for details of the underlying QuickBase HTTP API
Nothing
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.
A subroutine for adding a DB page.
Parameters
The QuickBase Database ID of the application you wish to add the page to.
The name of the page you wish to add.
Should be 1 for XSL stylesheets or HTML pages, or 3 for Exact Forms.
The contents of the page you are adding.
Example(s)
my $pagename="newstylesheet.xsl";
my $pagetype=1;
my $pagebody<<XSLHTML;
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0">
<xsl:template match="/">
<html>
<head></head>
<body>
Hello World
</body>
</html>
</xsl:template>
</xsl:stylesheet>
XSLHTML
my $page_id=$qdb->add_db_page("bep...pg2", $pagename, $pagetype, $pagebody);
print $page_id; # 6
See Also: add_replace_db_page, replace_db_page
Add a field to a QuickBase table.
Parameters
The unique ID of the QuickBase table you wish to add the field to.
The name of the new field.
The type of field you wish to add. The eligible type names differ slightly from their QuickBase UI counterparts:
QUICKBASE TYPE (UI) API TYPE ------------------- ------------------------ CheckBox checkbox Database Link dblink Date date Duration duration Email Address email File Attachment file Formula see the "mode" parameter Lookup see the "mode" parameter Numeric float Numeric-Currency currency Numeric-Rating rating Phone Number phone Text text Time of Day timeofday URL-Link url
If you want the field to be a formula specify ``virtual''. This can be set for any field type (type can be set to any value). If you want the field to be lookup specify ``lookup'' and set the Field Type to a text or numeric type.
Example(s)
my $fid=$qdb->add_field("bep...pg2", "Phone Number", "phone");
print $fid; # Prints 10
See Also: delete_field
Adds record to table
Parameters
The QuickBase Database ID of the table you wish to add the record to.
An array reference containing the record data.
Each array item should contain a hash reference detailing the field information, like so:
[
# First field, referenced by field name
{tag=>"field", atts=>{name=>"fieldname"}, value=>"fieldvalue"},
# Second field, referenced by field ID
{tag=>"field", atts=>{fid=>"22"}, value=>"otherfieldvalue"},
# Third field, file attachment type, referenced by field ID
{tag=>"field", atts=>{fid=>"30", filename=>"/path/to/myfile.jpg"}}
]
A subroutine for adding or replacing a DB page.
Parameters
The QuickBase Database ID of the application on which the page resides or will reside.
If you are adding a new page then you should pass the file name of the page here. If you are editing an existing page then you should pass the page ID here.
Should be 1 for XSL stylesheets or HTML pages, or 3 for Exact Forms.
The contents of the page.
Returns
The page ID of the page that was added or replaced.
Example(s)
my $pagename="newstylesheet.xsl";
my $pagetype=1;
my $pagebody<<XSLHTML;
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0">
<xsl:template match="/">
<html>
<head></head>
<body>
Hello World
</body>
</html>
</xsl:template>
</xsl:stylesheet>
XSLHTML
my $page_id=$qdb->add_replace_db_page("bep...pg2", $pagename, $pagetype, $pagebody);
print $page_id; # Prints 6
# Replaces new page with empty file
my $edited_page_id=$qdb->add_replace_db_page("bep...pg2", $page_id, $pagetype, "");
print $edited_page_id; # Prints 6
See Also: add_db_page, replace_db_page
Access to your application is governed by the roles in effect for your application. Users can access your application only if you assign them to one (or more) of these roles. You assign a user to a role using this call. A common use of this call is to set up a second call, send_invitation, where you let the user know that the user can access the application.
If you want a user to have several roles, you can invoke this on the same user several times, each time specifying a different role.
Although an application can use the standard default roles (viewer, participant, administrator), each application can have its own set of roles, with the access and permissions per role set up as needed by that particular application. You can find out what the roles are for the current application by calling get_role_info.
In order to make this call, you have to have administrator-level access in the application.
See also provision_user for an alternate way to assign roles to users.
Parameters
The application-level dbid of the application for which the role will be assigned.
The QuickBase userid of the user that will be added to the role.
The role id of the access role the user is being added to.
Returns
True/False value for success/failure.
Example(s)
print "Success!" if $qdb->add_user_to_role("6mpjiez8", "112245.efy7", 10);
See Also: provision_user, send_invitation, get_role_info
Provides access to the apptoken property
Parameters
The apptoken for subsequent calls
Example(s)
# Prints the current apptoken
print $qdb->apptoken();
# Assigns "b8qtx9rsf9gd..." to the apptoken property
$qdb->apptoken("b8qtx9rsf9gd...");
Initiates an authentication process, sending the username and password and retrieving a unique ticket identifier. Ticket retrieved will be stored in QuickBase instance and automatically inserted into subsequent API calls.
Parameters
Example(s)
# Authenticates the current $qdb object with QuickBase
# using the username/password my-username/my-password
$qdb->authenticate("my-username","my-password");
The record owner, by default, is the user who created it. QuickBase can use record ownership to restrict access. Normally, this is done through roles, where a role can be set up to restrict view and/or modify access to the record owner.
In order to call this method, you must have administrator rights to the application.
Parameters
Table-level dbid of the table containing the record you wish to transfer ownership of.
The ID of the record you wish to transfer ownership of.
The screen name or email address of the new owner.
Returns
True/False value for success/failure.
Example(s)
print "Record owner changed" if $qdb->change_record_owner("bdb5rjd6h", 3, "Muggsy");
This call allows you to assign a user to a different role.
Parameters
The ID of the QuickBase application in which the user's role will change.
The user ID of the user you wish to change the role of.
The current role ID of the user.
The role ID of the role you wish to change the user to. If no ID is specified for this parameter then the new role will be ``None''.
Returns
True/False value for success/failure.
Example(s)
$qdb->change_user_role("bdb5rjd6h", "112248.5nzg", "11", ""); # Changes role from 11 to "None"
Clone a QuickBase Application, including the schema, views, and users. Optionally, the data can be cloned as well, and if so the file attachments can be optionally included or excluded.
Parameters
The unique ID of the QuickBase application you wish to copy.
The name of the new database.
The description of the new database.
Set to 1 to clone the data as well as the structure.
Set to 1 to exclude file attachments from the clone process.
Returns
The DB ID of the new database.
Example(s)
# Clone bdb5rjd6h, calling the clone "New Database" with the description
# "My cloned database". Keep the data and the file attachments.
my $newdbid = $qdb->clone_database("bdb5rjd6h","New Database","My cloned database",1,0);
print $newdbid; # Prints bddnc6pn7
Creates a new QuickBase application with the main application table populated only with the built-in fields and optionally generates and returns an apptoken for API use.
Parameters
The name of your new application
The description of your new application.
Set to 1 to create an apptoken for the new application.
Returns
Returns a hash object containing the new application-level dbid of the new application and the apptoken if one was created:
{
dbid=>"bddnn3uz9",
apptoken=>"cmzaaz3dgdmmwwksdb7zcd7a9wg"
}
Example(s)
# Create a new application named Fuel Charter with the description Vehicle
# and Fuel Cost Tracker.
# Also create an apptoken for the new application.
my %newapp = $qdb->create_database("Fuel Charter", "Vehicle and Fuel Cost Tracker", 1);
print $newapp{'dbid'}; # Prints bddnn3uz9
print $newapp{'apptoken'}; # Prints cmzaaz3dgdmmwwksdb7zcd7a9wg
Creates a QuickBase table.
Parameters
The application in which the table will be created.
The name of the table
The pronoun that describes the items stored in the table
Returns
The new table's database identifier.
Example(s)
my $newdbid = $qdb->create_table("bep...yae", "Project Management", "Projects");
print $newdbid; # bep...pg2
If you have application administration rights you can use this call to delete either a child table or the entire application, depending on the dbid you supply.
Parameters
The Application or Table ID of the database you wish to delete.
Returns
True/False value for success/failure.
Example(s)
print "Application deleted!" if $qdb->delete_database("6mpjiez8");
If you have application administration rights you can use this call to delete a table field by specifying the field id. You have to use a table-level dbid, otherwise you will get an Error 31: No such field.
Parameters
The unique ID of the QuickBase table you wish to delete the field from.
The field ID of the field you wish to delete.
Returns
True/False value for success/failure.
Example(s)
print "Field deleted!" if $qdb->delete_field("6mpjiez8", 8);
If you have application administration rights you can use this call to delete a table record. You have to use a table-level dbid, otherwise you will get an error. If you want to delete several records at one time, you might want to use purge_records.
Parameters
The unique ID of the QuickBase table you wish to delete the record from.
The record ID of the record you wish to delete.
Returns
True/False value for success/failure.
Example(s)
print "Record deleted!" if $qdb->delete_record("bddnc2idi", 18);
You invoke this on a table dbid to get records from the table. You can use this to get all the records and fields, but typically you would want to get only some of the records and only those fields you want, ordered and sorted the way you want them to be.
More information on queries can be found in the QuickBase HTTP API Programmer's Guide under "Building and Using Queries".
Parameters
The table-level dbid of the QuickBase database you wish to query.
This parameter can be an ad hoc custom query or the ID or name of a query currently saved in the QuickBase application.
If the parameter is blank all records will be returned.
A period-delimited list of field IDs to be returned. The order you list
these in is the order in which they'll be returned. Alternatively, you can
specify the value ``a'' to get all the columns.
If the parameter is blank the table's default columns will be returned.
A period delimited list of field IDs for sorting.
A period-delimited list of options.
OPTION EFFECT ----------- ----------------------------------------------------------- num-n return a maximum of n records. onlynew return only those records marked with new or updated flags. skp-n skip the first n records returned by the query. sortorder-A sort ascending sortorder-D sort descending
sortorder-x options work with the Sort List. If one sortorder is specified it will use
the first column in the Sort List, the second will use the second column,
etc.
Specify ``structured'' to get additional table, field, and application information.
Specify a value other than structured to retrieve minimal information. ``unstructured'' is recommended in these cases.
Default if left blank is structured.
Returns
The value returned by do_query depends on the value expected and the type of format specified.
For either format, if the subroutine is called in array context then an array of records will be returned.
Otherwise, the subroutine will return a hash with the following structure:
{
action=>"API_DoQuery",
errcode=>0,
errtext=>"No error",
qid=>0,
qname=>'',
name=>"My Table",
desc=>"My table description",
table_id=>"bdb5rjd6g",
cre_date=>1204586581894,
mod_date=>1206583187767,
next_record_id=>34
next_field_id=>24
next_query_id=>5
def_sort_fid=>6
def_sort_order=>1
lastluserid=>0,
# fields only available via "structured" format
fields=>{
by_id=>{
"5"=>{
id=>5,
field_type=>"userid",
base_type=>"int32",
role=>"modifier",
mode=>"",
label=>"Last Modified By",
nowrap=>1,
bold=>0,
required=>0,
appears_by_default=>0,
find_enabled=>1,
allow_new_choices=>1,
sort_as_given=>0,
carrychoices=>1,
foreignkey=>0,
unique=>0,
doesdatacopy=>0,
fieldhelp=>"",
display_user=>"fullnamelf",
default_kind=>none,
num_lines=>0,
append_only=>0,
allowHTML=>0,
has_extension=>0,
max_versions=>"",
see_versions=>"",
use_new_window=>"",
comma_start=>"",
does_average=>"",
does_total=>"",
blank_is_zero=>""
},
"6"=>{
id=>6,
field_type=>"phone",
base_type=>"text",
role=>"",
mode=>"",
label=>"Business Phone Number",
nowrap=>0,
bold=>0,
required=>1,
appears_by_default=>1,
find_enabled=>1,
allow_new_choices=>0,
sort_as_given=>0,
carrychoices=>0,
foreignkey=>0,
unique=>1,
doesdatacopy=>0,
fieldhelp=>"This is the phone number",
display_user=>"",
default_kind=>"",
num_lines=>1,
append_only=>0,
allowHTML=>0,
has_extension=>1,
max_versions=>"",
see_versions=>"",
use_new_window=>"",
comma_start=>"",
does_average=>"",
does_total=>"",
blank_is_zero=>""
}
},
by_label=>{
"Last Modified By"=>{
# Repeat of structure found in fields->by_id->5
},
"Phone Number"=>{
# Repeat of structure found in fields->by_id->6
}
}
},
# queries only available via "structured" format
queries=>{
by_id=>{
"1"=>{
qyname=>"List All",
qytype=>"table",
qycrit=>"",
qyopts=>"",
qycalst=>"0.0",
qyclst=>"",
qydesc=>"",
qyslst=>"",
qyform=>"",
qyflbl=>"",
qyftyp=>""
},
"2"=>{
qyname=>"List Changes",
qytype=>"table",
qycrit=>"",
qyopts=>"so-D.onlynew.",
qycalst=>"0.0",
qyclst=>"",
qydesc=>"Sorted by Date Modified",
qyslst=>"2",
qyform=>"",
qyflbl=>"",
qyftyp=>""
}
},
by_name=>{
"List All"=>{
# Repeat of structure found in queries->by_id->1
},
"List Changes"=>{
# Repeat of structure found in queries->by_id->2
}
}
},
# users only available via "structured" format
users=>{
"112149.bhsv"=>"AppBoss"
},
# if the subroutine is called in array context then only this array will return
records=>[
# Structured format
{
"5"=>"112149.bhsv",
"Last Modified By"=>"112149.bhsv",
"6"=>"(123) 333-4321 x34566",
"Business Phone Number"=>"(123) 333-4321 x34566"
},
# Unstructured format
{
last_modified_by=>"AppBoss",
business_phone_number=>"(123) 333-4321 x34566"
},
{
# etc...
}
]
}
Example(s)
# Place the request
my %results = $qdb->do_query(
"bdb5rjd6h", # Table to query
"{'6'.SW.'(123)'}", # Search for phone numbers that start with (123)
"5.6", # Columns to return
"5", # Columns to sort by
"sortorder-A", # Sort ascending
"structured" # Request structured results
);
# Loop through the records of the results
foreach my $record(@{$results->{'records'}}){
# Retrieve the Contact username of the current record by looking up the
# user id in the results->users hash
my $user = $results->{'users'}{$record->{'Contact'}};
# Prints "Ragnar: (123) 333-4321 x34566"
print "$user: " . $record->{'Business Phone Number'} . "\n";
}
# Alternative method using array context
# Using query ID 6 and defaults for other params
foreach my $record($qdb->do_query("bdb5rjd6h","6")){
print $results->{'users'}{$record->{'Contact'}} . ": " . $record->{'Business Phone Number'} . "\n";
}
You can use this to change any of the editable field values in the specified record. Only those fields specified are changed, unspecified fields are left unchanged.
Parameters
The QuickBase dbid of the table in which the record resides.
The record ID of the record you want to edit.
A hash or array reference of field name/value pairs for editing. e.g.
{"email"=>"cucamonga@chuck.com"} or [{"name"=>"email", "value"=>"cucamonga@chuck.com"}]
The hash reference will assume that hash keys are field names if they do
not match the regex m/^\d+$/. Otherwise they will be assumed to be field IDs.
Returns
A hash reference containing the number of fields changed, the update ID, and the full content of the server response in the following format:
{
num_fields_changed=>5,
update_id=>1205700275470,
content=>'<?xml version="1.0" ?>\n<qdbapi>\n\t...'
}
Example(s)
# Update record 25 in table bdb5rjd6h and change the email field to "cucamonga@chuck.com"
my %results=$qdb->edit_record("bdb5rjd6h","25",{"email"=>"cucamonga@chuck.com"});
# Prints "1205700275470 1"
print $results->{'update_id'} . " " . $results->{'num_fields_changed'} . "\n";
See Also: edit_record_with_update_id
Like edit_record, you can use this to change any of the editable field values in the specified record. Unlike edit_record, the update will only be successful if the update_id provided is valid. This is to prevent potential collisions with multiple people editing the same record.
As before, only those fields specified are changed, unspecified fields are left unchanged.
Parameters
The QuickBase dbid of the table in which the record resides.
The record ID of the record you want to edit.
The current Update ID of the record you want to edit.
A hash or array reference of field name/value pairs for editing. e.g.
{"email"=>"cucamonga@chuck.com"} or [{"name"=>"email", "value"=>"cucamonga@chuck.com"}]
The hash reference will assume that hash keys are field names if they do
not match the regex m/^\d+$/. Otherwise they will be assumed to be field IDs.
Returns
If unsuccessful, a False value.
If successful, a hash reference containing the number of fields changed, the update ID, and the full content of the server response in the following format:
{
num_fields_changed=>3,
update_id=>992017018414,
content=>'<?xml version="1.0" ?>\n<qdbapi>\n\t...'
}
Example(s)
# Update record 25 in table bdb5rjd6h and change the email field to "cucamonga@chuck.com"
my %results=$qdb->edit_record("bdb5rjd6h","25",1205700275470,{"email"=>"cucamonga@chuck.com"});
# Prints "992017018414 1"
print $results->{'update_id'} . " " . $results->{'num_fields_changed'} . "\n";
See Also: edit_record
A method for accessing the current error code.
Parameters
If present, will set the error code to the provided value.
Returns
The current error code.
Example(s)
print $qdb->error; # Prints "0"
$qdb->create_database("Fuel Charter", "Vehicle and Fuel Cost Tracker", 1);
print $qdb->error; # Prints "74" (You are not allowed to create applications)
A method for accessing the current error text.
Parameters
If present, will set the error text to the provided value.
Returns
The current error text.
Example(s)
print $qdb->errortext; # Prints ""
$qdb->create_database("Fuel Charter", "Vehicle and Fuel Cost Tracker", 1);
print $qdb->errortext; # Prints "You are not allowed to create applications"
If you have administrative rights you can add new choices to any field through this method. If you don't have administrative rights you can only invoke this method if the multiple-choice field properties are set to allow new choices to be added.
If the choice you add already exists in the multiple choice list, the choice will not be added (no duplicates).
Parameters
The QuickBase dbid of the table the field resides in.
The field ID of the field you wish to add choices to.
An array reference of choices to be added, e.g. ["Choice 1","Choice 2","etc..."]
Returns
The number of choices that were added to the field.
Example(s)
my $num_added = $qdb->field_add_choices("bdb5rjd6h", 25, ["Choice 1","Choice 2"]);
print $num_added; # Prints "2"
See Also: field_remove_choices
If you have administrative rights you can remove choices from any field through this method. If you don't have administrative rights you can only invoke this method if the choice was created by you.
Parameters
The QuickBase dbid of the table the field resides in.
The field ID of the field you wish to remove choices from.
An array reference of choices to be removed, e.g. ["Choice 1","Choice 2","etc..."]
Returns
The number of choices that were removed from the field.
Example(s)
my $num_removed = $qdb->field_remove_choices("bdb5rjd6h", 25, ["Choice 1","Choice 2"]);
print $num_removed; # Prints "2"
See Also: field_add_choices
This method can be used to get the application-level dbid of an application whose name you know. Only those applications that have granted you access rights will be searched.
Because there can exist multiple applications with the same name, you should be aware that more than one application dbid can be returned.
Parameters
The name of the database you want to search for.
Returns
An array of dbids for databases matching the name you searched for.
Example(s)
my @dbids = $qdb->find_db_by_name("My Application");
print $dbids[0]; # Prints "bdcagynhs"
This method returns the standard QuickBase new record add page (in HTML) for the table whose dbid you specify. It contains edit fields for the user to fill and a save button to add the record to the database.
If you want to pre-fill any fields you can do so by supplying one or more field/value pairs in the request. Any fields not pre-filled or filled in by the user will get the default values set in the table field properties.
Parameters
The table-level dbid of the table you want to generate the form for.
A hash reference of field/value pairs for default values, e.g.
{"email"=>"cucamonga@chuck.com", "phone"=>"(123) 456-7890"}
Returns
Returns an HTML page containing the record add page with any pre-filled values.
Example(s)
my $html = $qdb->gen_add_record_form("bddrqepes", {"email"=>"cucamonga@chuck.com", "phone"=>"(123) 456-7890"});
print $html; # Prints the html page
This method is typically used in its URL form in an HTML page to embed the results as HTML, but it can also return results as a JavaScript array, in CSV format, or as tab separated values.
The SDK does not yet parse the results of any of these formats, and simply returns the raw response.
Parameters (A)
The QuickBase table-level dbid against which the query will be executed.
This parameter can be an ad hoc custom query or the ID or name of a query currently saved in the QuickBase application.
If the parameter is blank all records will be returned.
A period-delimited list of field IDs to be returned. The order you list
these in is the order in which they'll be returned. Alternatively, you can
specify the value ``a'' to get all the columns.
If the parameter is blank the table's default columns will be returned.
A period delimited list of field IDs for sorting.
Leave this parameter blank if you do not wish to receive HTML formatted results.
Set to 1 to use the CSS styles that render the HTML table with the QuickBase look and feel prior to April 11, 2003.
Set to n to use the CSS styles that render the HTML table with the QuickBase look and feel introduced on April 11, 2003.
Set to 1 if you wish to receive JavaScript Array formatted results, otherwise leave blank.
A period-delimited list of options.
OPTION EFFECT ----------- ----------------------------------------------------------- num-n return a maximum of n records. onlynew return only those records marked with new or updated flags. skp-n skip the first n records returned by the query. sortorder-A sort ascending sortorder-D sort descending ned omit the edit icons in HTML table format nvw omit the view icons in HTML table format nfg omit the new and updated icons in HTML table format phd plain (non-hyperlinked) headers abs absolute URLs csv comma-separated value output format tsv tab-separated value output format
sortorder-x options work with the Sort List. If one sortorder is specified it will use
the first column in the Sort List, the second will use the second column,
etc.
Parameters (B)
Because of the number of parameters this method accepts, it will also accept an alternative style wherein the 2nd through 7th parameters can be combined into a single hash reference. This aids readability and cuts down on unnecessary empty parameters.
The QuickBase table-level dbid against which the query will be executed.
A hash object reference containing the options you wish to set in the following format:
{
query=>"",
clist=>"",
slist=>"",
jht=>"",
jsa=>"",
options=>""
}
Returns
Currently returns the raw response contents from the API call.
Example(s)
my $results = $qdb->gen_results_table("bddrqepes",{query=>"{'0'.CT.''}",options=>'csv'});
print $results; # Prints "one,two,three,etc."
Performs a gen_results_table call, specifying all columns and all records and the CSV format.
Parameters
The QuickBase dbid of the database you want the CSV of.
Returns
CSV text.
Example(s)
my $csv = $qdb->get_complete_csv("bdcagynhs");
You can invoke this on the application-level dbid or the table dbid to get metadata information, such as the last time the table was modified. For example, you might use this function to find out if the table has changed since you last used it, or to find out if a new record has been added to the table.
Parameters
QuickBase application- or table-level dbid.
Returns
Returns a hash of the following format:
{
dbname=>"Test DB",
version=>"1.42",
lastRecModTime=>1205806751959,
lastModifiedTime=>1205877093679,
createdTime=>1204745351407,
numRecords=>3,
mgrID=>112149.bhsv,
mgrName=>AppBoss
}
Example(s)
my %dbinfo = $qdb->get_db_info("bddrqepes");
print $dbinfo{'dbname'}; # Prints "Test DB"
QuickBase allows you to store various types of pages, ranging from user-guide pages for your application to Exact Forms which are used to automate insertion of data into Word documents using a special Word template from QuickBase. This call lets you retrieve one of those pages in HTML.
Parameters
The QuickBase dbid of the application in which the page is stored.
The ID or name of the page you want to retrieve.
Returns
The requested page is returned in HTML.
Example(s)
my $page = $qdb->get_db_page("bdb5rjd6h", 6);
print $page; # Prints "<html><head>..."
DBVars are variables you can create and set values in at the application level, using the application-level dbid. This lets you get the values from these DBVars.
Parameters
The application-level dbid of the application the variable is stored in.
The name of the variable whose value you wish to retrieve.
Returns
The value of the DBVar requested.
Example(s)
my $color = $qdb->get_db_var("bddrqepes", "MyColor");
print $color; # Prints "blue"
Retrieves a file from QuickBase for given a table, record, and field.
Parameters
Table-level dbid containing the file.
The record ID containing the file.
The field ID of the file.
The version number of the file. Omitting this parameter, or using 0, will return the most recent version.
Returns
An array containing the file as the first element and the HTTP::Response headers as the second element.
Example(s)
my ($file) = $qdb->get_file("bdcagynhs", 78, 13);
print "$file"; # Prints retrieved file's contents
Returns the number of records in the table.
Parameters
The table-level dbid of the table you wish to query.
Returns
The number of records in the table.
Example(s)
my $num_records = $qdb->get_num_records("bdb5rjd6h");
print $num_records; # Prints 17
Returns a single-use ticket that expires after five minutes. After use, the ticket is no longer valid.
Intended for use with API_UploadFile, which is necessary only in environments that do not have access to the local filesystem.
Parameters
None.
Returns
A single-use ticket.
Example(s)
print $qdb->get_one_time_ticket(); # Prints "5_besfdf9uc..."
You invoke this on a table-level dbid to get all of the fields in a record.
Parameters
The table-level dbid of the QuickBase table the record is in.
The Record ID of the record you wish to retrieve.
Returns
Returns a hash of the following format:
{
rid=>20,
num_fields=>28,
update_id=>1205780029699,
user=>{
fid=>6,
name=>"user",
type=>"User",
value=>"Lodbrok"
},
f_6=>{
# reference to same hash as user
},
"file attachment"=>{
fid=>7,
name=>"file attachment",
type=>"File Attachment",
value=>"BatchID.html"
},
f_7=>{
# reference to same hash as file attachment
}
}
Example(s)
my %record = $qdb->get_record("bdb5rjd6h", 20);
print $record{'file attachment'}{'value'}; # Prints "BatchID.html"
You invoke this call on a table-level dbid to return a record as an HTML fragment that can be embedded in another HTML page.
Most frequently this method will be called via the GET method in a URL.
Parameters
QuickBase table-level database ID of the table containing the record
The Record ID (or rid) of the record you wish to retrieve
Set to 1 to return the information in Javascript format. The javascript will contain a function called qdbWrite which, when called, will output the HTML via document.write commands.
Omit this parameter for plain HTML format.
Returns
A string containing either a Javascript or an HTML representation of the record.
Example(s)
my $html = $qdb->get_record_as_html("bdb5rjd6h", 27);
# Prints HTML output, including css style information, links to javascript
# files on QuickBase's server, and the table containing the record.
print $html;
Invoking this call on a table-level dbid will return all the fields of a record, similar to do_query with all fields specified.
Parameters
Table-level QuickBase database ID in which the record resides
The Record ID (or rid) of the record
Returns
Currently returns unprocessed XML response.
Example(s)
my $xml = $qdb->get_record_info("bdcagynhs", 27);
print $xml;
###################################################
Prints:
<?xml version="1.0" ?>
<qdbapi>
<action>API_GetRecordInfo</action>
<errcode>0</errcode>
<errtext>No error</errtext>
<rid>20</rid>
<num_fields>28</num_fields>
<update_id>1205780029699</update_id>
<field>
<fid>6</fid>
<name>user</name>
<type>User</type>
<value>Lodbrok</value>
<printable>Boneless, Ivar</printable>
</field>
<field>
<fid>7</fid>
<name>file attachment</name>
<type>File Attachment</type>
<value>BatchID.html</value>
</field>
.
.
.
</qbdapi>
Used to retrieve a list of record IDs in a table.
Parameters
Table-level QuickBase database ID
Returns
Array of record IDs.
Example(s)
my @rids = $qdb->get_rids("bdb5rjd6h");
print join(", ", @rids);
# Prints: 1, 2, 3, 4, etc.
Use this method to get all of the roles that apply to an application.
Each application can have its own set or foles that govern user access to that application. To find out what roles are available in an application, you can invoke this method to return all of the roles and their information (name, ID, application access level).
The access level returned is one of these available access types:
Parameters
Application-level QuickBase database ID
Returns
An array of roles in the following format:
[
{
id => 10,
name => "Viewer",
access_id => 3,
access => "Basic Access"
},
{
id => 11,
name => "Participant",
access_id => 3,
access => "Basic Access"
},
{
id => 12,
name => "App Admin",
access_id => 1,
access => "Administrator"
}
]
Example(s)
# Retrieve the array of roles
my @roles = $qdb->get_role_info("bddrqepes");
# Print a list of role names and their access level
foreach my $role (@roles){
print $role{"name"}.": ".$role{"access"}."\n";
}
If you invoke this method on an application-level dbid it will return information about the application, such as any DBVars created for it and all child table dbids available.
If you invoke this method on a table-level dbid the DBVars are also listed, but there will additionally be table-related information such as queries, field IDs (fids), and the current property settings for each field.
Parameters
An application-level or table-level QuickBase database ID.
Returns
A detailed hash object containing the application or table schema in the following format:
{
"name" => "My Application/Table",
"desc" => "My application/table description",
"table_id" => "bdb5rjd6h", # dbid, field name same for applications and tables
"cre_date" => 1204586581894,
"mod_date" => 1206394201119,
"next_record_id" => 1,
"next_field_id" => 1,
"next_query_id" => 7,
"def_sort_fid" => 5,
"def_sort_order" => 6,
"variables" => {
"Blue" => 14,
"Jack" => 14,
"Magenta" => 12,
"usercode" => 14
},
# Available only in application-level dbids
"chdbids" => {
"_dbid_sample_database" => "bdb5rjd6g",
"_dbid_pronouns" => "bddrydqhg"
},
# Available only in table-level dbids
"queries" => {
"by_id" => {
"1" => {
"id" => 1,
"qyname" => "List All",
"qytype" => "table",
"qycalst" => 0.0
}
},
"by_name" => {
"List All" => {
"id" => 1,
"qyname" => "List All",
"qytype" => "table",
"qycalst" => 0.0
}
}
}
}
Example(s)
# Example code goes here
Returns a new authentication ticket from QuickBase.
Parameters
The username of the QuickBase user.
The password of the QuickBase user.
Example(s)
# Prints a new authentication ticket
print $qdb->get_ticket("my-username","my-password");
You invoke this method to get the user name and userid associated with the specified email address (used for QuickBase login). This call is useful in the contet of granting a user access rights to your application and then inviting that user to your application. This call is typically made to return the QuickBase userid for a user whose email address you know, in preparation for subsequent calls to add_user_to_role (grant access rights) and send_invitation, both of which require the userid.
The user email you specify must be recognized in QuickBase or this call won't work. For users not registered with QuickBase use the alternative provision_user.
If the email parameter is not supplied the ticket will be used to determine the user, and information for the currently authenticated user will be returned.
Parameters
Email address of the registered QuickBase user for whom you wish to retrieve information. If omitted, the currently authenticated user's information will be returned.
Returns
A hash object of the following format:
{
"id" => "112149.bhsv",
"firstName" => "Ragnar",
"lastName" => "Lodbrok",
"login" => "Ragnar",
"email" => "rlodbrok@paris.net",
"screenName" => "Ragnar"
}
Example(s)
my %user_info = $qdb->get_user_info("rlodbrok@paris.net");
print $user_info{'id'}; # Prints "112149.bhsv"
You invoke this method on an application-level dbid to find out what roles are currently assigned to a specific user in an application.
In contrast, the similar user_roles casts a bigger net, getting all users and their roles for the specified application.
Parameters
Application-level dbid for which the specified user's roles will be retrieved.
The user id of the user whose roles will be retrieved.
Returns
A hash object of the following format:
{
"id" => "112245.efy7",
"name" => "Ivar Boneless",
"roles" => [
{
"id" => 10,
"name" => "Viewer",
"access_id" => 3,
"access" => "Basic Access"
},
# etc...
]
}
Example(s)
my %user_roles = $qdb->get_user_roles("57pa5vjf","112245.efy7");
while my $role (@{$user_roles{'roles'}}){
# Prints "Viewer: Basic Access"
print $role->{'name'}.": ".$role->{'access'}."\n";
}
You invoke this method to get the names and dbids of all the applications and tables that you are able to access. Optionally, you can choose to retrieve parent applications, child tables, or both, or restrict the list to only those applications and tables to which you have administrative rights.
Parameters
Set this parameter to 1 to include applications in the response.
Set this parameter to 1 to include tables in the response.
Set this parameter to 1 to only show the applications and/or tables for which administrative rights have been granted.
Note: Omitting all parameters will return an empty array in all cases.
Returns
An array of the following format:
[
{
"dbname" => "Misc_Comments",
"dbid" => "bdadur4ak",
},
{
"dbname" => "Misc_Comments: Comment",
"dbid" => "bdadur4am"
},
{
"dbname" => "Misc_Comments: Rating",
"dbid" => "bdbs8ms3g"
},
{
"dbname" => "Misc_Comments: Emails",
"dbid" => "bdbtbrxed"
},
{
"dbname" => "API Created Sample",
"dbid" => "bdb5rjd6g"
}
]
Example(s)
my @databases = $qdb->granted_dbs();
foreach my $db(@databases){
print "$db->{'dbname'}: $db->{'dbid'}\n"; # Prints "Misc_Comments: bdadur4ak", etc.
}
You invoke this method on a table-level dbid to add or update a batch of records. You can even do adds and edits together in the same import_from_csv call. (For an add, leave the RecordID empty -- that's how QuickBase knows it's an add.)
In comparison, add_record and edit_record will only let you add or edit one record at a time. There is one limitation, though: you can't use this call to modify file attachment fields.
The clist parameter is optional when adding new records to a table. However, when updating existing records, you must specify the clist parameter. QuickBase uses this parameter to determine whether new records to a table or existing records are being updated.
For an edit operation, the clist parameter must contain the field ID for the Record ID# field. Also, the CSV must include a column that contains a record id for each record that you are updating.
Parameters
The QuickBase table-level dbid of the table you wish to update or add to.
The comma-separated input data.
A period delimited list of field IDs to which the CSV columns map. This means that the first field ID in the list maps to the first column in the CSV file, the second ID maps to the second column in the CSV file, and so forth.
To prevent a column in the CSV file from being imported, enter a 0 in the field list.
Examples:
In the following examples, the CSV file contains 4 columns
"0.7.0.6"
In this example, QuickBase will not import either the first or the third
columns in the CSV file.
"7.8.5"
In this example the field ID of 7 is mapped to the first column in the CSV
file, the field with a field ID of 8 is mapped to the second column, and
the field id of 5 is mapped to the third column. Since the clist parameter
does not include a fourth field ID, the fourth column in the CSV file is
ignored.
This parameter prevents QuickBase from importing the first row of data in a CSV file. You must set this parameter to 1 if the first row of your CSV contains column names.
Returns
Currently returns unprocessed XML.
Example(s)
my $xml_response = $qdb->import_from_csv("bddrqepes", "First Name,Last Name,Phone Number,Email,...", "5.6.10.11", 1);
A (mostly) private method for direct communication with the QuickBase API. The post_api method will take a parameter list and convert it into the requisite XML for a request, including the authentication and header information automatically. It returns an HTTP::Response object, after checking its contents for error information which is stored in the error and errortext properties if found.
Parameters
A QuickBase application- or table-level dbid. (``main'' should be used for API calls which do not require a database.)
The name of the QuickBase API to be invoked. Typically begins in API_xxxx.
A hash or array list of parameters to be sent to QuickBase.
A hash list of headers to send to QuickBase. Basic headers such as Content-Type and QUICKBASE-ACTION are set automatically.
Returns
An HTTP::Response object containing the response from QuickBase.
Example(s)
my $response = $qdb->post_api("bddrqepes", "API_GetDBvar", {"varname"=>"usercode"});
print $response->content;
# Prints:
<?xml version="1.0" ?>
<qdbapi>
<action>API_getDBvar</action>
<errcode>0</errcode>
<errtext>No error</errtext>
<value>12</value>
</qdbapi>
This method is invoked on an application-level dbid for a user that is not yet registered with QuickBase, but whose email is known to you. This call will:
After you invoke this method, you'll need to invoke send_invitation to invite the new user via email. When the user clicks on the link in the email invitation, the user is prompted to complete the brief registration. At this time, the user can change the first and last name you assigned.
If a user is already registered with QuickBase, you can't use this call. Instead, to do these same tasks you'll have to use get_user_info, add_user_to_role, and send_invitation.
Parameters
The application-level dbid of the QuickBase application you wish to grant the user access to.
The email address of the person to whom you are granting access.
The first name of the new QuickBase user.
The last name of the new QuickBase user.
The role ID of the role you want to assign the user to. If you don't supply a role, the role will be set to 'none'. This can be found via get_role_info.
Returns
The userid of the newly created user.
Example(s)
my $new_userid = $qdb->provision_user("bdcagynhs", "sanskor@sbcglobal.com", "Margi", "Rita" 10);
print $new_userid; # Prints "112248.5nzg"
Gets and sets the proxy for LWP::UserAgent to use when making API calls.
Parameters
The address for the proxy server to use.
Returns
The current proxy address.
Example(s)
print $qdb->proxy(); # Prints ""
$qdb->proxy("http://myproxy.com:8080");
print $qdb->proxy(); #Prints "http://myproxy.com:8080"
The purge_records method is used to delete several records at once, and has the potential to completely wipe out a table if the query parameter is omitted or empty.
You invoke this call on the table-level dbid of the table you want to delete the records from. If you only need to delete one record, delete_record would be a better choice.
All records matching your query criteria will be deleted.
Parameters
The table-level dbid of the table in which the records reside.
This parameter will accept one of three input types:
The name (qname) of the pre-built query you wish to execute.
The ID (qid) of the pre-built query you wish to execute.
The custom query built using the language specified at http://member.developer.intuit.com/MyIDN/technical_resources/quickbase/framework/httpapiref/HTML_API_Programmers_Guide.htm under Building and Using Queries.
Returns
The number of records deleted.
Example(s)
my $num_deleted = $qdb->purge_records("bddrqepes", "{'7'.CT.'Company B'}");
print "$num_deleted record(s) deleted.";
Gets and sets the realmhost to use when accessing QuickBase.
Parameters
The realmhost to use.
Returns
The current realmhost.
Example(s)
print $qdb->realmhost(); # Prints ""
$qdb->realmhost("http://mycompany.quickbase.com");
print $qdb->realmhost(); # Prints "http://mycompany.quickbase.com"
You invoke this method on an application-level dbid to remove the user entirely from the specified role in that application. Keep in mind that if the user has no other role, it eliminates the user entirely from the application's role list. This means that calling user_roles won't return the user at all, so you'll need to get the userid by calling get_user_info if you want to assign the user to another role in the future.
This method can be used to remove the user entirely from any role in the application, effectively turning off access to that user. If you intend to turn off all access, you would need to call get_user_roles to see what roles the user has, then invoke remove_user_from_role on each role.
If you expect to add that user to another role in the future, you should consider using change_user_role, which can be used to turn off access with a role set to None while keeping the user on the application's role list for future reinstatement or role change.
If you are simply changing the user from one role to another, you should use change_user_role.
Parameters
Application-level dbid of the application containing the role you want to remove the user from.
The user you want removed from the role.
The ID of the role you want the user removed from.
Returns
True/False value for success/failure.
Example(s)
print "Success!" if $qdb->remove_user_from_role("bdb5rjd6h", "112245.efy7", 11);
You invoke this method on an application-level dbid to change the application name. No dbids, fids, or anything other than the application name is affected. You must have administrator rights to call this.
Parameters
Application-level QuickBase dbid.
The name you want to change the application to.
Returns
True/False value for success/failure.
Example(s)
print "Application renamed" if $qdb->rename_app("bddrqepes", "My New Application Name");
A subroutine for replacing a DB page. See add_replace_db_page for more information.
See Also: add_replace_db_page, add_db_page
You invoke this method to send an email invitation for your application. The userid is either from an existing QuickBase user that you have granted access to via add_user_to_role, or from a new QuickBase user that you have created via provision_user.
Parameters
Application-level dbid of the application you want to invite the user to.
The ID of the user you want to invite to the application.
The message you want to display in your email invitation.
Returns
True/False value for success/failure.
Example(s)
print "Invitation sent" if $qdb->send_invitation("bdb5rjd6h","112249.ctdg","Welcome to my app!");
If you have administrator rights in an aplication, you can invoke this method to create a DBVar variable and/or set a value for it. If the DBVar already exists, this call will overwrite the existing value. You can only invoke this call on one DBVar at a time.
DBVars can only be set at the application level, so you must specify an application-level dbid.
Parameters
Application-level dbid in which the DBVar will be created or modified.
The name of the DBVar you wish to modify or create.
The value you want to set the DBVar to.
Returns
True/False value for success/failure.
Example(s)
print "Value changed" if $qdb->set_db_var("bddrqepes", "Day Number", 353);
You invoke this method on a table-level dbid to set one or more properties of a field. Normally, you use this call after you create a new field using add_field, to set up its default behavior, however you can also use this call any time you want to change properties, even if the affected field has data.
The properties available for a field vary slightly for different field types. To get all of the available properties for a field, and to get the field id (fid) needed, use the get_schema method.
Parameters
Table-level dbid containing the field you wish to modify.
The field ID of the field to modify.
A hash reference containing a list of properties and values to change. For a complete list of field properties, see the link below.
Returns
True/False value for success/failure.
Example(s)
my $success = $qdb=>set_field_properties("bddrqepes", 15, {"default_value" => "Hello"});
print "Default value changed" if $success;
You invoke this method to find out details about an application's users and their roles. You have to use the application-level dbid; a table-level dbid returns an error.
This method returns all users and their roles. In contrast, get_user_role gets only the roles for a specified user.
You can invoke this method if you have basic access rights or higher.
Parameters
Application-level dbid you want to retrieve the users/roles for.
Returns
An array of the following format:
(
{
"id" => "112149.bhsv",
"name" => "Jack Danielsson",
"roles" => [
{
"id" => 12,
"name" => "Administrator",
"access" => "Administrator",
"access_id" => 1
}
# etc.
]
}
# etc.
)
Example(s)
my @user_roles = $qdb->user_roles("bddrqepes");
my $num_users = $#user_roles;
foreach my $user (@user_roles){
print "User ID: $user->{'id'}\n";
print "User Name: $user->{'name'}\n";
print "Roles:\n";
foreach my $role (@{$user->{'roles'}}){
print " Role ID: $role->{'id'}\n"
print " Role Name: $role->{'name'}\n"
print " Role Access: $role->{'access'}\n"
print " Role Access ID: $role->{'access_id'}\n\n"
}
print "\n";
}
These methods are no longer preferred. They will be phased out in future versions of the SDK.
See add_field
See add_record
See add_user_to_role
See change_user_role
See clone_database
See create_database
See create_table
See delete_database
See delete_field
See delete_record
See do_query
See do_query
See edit_record
See edit_record_with_update_id
See find_db_by_name
See get_complete_csv
See get_db_info
See get_db_page
See get_db_var
See get_file
See find_db_by_name
See get_num_records
See find_db_by_name
See get_record
See get_record_info
See get_rids
See get_role_info
See get_schema
See get_ticket
See get_user_info
See get_user_roles
See granted_dbs
See import_from_csv
See post_api
See provision_user
See purge_records
See rename_app
See send_invitation
See apptoken
See set_db_var
See proxy
See realmhost
See user_roles