QB Signatures
Formula URL parameters—what's behind the button?
A formula field on your table runs QB Signatures. The formula builds a URL made of your designated QB Signatures server address followed by parameters that tell it which record to sign, where to save the signature, and what to show the signer. The installation wizard creates these buttons for you (see QB Signatures in the installation wizard); edit the formula to change any of the options below. If the signing window shows a message instead of the signature pad, see QB Signatures messages and troubleshooting.
A few terms used on this page:
Client ID—your Quickbase Extensions Client ID: the letter Q followed by a number, for example Q1234. The wizard writes it into the Sign Off button as clientid=Q…, so the easiest way to get it is to copy it from that formula. The samples on this page show it as Q#.
Table ID (DBID)—a table's unique identifier. In a formula, Dbid() returns the current table's ID, and a table alias such as [_DBID_TERMS] (for a table named Terms) returns another table's. See Table aliases.
Field ID (FID)—the number Quickbase gives each field. You can find it in the field's properties in Quickbase. Record ID# is always field 3.
Change the button
Open the table's settings and select Fields.
Select the Sign Off field (or Sign Off (Mobile)).
In the Formula box, add or change parameters. In the encoded form the wizard creates, put each parameter inside Base64Encode( ), before the closing parenthesis.
Save the field, then open a record and test the button.
Each button has its own formula. If you use both Sign Off and Sign Off (Mobile), change both.
Two ways to pass the parameters
Encoded (recommended)—join the parameters with &, wrap them in Base64Encode(), and pass the result as a single request parameter. This is what the installation wizard creates, and it keeps values such as field IDs out of the visible URL.
Plain—add each parameter to the URL directly, joined with &.
Replace https://... with your designated QB Signatures server URL, provided during setup (it's in the formula the wizard created), and Q# with your Client ID.
Writing values inside request=
Parameter names are case-sensitive. Write them exactly as shown on this page, for example appID, H, and W. In the plain form, names aren't case-sensitive.
Pass text as-is. Don't wrap it in URLEncode(): the signer would see codes such as %20 instead of spaces. Don't use & inside a value, because & separates the parameters.
Use plain characters. Accented letters and other special characters may not display correctly.
Everything goes inside. Parameters added to the URL outside request= are ignored.
In the plain form, wrap text values, especially values that come from fields, in URLEncode().
Parameters that don't work in every form yet
Both forms are supported. For now, a few parameters work in only one of them:
size is read only inside request=. In the plain form, set the pad size with H and W instead.
qbuserfid and tdbid are read only in the plain form. Inside request= they're ignored: no value is saved to the signeradmin field, and a terms document stored on another table doesn't open.
The clist2 drop-down list isn't enforced as required yet. The signer can save without choosing a value.
Parameters
Parameter | Description | Sample in formula |
|---|---|---|
Authorization parameters—identify the account and application running QB Signatures. | ||
clientid | Required. Your Quickbase Extensions Client ID: Q followed by a number. Copy it from the Sign Off button the wizard created. | "clientid=Q#" |
appID | Required. The ID of the Quickbase application. Used to confirm the application is authorized to use QB Signatures. | "&appID=" & AppID() |
apptoken | Optional. An application token, if your application requires application tokens. Leave it blank otherwise. | "&apptoken=" |
Table and record parameters—which record is signed and where the results are saved. | ||
dbid | Required. The ID of the table that holds the record and stores the signature. | "&dbid=" & Dbid() |
recid | Required. The Record ID# of the record being signed. If the key field has been renamed, use its new name in the brackets. | "&recid=" & [Record ID#] |
fafid | Required. The field ID of the file attachment field that receives the signature image. | "&fafid=14" |
updatefid | Optional. The field ID of a Date / Time field that is set to the date and time the signature was saved, in your application's date format and time zone. | "&updatefid=15" |
fn | Optional. The start of the signature file name. The record's Record ID# and .gif are added to the end, so fn=Signature_ on record 3 creates Signature_3.gif. End the value with an underscore or another separator to keep the Record ID# readable. If omitted, files are named signature_<table ID>_<Record ID#>.gif. To use a field's value inside request=, add it as-is, for example "&fn=" & [Client Name] & "_". In the plain form, wrap it in URLEncode(). The button the wizard creates adds a number from the clock, so its files have names like Signature_4573.gif. See Sample formula: Sign Off button. | "&fn=Signature_" |
Signer details—information the signer enters or reviews before saving. | ||
fid1 | Optional. The field ID of a field the signer fills in—for example, their name. A text box labeled with the field's Quickbase label appears under the signature pad, and the signer's entry is saved to that field. The field is required (marked with a red *) unless you add an uppercase U to the field ID. Use a text field. | "&fid1=16" "&fid1=16U" // optional |
fid2 | Optional. A second field the signer fills in—for example, their title. Works the same as fid1. You can use either field on its own. | "&fid2=17" |
fatermsfid | Optional. The field ID of a file attachment field holding a terms and conditions document. The signer sees a required checkbox with the link Click here to view terms., which opens the document in a new tab, and must check the box before saving. By default the file is read from the same record, and the field must be a file attachment field. If the field is empty on the record, the link doesn't open anything, but the signer still has to check the box. | "&fatermsfid=24" |
tdbid | Optional. Use with fatermsfid and trecid when the terms document is stored on a different table—for example, one shared terms record. The ID of that table. For now, plain form only. | "&tdbid=" & [_DBID_TERMS] |
trecid | Optional. The Record ID# of the record holding the terms document on the tdbid table. | "&trecid=1" |
clist | Optional. A period-separated list of field IDs from the record to show in the signing window, two per row, each labeled with its Quickbase field label and filled in with the record's current value. The signer can change them, and changes are saved back to the record. Text, Text - Multiple Choice (shown as a drop-down list), Checkbox, and Date fields are shown; other field types are skipped. Every field ID must exist on the table. | "&clist=8.67.55.17.28" |
clist2 | Optional. Shows a drop-down list of records from another table, and saves the chosen record's Record ID# to a field on this record. The value has four parts separated by colons: table ID:query:field ID to display:field ID to update. The query can't contain a colon. The list is meant to be required, but this isn't enforced yet. | "&clist2=" & [_DBID_CREWS] & ":{'8'.EX.'Active'}:7:110" |
qbuserfid | Optional. A value to record with the signature—typically the Quickbase user who opened the window. It's saved to the field in signeradmin. For now, plain form only; wrap the value in URLEncode() as shown. | "&qbuserfid=" & URLEncode(UserToName(User())) |
signeradmin | Optional. The field ID of a text field that receives the qbuserfid value. | "&signeradmin=20" |
Window appearance | ||
size | Optional. The size of the signature pad: S (450 × 200 pixels), M (550 × 300), L (650 × 400), or XL (750 × 500). Not case-sensitive. If size, H, and W are all omitted, the pad is 450 × 200. For now, read only inside request=; in the plain form, use H and W. | "&size=L" |
H W | Optional. A custom signature pad height and width in pixels. Leave size out and pass both H and W. | "&H=400" "&W=450" |
titledlg | Optional. Replaces the heading above the signature pad (by default Please sign below and save). Inside request=, type the text as-is, without URLEncode() and without &. In the plain form, wrap it in URLEncode(). | "&titledlg=Please sign to accept delivery" |
titlefid | Optional. The field ID of a field whose value is used as the heading, so it can change per record. titledlg takes priority if both are supplied. | "&titlefid=72" |
After saving | ||
rdr | Optional. The address to go to after the signer saves and closes the window, wrapped in Base64Encode(). Defaults to the record the signature was captured on. | "&rdr=" & Base64Encode(URLRoot() & "db/" & Dbid() & "?a=dr&rid=" & [Record ID#]) |
submitclose | Optional. When true, the button reads Submit instead of Save, and the window closes on its own after saving instead of waiting for the signer to select Close. If rdr is supplied, the signer goes to that address instead. Defaults to false. | "&submitclose=true" |
Advanced | ||
request | All of the other parameters, joined with & and wrapped in Base64Encode(). Use instead of passing them plainly. clientid must be inside it. Parameter names inside it are case-sensitive, and values are read exactly as written—see Writing values inside request=. | "request=" & Base64Encode("clientid=Q#" & ...) |
preqbaction | Optional. A Quickbase API call to run when the signing window opens, wrapped in Base64Encode()—for example, to mark the record as being signed. Requires the enhanced security button. The call must point at your own Quickbase realm and act on the same table as the button; calls that open a Quickbase page, such as GenAddRecord, don't work. If the call fails, its error is shown instead of the signature pad. See Change formula fields. | "&preqbaction=" & Base64Encode(URLRoot() & "db/" & Dbid() & "?a=API_EditRecord&rid=" & [Record ID#] & "&_fid_30=Signing") |
Sample formula: Sign Off button
This is the Sign Off button the installation wizard creates, a Formula - Text field with Allow some HTML tags selected. It opens the signing window as a pop-up, saves the signature to field 14 and the date and time to field 15, and asks the signer for the values of fields 16 and 17 (field 17 optional):
var Text url = "https://.../Signature.aspx?" // your QB Signatures server URL, created by the installation wizard
& "request="
& Base64Encode(
"clientid=Q#" // your Client ID
& "&appID=" & AppID()
& "&dbid=" & Dbid()
& "&recid=" & [Record ID#]
& "&fafid=14" // Signature File
& "&updatefid=15" // Sign-off Date
& "&fn=" & "Signature_" & MSecond(ToTimeOfDay(Now()))
& "&fid1=16"
& "&fid2=17U"
& "&fatermsfid="
& "&apptoken="
);
"<a class='Vibrant Success OpenAsPopup POSTTempToken' style=\"\" data-height=800 data-width=700 data-refresh=true data-tempTokenDBID='" & Dbid() & "' href=\"" & $url & "\" >Sign Off</a>"About the lines in this formula:
fn—the wizard's file name is Signature_ followed by the milliseconds of the time the button was displayed (a number from 0 to 999). QB Signatures then adds the Record ID#. So record 3 might get Signature_4573.gif: 457 from the clock, then 3. The number changes every time, so you can't read the Record ID# from the name. For names such as Signature_3.gif, change the line to & "&fn=Signature_".
fatermsfid= is empty, so no terms checkbox appears. Add a field ID to require one (see fatermsfid above).
size isn't set, so the pad is Small (450 × 200). For a larger pad, add & "&size=L" on its own line before & "&apptoken=".
The POSTTempToken class and data-tempTokenDBID value let Quickbase confirm the user has access to the record when your account uses Quickbase enhanced security—keep them as shown. data-height and data-width set the pop-up window size; data-refresh=true refreshes the record when the window closes so the new signature appears.
Sample formula: plain parameters
A similar button with the parameters passed plainly instead of encoded. It uses a fixed file name and sets a Large pad with H and W, because size isn't read in the plain form yet:
var text url = "https://.../Signature.aspx?" // your QB Signatures server URL, created by the installation wizard
& "clientid=Q#" // your Client ID
& "&appID=" & AppID()
& "&dbid=" & Dbid()
& "&recid=" & [Record ID#]
& "&fafid=14"
& "&updatefid=15"
& "&fn=Signature_"
& "&fid1=16"
& "&fid2=17U"
& "&H=400"
& "&W=650"
& "&apptoken=";
"<a class='Vibrant Success OpenAsPopup POSTTempToken' data-height=800 data-width=700 data-refresh=true data-tempTokenDBID='" & Dbid() & "' href=\"" & $url & "\">Sign Off</a>"Mobile button
The Sign Off (Mobile) button the wizard creates is a Formula - URL field, displayed as a button that opens in a new window. The wizard creates it so it sends a temporary token, so it also works when your account uses Quickbase enhanced security. Its URL is the same as the Sign Off button's, plus an rdr parameter that returns the signer to the record after saving:
"https://.../Signature.aspx?" // your QB Signatures server URL, created by the installation wizard
& "request="
& Base64Encode(
"clientid=Q#" // your Client ID
& "&appID=" & AppID()
& "&dbid=" & Dbid()
& "&recid=" & [Record ID#]
& "&fafid=14"
& "&updatefid=15"
& "&fn=" & "Signature_" & MSecond(ToTimeOfDay(Now()))
& "&fid1=16"
& "&fid2=17U"
& "&fatermsfid="
& "&apptoken="
& "&rdr=" & Base64Encode(URLRoot() & "db/" & Dbid() & "?a=dr&rid=" & [Record ID#] & "&z=" & Rurl())
)We understand these parameters can be complex—submit a technical support case if you have any questions.