What is a Database?

A Database is an entity on Checkbox that stores data and acts as a single source of truth. Using a DATABASE block, Databases can allow Apps to read and write from a shared data source.

An example use case where you might use a Database and DATABASE block is if you have an HR Solution with an employee onboarding App and an employee performance review App. In this case, employee data can be captured from the employee onboarding App and stored in a Database. Once stored, you can use the DATABASE block to reuse and prefill the same data in the employee performance review App. Creating new and updating existing employee data in the Database is also possible from the App via the DATABASE block.

 

Who can access the Databases?

Please see the article on the available permission configurations for Databases.

 

How to create a Database

1. Click on "Databases" on the navigation bar
   
   
2. Towards the top of the left panel, click on the "+" icon to create a new Database
   
   
3. In the popup, add a name and description for the new Database and click "Create"
   
   Note: It is best practice to add a Database description, but this is an optional field when creating a new Database.
   
   
4. You should have now landed on the "Database" tab of the newly created Database and should be able to see a table that displays a "uuid" column by default
   
   
5. Click onto the "+" icon next to the "uuid" column to create a new column of data to store. The type of data you can capture includes:
   1. Text
   2. Number
   3. Dropdown
   4. Date
   5. Checkbox
   6. File Upload
   7. User

Tip: If you already have experience with the FORM block, you can treat these types of data as variables that capture user input. This concept becomes important when you want the data needs to flow to and from the Database and Apps within a connected Solution.

6. Repeat step 5 until you have all the columns required that you wish to capture in your Database

 

How to add entries/data to my Database

Note: You can only add entries after you have added at least 1 column to your Database table

There are 3 ways you can add entries into your Database:

1. Manual data entry
2. Bulk import via a CSV file
3. Create entry from an App via the DATABASE block
   
   

1. Manual data entry

1. In the "Database" tab of your Database, click on the "+" icon at the bottom left of the table
   
   
2. In the right panel that slides out, enter any relevant data in each available field
   
   Note: All fields are optional fields to fill in the Database (i.e., empty fields are accepted).
   
   
3. Click "SAVE" to save your changes
   
   

2. Bulk import via a CSV file

Note: The bulk import journey is almost identical to when bulk importing Assessment data. Learn more about bulk importing Assessments.

1. Create a CSV file and add all column names into the first row of your spreadsheet
   
   Note: You do not need to add the "uuid" column into your CSV file as this will be automatically generated on Checkbox after importing the rest of your data in bulk.
   
   
2. In all subsequent rows, enter all the details you wish to add
   
   
3. Go to your "Database" tab in your relevant Database
   
   
4. Click onto "Import CSV" and select the CSV file you created in steps 1-2 to bulk import your data into your Database
   
   Note: User variables in import CSV files are not supported for Databases.
   
   

3. Create an entry from an App via the DATABASE block

Please see the article on the create function in the DATABASE block.

 

How can I connect my Database to my Solution?

Connecting your Database to Solutions allows data to flow to and from the Database and Apps within the Solutions.

1. Go to the "Access & Permissions" tab of your Database
   
   
2. On the right of the screen for the table called "Permitted Solutions", click on the "+ ADD SOLUTION" button
   
   
3. Search and select a Solution to connect your Database to and click "CONFIRM"
   
   
4. Alternatively, you can click onto the "Permit all solutions access" toggle to allow convert your Database into a "global" Database that can be accessed by all Solutions in your organisation.

 

How to filter my Database entries

1. At the top of your Database on the "Database" tab, click on "Filter"
2. Using the dropdown inside the filter, select a variable you wish to filter for
3. Select any of the relevant operators
4. Select or add the value to complete the filter expression

Notes:

• The data in your Database will begin to filter in the background in real-time as you complete the filter expressions
• The filtered view of the Database is unique to each user and will persist until the browser cache is cleared or the filters are manually cleared or changed
• You can filter by email and full name even if the first and last names are captured in separate columns

 

How to sort my Database entries

1. Click onto the Database field name (i.e. the column name) to sort the Database entries

General sorting behaviour:

• By default, the Database should be sorted by ascending order for when the entry was created (i.e. the first-ever entry added will always be shown as the first data entry by default)
• Sorting should be applied to the entire Database and persist even if you add or remove filters to the Database
• The sorting should persist as you surf through the table pages using the Database pagination
• Only one type of sorting will persist at any one time. For example, if you sort by Text in ascending alphabetical then sort by Number in ascending numerical, your Database will only show the ascending numerical sorting since this was the most recent sorting applied
• Sorting will be cleared if the user leaves the Database page or refreshes the browser
• If some of the Database fields have blank values, these values will be shown at the tail end of any sorting

Field type sorting behaviour:

Field Type	Enable Sorting? (Y/N)	Sorting Type (e.g. ascending/descending alphabetical, numerical, date etc)
Text	Y	Alphabetical - alternates between ascending and descending as you click on the column name multiple times
Number	Y	Numerical - alternates between ascending and descending as you click on the column multiple times
Dropdown	Y	Alphabetical - alternates between ascending and descending as you click on the column name multiple times
Date	Y	Latest and Oldest - alternates between latest and oldest as you click on the column name multiple times
Checkbox	Y	True and False - alternates between true and false as you click on the column name multiple times
File Upload	N	N/A

 

How to export Database entries

1. At the top of your Database on the "Database" tab, click on "Export CSV"
2. The browser will start downloading a ZIP file containing the exported .csv file

Note:

• If the data is exported while the filters are active, only the filtered data will be exported

 

Database Permissions

Account-level configuration

Permissions available:

Permission	Description
Create New Databases	User can create new Databases within the organisation
Manage all databases	User gains full rights over the configuration of all the Databases in the organisation including the ability to: -       Add and remove new users -       Change user permissions -       Add and remove new permitted Solutions -       Add and remove fields -       Rename fields -       Re-arrange fields (columns) by drag and drop

 

Database level configuration

Permissions available:

Users can have any combinations of the following permissions.

Permission	Description
Database Manager	User gains full rights over the configuration of the Database including the ability to: -       Add and remove new users -       Change user permissions -       Add and remove new permitted Solutions -       Add and remove fields -       Rename fields -       Re-arrange fields (columns) by drag and drop -       Create, View, Update and Delete Database entries
Create	User can create entries in the Database directly including the use of csv file imports
View	User can view the Database and entries in the Database
Update	User can update entries in the Database
Delete	User can delete entries in the Database

 

How to allow users access to Databases

1. Go to the "Access & Permissions" tab of the Database
   
   
2. Under the "Permitted Users" table, click on the "+ ADD USER" button on the far right of the screen
   
   
3. Select a user(s) and their permissions using the available checkboxes or Database Manager toggle
   
   
4. Click "CONFIRM" to confirm your user additions

 

How to edit user permissions

1. Go to the "Access & Permissions" tab of the Database
   
   
2. Under the "Permitted Users" table, click on the ellipsis in the "Action" column for the user you wish to change permissions for
   
   
3. Change the user permissions by checking/unchecking the available permissions or toggling ON/OFF the Database Manager toggle
   
   
4. Click "CONFIRM" to confirm the user permission changes

 

 

 

Database FAQ

Will testing Database functionality in Preview affect my Database?

No. Any data created, retrieved, or updated from Preview in the App Studio will only interact with test data and will not affect live production data. Live production data will only be interacted with during live Assessments. 

Notes:

• Any changes in the Database design (e.g. adding/removing Database fields (or columns)) will persist in both production and test data views
• Only the user with the "Manage all Databases" account-level permission and/or "Manage" permission on a Database-specific can toggle between production and test data views. Test data will not be shown to users outside of these permissions
• By default, the production data view will be shown to users

 

What happens if I accidentally delete a Database field?

We have made sure to track the Solution and App dependencies relevant to your Databases to avoid making any breaking changes. For example, if you accidentally deleted a Database field and a dependency exists, a confirmation modal will pop up. To confirm the deletion of the Database field, you will be required to enter the Database field name in the confirmation modal.

 

Can end users lookup a Database in a FORM block?

Yes they can! For details on how to do this, please see the article on Lookup Fields on FORM blocks.