1. Checkbox
  2. Guides
  3. Use Cases

User List

In Checkbox, a User List is a configurable database field that applications can retrieve for user assignment or selection.

 

SKIP AHEAD TO 
Setting the Scene
Setting Up the User List Database
Granting your applications permission to access the database
Retrieving the User List based on a category or selection within your App
Using the Created User List Variable Within the App

 

 

Setting the Scene

The Situation:

Employees submit expense reports, and the required approvers for sign-off are determined based on the employee’s department and approval thresholds (e.g., Finance Manager or CFO sign-off is required for finance-related expenses). As a business, you want a way to automatically send notifications and/or assign approvals to a set of users (those who can approve).

This user list can be utilized in the following areas:

  1. Workflow Block – Ensures the assessment is assigned to the correct approvers based on the selected department. This is recommended when you want to the system to notify and assign who should approve the expense report.
  2. Dropdown or Radio Field – Allows users to select an approver from a predefined list, ideal when only one approver needs to be chosen. This is recommended when you want a person to make the selection, not the system, on who should approve the expense report.

In the next sections, we'll walk through the steps to create a User List from a database and set up a user list field within the app to ensure seamless integration.

 

Step-by-step instructions

Create a Database for the User List

Before assigning a User List within a workflow, you need to create a database to store the user list information.

Setting Up the User List Database

  1. Add a column for the user category – This could be a business unit or department, allowing you to filter and distinguish between different user lists within the app.

    In this example, we selected a dropdown field to allow users to choose from a prepopulated list instead of manually typing when adding a new entry to the database. This ensures a more seamless experience with predefined set of departments.

    Example of field configuration setup and output when adding a new database record:

    Department Field Editor.png

    When adding an entry.png

  2. Add another column (for the Approver List) and set its type to "List"

    • In the Field Editor, select User under the List Types dropdown.
    • This is where your the names of the Approvers will be entered.

      user list type.png

     

  3. Manually add users to the list.

    • Only users with Checkbox accounts can be selected, similar to the User Picker field.

    Below is an example of how the database will look once everything is set up.

    Approver Database.png

Granting your applications permission to access the database

To allow the app to retrieve values from the created database, add the Solution where the app is created under the Access & Permission section.

DB permission.png

 

Retrieving the User List based on a category or selection within your App

  1. Start by adding a FORM block to allow manual input from users. After selecting the block, click Open Form Builder.

    form.png

  2. Set up a Dropdown Field (other form fields may also be used, but we recommend a dropdown as a pre-populated list ensures data consistency in the database, reducing errors from manual input).

    form builder.png

  3. In the Property Field, enter the list of Departments. The selected department will later be used to retrieve the corresponding approvers.

    DepartmentDropdown.png

     

  4. Return to the Studio and add a DATABASE block and create a route from the FORM block to it.
    form to db.png

     

  5. Click on the DATABASE block to edit its properties, select a database from the dropdown, and set the Data Function to Retrieve.

    Select Database.png

     

  6. Under the Find the entries to retrieve section, select Retrieve all matching entries.

  7. Add a database field to match the selected value from the app with the database.

    Matching setup:

    This is how you establish the connection/relationship between the Database and the Dropdown field.

    • Target database field – The column in the database where the selected value will be matched.
    • Operator – Define how the values should be compared.
    • Value – The app variable containing the selected value from the app.

    In this example, we'll use the DepartmentDropdown field added to the form (as the "Value"), and Department as the "Target database field" from which we’ll retrieve the matching entries or approvers.

    DB filter.png

  8. Create a "New App variable" for the User List under the Retrieve variables section.
    new app var.png

     

Using the Created User List Variable Within the App

  1. Assign Assessments to Users in the List via the Workflow Block

    • Add a WORKFLOW block and create a route from the DATABASE block to it.
      DATABASE TO WORKFLOW.png

    • Click on the WORKFLOW block to edit its properties, select User List Variable from the Assignment Option dropdown.

    • Choose the appropriate User List Variable.

      workflow editor ss.png

       

  2. Use the List to Prepopulate Dropdown or Radio Fields for Approver Selection

    • If the User list variable will be used to populate a dropdown, add a FORM block instead and route the DATABASE block to it.
      db to form ss.png

    • Add a Dropdown field with instructions for users to select an approver from the list.

      approver dropdown ss.png

    • In the Options section, select "Set Options Using a List Variable" and choose the created User List Variable.

      ApproverDropdown.png

       

Use Case: Retrieving a Single User List Variable

This feature also allows you to retrieve a single predefined user list, making it especially useful when sending scheduled assessments to a group of users.

Setting Up the User List Database

  1. Create a Database for the User List
    • Add a new database and create a single field.
    • Set the Field Type to "List" and select "User" as the List Type.
  2. Manually Add Users to the List

    • Only users with Checkbox accounts can be selected, similar to the User Picker field.

      User List DB.png

Retrieving the User List Within the App

  1. Add a DATABASE Block
    • Select the database containing the user list.
  2. Set the Data Function to "Retrieve"
    • Choose "Retrieve all entries" under the Find the entries to retrieve section.
  3. Create an App Variable for the User List
    • Under the Retrieve Variables section, define a New App Variable to store the retrieved user list.

      Property Editor Single User LIST.png