---
title: "Variables (keys)"
section: "Data Source"
description: "Work with SmartestQA Data Source keys: create a key, take its value from a typed value, a dataset cell or an SQL query, add _DEV/_TEST/_PRP variants, folders and connected actions."
url: https://docs.smartestqa.ai/en/data-source-variables.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "data source key variable new key folder value comes from typed value dataset cell db query environment _DEV _TEST _PRP connected actions copy move delete"
---
# Data Source: Variables: keys and folders

A key is one named value that test steps read. This page covers creating keys and folders, the three value sources, environment-specific keys, connected actions, and changing or deleting keys without breaking tests.

## In short

**On this page you can**

- Create a key and give it a typed, dataset or database value.
- Group keys in folders and sub folders, and move them by drag and drop.
- Add _DEV , _TEST or _PRP variants of a key for one environment.
- Connect a key to the actions that use it, so the AI knows the data a page needs.
- Find empty, encrypted and environment-specific keys with the summary cards.

**How to use it**

1. Click New key ; the new key opens in the side panel.
2. Type the Key name and pick a Folder .
3. Choose Value comes from and fill the value or pick the cell or query.
4. Add a Description and click Save .
5. Use the key in a step as {{ds:yourKey}} .

## Create a key

1. **Open Variables**

   Go to **Data Source** › **Variables**.
2. **Click New key**

   Click **New key** at the top for a key at the top level, or **New key** in a folder’s row menu to create it inside that folder. SmartestQA creates the key with a placeholder name such as `new_key_244` and opens it in the side panel, with the **Key** field selected.
3. **Name it**

   Type the name the steps will use, for example `loginEmail`. Spaces are removed as you type. The name must be unique in the project; otherwise you see “This key already exists. Please enter a different name.”
4. **Set the value**

   Leave **Value comes from** on **Typed value** and fill **Default value**. For a password or token, switch on [**Encrypt**](https://docs.smartestqa.ai/en/data-source-secrets.html#encrypt) first; see [Encrypt a value](https://docs.smartestqa.ai/en/data-source-secrets.html#encrypt).
5. **Describe and save**

   Add a **Description**, for example “Login of the standard test user”, and click **Save**.

   “'loginEmail' updated successfully”. The key appears in its folder, and every step can read it as `{{ds:loginEmail}}`.

### The key panel

| Field | What it does |
| --- | --- |
| **Key** | The name steps use. No spaces. Required: Save stays disabled while it is empty. |
| **Folder** | Moves the key to another folder at once. This is not part of Save. |
| **Value comes from** | **Typed value**, **Dataset cell** or **DB query**. See [below](https://docs.smartestqa.ai/en/data-source-variables.html#value-source). |
| **Default value** | The value for a typed key. It is the default because [environment variants](https://docs.smartestqa.ai/en/data-source-variables.html#environments) can replace it. For a bound key the field is read-only and shows the binding. |
| [**Encrypt**](https://docs.smartestqa.ai/en/data-source-secrets.html#encrypt) | Stores the value encrypted. Only for typed values. See [Encrypt a value](https://docs.smartestqa.ai/en/data-source-secrets.html#encrypt). |
| **Description** | What the key is for. The AI also reads it. |
| **Connected Actions List** | The actions that use this key. See [Connected actions](https://docs.smartestqa.ai/en/data-source-variables.html#connected-actions). |
| **Created by** / **Updated by** | Who created and last saved the key, and when. |

The copy and delete icons sit in the panel header. If you close the panel or open another key with unsaved changes, you are asked “Are you sure to exit without saving?” with **Exit without saving**, **Cancel** and **Save and Exit**.

## Where a value comes from

A key has exactly one value source. Pick it under **Value comes from**; the choice is stored when you click **Save**.

| Option | The run gets | Use it for |
| --- | --- | --- |
| **Typed value** | The text in **Default value**, or the environment variant’s value. An empty value gives an empty text. | Fixed test data, URLs, secrets. |
| **Dataset cell** | One cell of a dataset, read when the step runs. | Values that already live in a spreadsheet. |
| **DB query** | The first column of the first row the SQL query returns, read when the step runs. | Values that change in the application, for example the newest order number. |

### Read a dataset cell

1. **Choose Dataset cell**

   In **Value comes from**, click **Dataset cell**. The dialog **Select dataset cell** opens: “Open with View and click a cell.”
2. **Open the dataset**

   Find it with **Search datasets** and click its row. The table opens. Headers cannot be picked here: “Headers aren't selectable; click a cell to pick its value.”
3. **Click the cell**

   The dialog closes and the value field shows “Dataset linked - `{{excel:users_email_2}}`”: dataset `users`, column `email`, row 2.
4. **Save the key**

   The key now always returns that cell. Change the cell in [the dataset](https://docs.smartestqa.ai/en/data-source-datasets.html#edit) and the key follows.

To remove the link, open the dialog again and click **Remove** (“Remove the dataset link?”), or switch back to **Typed value**, then save.

### Read a value from a database

You need a [DB connection](https://docs.smartestqa.ai/en/data-source-connections.html#add-db) first.

1. **Choose DB query**

   In **Value comes from**, click **DB query**. The **DB Request** dialog opens.
2. **Fill the request**

   **Name** (for example “Newest order number”), **Configuration** (the DB connection) and [**SQL Query**](https://docs.smartestqa.ai/en/automate-steps-database.html#sql-rules).

   Example · the key returns one order number

   ```sql
   SELECT order_no FROM orders WHERE status = 'NEW' ORDER BY created_at DESC
   ```
3. **Save the dialog, then the key**

   The value field shows “DB Connected - *connection* | *query*”. Click **Save** on the key.

   “'*key*' updated successfully”. Each time a step reads the key, the query runs and its first value is used.

> **Warning: The query runs on every read**
>
> Any query type is accepted: SELECT, INSERT, UPDATE, DELETE, DDL and stored procedures. The dialog warns about changes that are committed, about UPDATE or DELETE without WHERE, and about DROP or TRUNCATE. For a key, use a SELECT: a key that changes data every time a step reads it is hard to reason about. If the query returns no rows, the step fails with “Could not resolve DB data source '*key*': query returned no rows (0)”.

SELECT rules: the query must be in “SELECT … FROM …” form, list at least one column, and must not use `*` (“Asterisk (*) is not allowed. Please specify explicit column names.”). Put uppercase or reserved table and column names in double quotes: `SELECT username FROM "user" WHERE id = 1`.

### One source at a time

- A key bound to a database cannot be linked to a dataset: “This data source is bound to a DB. Remove the DB binding first to link a dataset.” The reverse gives “This data source is linked to a dataset. Remove the dataset link first to bind a DB.”
- A bound key is never encrypted. Choosing **Dataset cell** or **DB query** switches [**Encrypt**](https://docs.smartestqa.ai/en/data-source-secrets.html#encrypt) off.
- A DB-bound key cannot be copied: “This datasource is associated with a DB object. Copy cannot be performed.”

## Environment-specific keys

When a value differs per environment, keep one key per environment. Steps and [pipelines](https://docs.smartestqa.ai/en/schedule-create.html) always reference the name without the suffix.

| Key | Value | Environment column |
| --- | --- | --- |
| `apiBase` | `https://dev.shop.example.com/api` | Default + TEST, PRP chips |
| `apiBase_TEST` | `https://test.shop.example.com/api` | TEST chip + `apiBase` |
| `apiBase_PRP` | `https://shop.example.com/api` | PRP chip + `apiBase` |

What a step that uses {{ds:apiBase}} gets

```text
Run in DEV   → apiBase       (no apiBase_DEV exists, so the default)
Run in TEST  → apiBase_TEST
Run in PRP   → apiBase_PRP
```

- The suffix is exactly `_DEV`, `_TEST` or `_PRP`, upper case, at the end. Other underscores in the name are fine: `checkout_user_TEST`.
- A step that names a variant directly, `{{ds:apiBase_TEST}}`, always gets that key, whatever the environment.
- The same rule applies to datasets: a TEST run that reads dataset `users` uses `users_TEST` when it exists.
- The environment is the one the run uses (DEV, TEST or PRP), the same one that picks the [start page URL](https://docs.smartestqa.ai/en/quick-start-connect.html#start-page-url).
- **Send** on the [API Requests](https://docs.smartestqa.ai/en/api-requests.html) page and other previews on the screen use the default value, not a variant.

The **Environment** column shows **All** (“Used in every environment”) for a key without variants, **Default** plus chips for a key that has variants, and the environment chip for a variant. The **Environment-specific** card lists both.

## Folders

- **Create:** **New folder** at the top, or **New sub folder** in a folder’s row menu. Name it in the dialog (**Folder name**).
- **Rename:** folder menu › **Rename**.
- **Collapse:** click the folder header. Keys at the top level have no header: **Top level (no folder)**.
- **Delete:** folder menu › **Delete**. “The folder, its sub folders and every key in them are deleted. Test steps that use these keys can no longer read them.” A folder that is not empty can only be deleted by an [Admin](https://docs.smartestqa.ai/en/company-settings-roles.html).

Folders are for people. A key’s folder does not change its name in steps: `{{ds:loginEmail}}` works wherever the key sits.

## Connected actions

The **Connected Actions List** on the right of the key panel records which [actions](https://docs.smartestqa.ai/en/discover-actions.html) use the key, for example action `Type Email` on page `login` for `loginEmail`.

1. **Click Add**

   In the **Connected Actions List**, click **Add** (“You can connect actions to the Data Source”).
2. **Pick actions**

   Search with **Search Actions** and add one or more actions from the **Action List**.
3. **Save the key**

   The **Actions** column of the key shows how many actions are connected.

What it changes: the [App Map](https://docs.smartestqa.ai/en/discover-app-map.html) tells the AI which data each page needs (key name, kind, description and whether it is encrypted, never the value), so generated tests use your keys. Deleting a connected action shows the key under “Data Sources Using Action”; see [Deleting actions](https://docs.smartestqa.ai/en/discover-actions.html#delete). Connecting an action does not fill its steps: a step still needs `{{ds:key}}` in its value.

## Find keys

- **Summary cards** double as filters: **Keys**, **No value**, **Environment-specific**, **Encrypted**. Click one to filter, click it again to show all. How they count: [Summary cards](https://docs.smartestqa.ai/en/data-source-numbers.html#summary-cards).
- **Search:** **Search key or description** matches any part of the key or description.
- **Kind column:** empty for a plain key, otherwise **Encrypted**, **DB** or **Dataset**.
- **Default value column:** **No value** in amber for a plain key without a value, “•••••••• set” or “no value” for an encrypted key, “DB Connected” for a DB-bound key, the cell reference for a dataset key.

## Copy, move and delete

### Copy

Row menu › **Copy**, or the copy icon in the panel. The copy lands in the same folder as `loginEmail_copy` (then `_copy2`, `_copy3`…), with the same value and description, no connected actions and no dataset link. It opens in the panel so you can rename it. An encrypted key is copied as a plain key without a value: type the secret again and switch on [**Encrypt**](https://docs.smartestqa.ai/en/data-source-secrets.html#encrypt).

### Move

Drag a key (or several checked keys) onto a folder, or onto the bar “Drop here to move to the top level”. You can also use row menu › **Move to folder**, the **Folder** field in the panel, or check several keys and click **Move to folder**. Moving never changes how steps reference the key.

### Delete

- Only an [Admin](https://docs.smartestqa.ai/en/company-settings-roles.html) can delete a key. Others get “Failed to delete data source. Please try again.”
- Row menu › **Delete**, the delete icon in the panel, or check keys and click **Delete**. The dialog says “Test steps that use these keys can no longer read them. This cannot be undone.”
- Steps that reference a deleted key keep the reference, so they lose their value at run time. Search the tests for `{{ds:key}}` before you delete, or rename the key instead.

> **Tip: Renaming a key breaks its references too**
>
> Steps store the key’s name, not its id. After a rename, update every step that still uses the previous name. Safer: create the new key, switch the tests to it, then delete the old one.

## If something goes wrong

- [“This key already exists. Please enter a different name.”](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-key-exists)
- [“This data source is bound to a DB…”](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-bind-conflict)
- [“Could not resolve DB data source”](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-db-key-no-rows)
- [I can’t delete a key](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-delete-key)
- [The run ignores my _TEST key](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-env-variant-ignored)
