QBL definition
Quickbase language (QBL) is a schema extending YAML that allows you to create textual descriptions of Quickbase apps. QBL is human-readable, text-based, and portable. Note: QBL support for pipelines is expected to be available later this year.
The simple, intuitive syntax makes it easy to read and review changes to Quickbase apps. Use your text-based descriptions in SCM tools, just like more traditional software projects.
To make the QBL descriptions portable, we’ve conceptualized object identifiers, logical IDs. Because Quickbase uses logical IDs, it does not need to include app, table, and other globally unique identifiers in the format.
QBL syntax indicates references via logical IDs. This allows relationships and dependencies to be tracked inside of QBL descriptions. When creating or updating apps using QBL, the Quickbase platform translates references and logical IDs into the correct identifiers.
QBL Structure
The Solutions API defines solutions in YAML format with the following schema:
Version: 0.2
Resources:
$App_Project_Management_App:
<snip>Version—This numerical value represents the schema version of the QBL contained in the document. Learn more about QBL versions and Quickbase's versioning logic.
Resources—A YAML map. The key is logical IDs. The values are QBL descriptions of applications.
Syntax
QBL is a tree structure where each node has the following syntax:
Type: <namespaced type>
Properties: <map of properties and values>
<Type specific children>Each node is a value in a map, where the key is that node’s logical ID.
Here’s an example of an application node:
Resources:
$App_Project_Management_App:
Type: QB::Application
Properties:
Name: Project Management App Copy
Tables:
<snip>And to extend further with a table:
Resources:
TodoApp:
Type: Qb::Application
Properties:
Name: "My Todo List"
Tables:
$Table_Projects:
Type: QB::Table
Properties:
Name: Projects
$Table_Tasks:
Type: QB::Table
Properties:
Name: TasksThe example output shows two tables in the application. In this document, any relationships the Projects table might have with Tasks would be mediated via the logical ID $Table_Projects.
References
A !Ref tag is used to reference properties in other objects. For example, this tag can be used in table-to-table relationships to reference objects in different tables.
The !Ref tag specifies the type of object it is referencing and the logical ID:
SourceField: !Ref
Field: $Field_My_Field_logical_id The!Ref tag might also specify the scope of the object a property belongs to so that it can identify the correct field. For example, to reference a field in a different app, the QBL also specifies the app and the table that the field belongs to:
Properties:
DataField: !Ref
App: $App_MyApp
Table: $Table_MyTable
Field: $Field_My_Field_logical_id The !BadRef tag is exported in QBL in place of a !Ref tag when a reference cannot be resolved to a real resource. For example, form rules can reference fields and roles. If those fields or roles are deleted from the table within an app, the form rule definitions are not updated in the table schema. This means in the exported YAML, the form rules will attempt to reference fields and roles that may not exist anymore. !BadRef is the way to represent that in the exported YAML and keep the solution valid.
When a reference resolves to a valid resource, it is exported as:
Value: !Ref
Field: $Field_MyFieldIf the reference cannot be resolved, it is exported as:
Value: !BadRef "Referenced resource does not exist."Formulas and custom data rules
Formulas and custom data rules are observed as strings in QBL. For example, a formula URL field may look like:
$Field_Add_Task:
Type: QB::Field::URL::Formula
Id: 34
Properties:
Formula: |-
URLRoot() & "db/" & [_DBID_TASKS] & "?act=API_GenAddRecordForm&_fid_48=" & [Record ID#] &"&_fid_8=" & [Est Start Date] &"&z=" & Rurl()QBL does not recognize references to fields and tables as logical IDs.
When you update a solution using QBL, make sure there are no differences between the field and table IDs in the origin solution where you exported the QBL and the destination solution that you will use the QBL to update. If there are differences, make the IDs match the IDs in the destination solution.
Examples: Quickbase UI and QBL representation
Example 1—Quickbase UI
Example 1—QBL representation
Resources:
$App_Project_Management_App:
Type: QB::Application
Properties:
Name: Project Management App Copy
Description: Start your project management journey with this easy to use starter app!
Manager: rstoycheva@quickbase.com
CurrencySymbol: $Example 2—Quickbase UI
Example 2—QBL representation
Resources:
$App_Project_Management_App:
Type: QB::Application
Properties:
Name: Project Management App Copy
Description: Start your project management journey with this easy to use starter app!
Roles:
$Role_Team_Member:
Type: QB::Application::Role
Properties:
Name: Team Member
Description:
Default: true
ManageUsers: true
EditApp: false
DisableAccess: false
AppUI:
HideSettings: false
HideUsers: false
HideFavorites: false
HideSearch: false
HideHelp: false
HideTestAs: false
TableUI:
Global:
HideInBar: false
HideNewRecord: false
HideGridEdit: false
HideEmail: false
HidePrint: false
HideImportExport: false
HideSaveSpreadsheet: false
HideCreateCustomizeReport: false
HidePersonalSettings: false
$Table_Projects:
HideInBar: false
HideNewRecord: false
HideGridEdit: false
HideEmail: false
HidePrint: false
HideImportExport: false
HideSaveSpreadsheet: false
$Table_Tasks:
HideInBar: false
HideNewRecord: false
HideGridEdit: false
HideEmail: false
HidePrint: false
HideImportExport: false
HideSaveSpreadsheet: false