> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/insights/workspace/design/parameters.md).

# Parameters

This module is used for creating and managing parameters that are later used by prompts.

A parameter is one question that Insights answers for every record, for example "Did the agent greet the customer?" or "What was the main reason for contact?". You define it once, reuse it in any number of [Prompts](https://docs.borndigital.ai/insights/workspace/design/prompts.md), and its answers become fields you can filter and chart in your dashboards. With **Organization** switched on, other projects in your organization can use the same parameter, so every team measures the same thing the same way.

### Types and configuration fields

There are two parameter types: **Custom** (answered by the language model) and **Flow connector** (answered by a Digital Agent flow). A Custom parameter's configuration is split into the **Essential** tab (**Details** and **Value**) and the **Advanced** tab (**Settings** and **Normalization**). A Flow connector has no tabs; it shows the **Details** and **Extras** sections on one page.

#### Custom

A Custom parameter extracts a piece of information from the records of the selected [Data sources](https://docs.borndigital.ai/insights/workspace/upload.md). Parameters are combined and run by [Prompts](https://docs.borndigital.ai/insights/workspace/design/prompts.md).

<img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FXbGCo3okFS4UXZ4WlN8Z%2Fparameters-essential.png?alt=media" alt="Custom parameter — Essential configuration" width="375">

On-screen elements:

* **Type**: dropdown field with values [**Custom**](https://docs.borndigital.ai/insights/workspace/design/parameters.md#custom) and [**Flow connector**](https://docs.borndigital.ai/insights/workspace/design/parameters.md#flow-connector) for changing the parameter type
* **Essential:**
  * **Details:**
    * **Name**: input field of the parameter. The saved name is automatically normalized to lowercase `snake_case`. Two parameters cannot share a name.
    * **Language**: dropdown field, for selecting parameter processing language. If **Universal** is selected, the model decides for itself, using the language in the instructions.
    * **Organization**: switch for making the parameter available to other projects in the organization
    * **Definition**: input field for the instruction that is passed to the model to obtain the value. It is required.
    * **Output format**: buttons for selecting **String** (text), **Number**, **Boolean** (`true` or `false`) or **JSON** (an object with several values)
  * **Value** (shown for every **Output format**):
    * **Fallback value**: the value stored when the model does not find an answer. It is required as soon as **List of values** contains a value. For a **String** parameter, it is also stored when the record is empty and processing is skipped; the other formats store an empty result (`null`) in that case.
    * **List of values**: the allowed answers. For **String** and **Number** parameters, the model must answer with one of these values. Enter each value individually and confirm it with **Enter**.
    * **Enforce**: switch that replaces any answer that is not in **List of values** with **Fallback value**. It can be enabled only when both **List of values** and **Fallback value** are filled in, and it is not available for **JSON**.

{% hint style="info" %}
For a **Boolean** output, describe in **Definition** when the result should be `true` and when it should be `false`. For example: `Return true if the agent greeted the client. Return false otherwise.` The selected **Output format** enforces a native Boolean result, so do not add `true` and `false` to **List of values**.

Boolean results use the native JSON values `true` or `false`, without quotation marks. Values such as `0`, `1`, `"true"`, `"false"`, `YES`, and `NO` are not Boolean values.

Leave **List of values** empty and **Enforce** disabled for Boolean parameters. **Fallback value** is not applied to Boolean results. If processing is skipped because the input is empty, the result is `null`.

If you need `0` or `1`, use **Number**. If you need `YES`, `NO`, or another state such as `NOT_FOUND`, use **String**.
{% endhint %}

{% hint style="info" %}
For a **JSON** output, name the keys you expect in **Definition** – see [JSON parameters](https://docs.borndigital.ai/insights/workspace/design/parameters.md#json-parameters) for examples. **Enforce** cannot be used with JSON, and **Multi prompt behaviour** offers only the options that keep one object whole: **FIRST**, **FIRST\_FOUND**, **LAST** and **LAST\_FOUND**. When you switch an existing parameter to JSON, other behaviours are reset.
{% endhint %}

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FC7sc8YiZ89Deci1tC5gY%2Fparameters-advanced.png?alt=media" alt="Custom parameter — Advanced configuration" width="375"><figcaption></figcaption></figure>

* **Advanced:**
  * **Settings:**
    * **Custom categories**: dropdown field for selecting user-defined [Custom categories and AI category suggestions](https://docs.borndigital.ai/insights/workspace/design/categories.md). Selecting categories appends their values to **List of values**.
    * **Constraint**: input field for describing the format validation of the output
    * ⚙️ **Multi prompt behaviour**: dropdown field with strategies for combining the partial results when a long record is processed in several chunks. It is required.
    * ⚙️ **Weighted table**: dropdown field. It is enabled and required once **WEIGHTED\_VALUE** is chosen in **Multi prompt behaviour**, and it sets how the weighted aggregation is calculated.

{% hint style="info" %}
Multi-prompt setups break very long inputs into smaller processing segments because language models have limited context windows. This allows large documents or recordings to be processed without truncation. The input is split when its processed text reaches 110,000 characters. Each segment is processed separately, and the selected **Multi prompt behaviour** determines how the partial outputs are aggregated into a unified response.

This is relevant only for very long audio or text inputs. For Audio projects, recordings over one hour are an orientation only; the actual trigger depends on the transcription length and occurs when the processed text reaches 110,000 characters.
{% endhint %}

<details>

<summary>Context window and the splitting limit</summary>

A model's context window is the amount of text it can read in one request. It differs between models and providers and grows with newer model generations. Multi-prompt splitting currently uses a 110,000-character limit, which equals approximately 2–2.5 hours of a call recording, so virtually no call-center recording needs to be split.

</details>

* **Normalization**: settings for adjusting the parameter output
  * **Letter case conversion**: radio buttons **No**, **Uppercase**, **Lowercase** and **Capitalize**. **No** leaves the output unchanged.
  * **Remove diacritics**: radio buttons for removing diacritics from the output value when **Yes** is selected
  * **Apply underscore**: radio buttons for replacing spaces with underscores in the output value when **Yes** is selected
* **Delete**: button at the bottom for deleting the parameter. It is active only for a saved parameter.
* **Create** / **Save**: button at the bottom for creating a new parameter or saving changes to an existing one

#### JSON parameters

A JSON parameter answers several related questions in one go – a category together with its subcategory, an amount with its currency and date, or every topic a customer raised in one e-mail. You get structured results from a single parameter, and each value becomes its own field in your dashboards.

**Name the keys in the Definition.** The model returns exactly the keys you ask for. If you leave them out, it picks its own, and they can differ from record to record – a chart built on one key then misses the records that use another. How you write the keys does not matter: double quotes, single quotes, no quotes, or a sentence that lists them all work the same.

Definitions that work:

* `Return the category and subcategory (main topic and subtopic) of the text as a JSON object with the keys "category" and "subcategory".`
* `Return the category and subcategory (main topic and subtopic) of the text in format: {"category": "", "subcategory": ""}`
* `Return all topics of the text, each with its category and subcategory, in format: {"topics": [{"category": "", "subcategory": ""}]}`

**List the allowed values in the Definition** when you want consistent answers, because **List of values** is not applied to JSON. Without a list, the model may name the same thing differently from record to record, for example *Billing*, *Invoicing* and *Electricity bill*. For example:

`Return the category and subcategory of the text in format: {"category": "", "subcategory": ""}. category must be one of: "Billing", "Moving", "Customer line", "Other".`

The model keeps to such a list in most cases, but it is not enforced. When a chart needs a strictly fixed set of values, use a **String** parameter with **List of values** and **Enforce**.

**When nothing is found**, a JSON parameter returns an empty object `{}`. **Fallback value** is not used.

**In dashboards**, each key is a separate field named `<prompt>_<parameter>.<key>`, for example `topics_classification.category`. You filter and chart it like a String parameter. A record that returned `{}` has no such field.

A list of objects, such as the topics above, becomes one field per key with several values in each record. You can count how often each category appears across records, but a filter cannot tell which subcategory belongs to which category within one record. If you need that pair together in a chart, return it as a single object, not inside a list.

#### Flow connector

Use a Flow connector to connect an Insights project with a [flow](https://docs.borndigital.ai/digital-agent/conversation-flow.md) in a [Digital Agent](https://docs.borndigital.ai/digital-agent/introduction.md) project. The flow can use insight data for further processing and return results to Insights. Consider using it if you want to, for example, classify the emails or audio recordings first, change the metadata values, add new fields, etc., before entering analytics, during the analytical processing, or for post-analytical processing once the analytics are finished.

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FZYVos1zJCEJc7qreugqZ%2Fimage.png?alt=media&#x26;token=1d9047db-5a16-4a6b-a735-e01bbb271c7f" alt=""><figcaption></figcaption></figure>

On-screen elements:

* **Type**: dropdown field with values [**Custom**](https://docs.borndigital.ai/insights/workspace/design/parameters.md#custom) and [**Flow connector**](https://docs.borndigital.ai/insights/workspace/design/parameters.md#flow-connector) for changing the parameter type
* **Details**:
  * **Name**: input field for the Flow connector name. The saved name is automatically normalized to lowercase `snake_case`.
  * **Connect to project**: dropdown field for selecting a Digital Agent project in your organization
  * **Select trained version**: dropdown field for selecting a trained version of the selected project. It appears after you select a project; if the project has no trained version, a message asks you to choose another project.
  * **Organization**: switch, if enabled, the parameter can be used in the other projects within the organization
  * **Definition (auto-generated)**: read-only field that displays the mapping identifier for the selected Digital Agent project version

{% hint style="warning" %}
Consider connecting a proxy project rather than the target flow directly. The connector is bound to the selected trained version, so after you train the target project again it would still call the old version. A proxy project with a Transfer node always goes to the most recently trained version of the target. See Add a Flow connector.
{% endhint %}

* **Extras** (collapsed by default):
  * **Output variables**: input field for limiting which variables are returned from the connected flow. Leave it empty to return all named entities. If populated, only the listed variables are returned. Enter variables individually exactly as defined in Flow and confirm each with Enter.\
    Example: `flow_auto_email_handling_usecase`
  * **Previous parameter results to flow**: switch controlling whether results already available from earlier prompts are added to the flow metadata. It does not control the main conversation input.
    * If **disabled** (default), the main conversation is still sent to the flow as its input, but results from earlier prompts are not added to the flow metadata.
    * If **enabled**, the main conversation is sent to the flow as its input and results from earlier prompts are also added to the flow metadata. Each result keeps its existing `<prompt>_<parameter>` name.
  * **Send unprocessed transcript/text to flow**: switch for adding the original transcript or text to the flow metadata. The flow receives it in the `raw_utterance` variable as a JSON-formatted string, for example when it needs speaker turns rather than the flattened conversation.
  * **Should process email attachments**: Text/Email-only switch for enabling email attachment processing in the flow.

{% hint style="success" %}
Pro Tip:\
Send relevant data from Digital Agent back to Insights → you can then use them in your Dashboards easily.
{% endhint %}

* **Delete**: button at the bottom for deleting the parameter. It is active only for a saved parameter.
* **Create** / **Save**: button at the bottom for creating a new parameter or saving changes to an existing one

### Management

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FPNrDNiri4xuN2MClu5KB%2Fimage.png?alt=media&#x26;token=89a423ba-1294-4086-ac5e-dfa324a79582" alt=""><figcaption></figcaption></figure>

On-screen elements:

* Upper part:
  * **Search parameters**: bar for searching parameters by name or by the text of their **Definition**
  * **+ Create**: menu for creating a **Custom** parameter or a **Flow connector**
  * Filters (below search bar):
    * **All**: displays all parameters
    * **Global**: displays parameters shared across the organization
    * **Custom**: displays Custom parameters, including shared ones
    * **Flow**: displays Flow connector parameters, including shared ones
  * **Select**: enters bulk selection mode
    * **Select all**: selects every parameter of the current project in the list
    * **Done**: exits bulk selection mode
    * **Duplicate** and **Delete**: actions for the selected parameters. **Duplicate** creates a copy in the current project.
* List of parameters:\
  *(Elements are listed from the left)*
  * **Parameter name**
  * **Pencil**: icon button for editing the parameter. A parameter shared from another project shows an eye icon instead and opens read-only.
  * **Language**: displaying selected language for the parameter processing
  * **Global**: shown when the parameter is shared across the organization
  * **Parameter type**: displaying either **Custom** or **Flow connector**
  * **Prompt preview**: displaying a value of the parameter **Definition** field
* Floating buttons:
  * **Export**: downloads a JSON file with the project's prompts, the parameters created in this project, and the [project prompt](https://docs.borndigital.ai/insights/workspace/design/prompts.md#project-prompt). **Custom provider** settings are not exported, so API keys never leave the project.
  * **Import**: loads such a JSON file. It creates the parameters from the file in this project and **replaces the project's prompts** with the imported ones, including the project prompt when the file contains one. If a parameter used by an imported prompt already exists with the same name, the import stops and lists the duplicated names.
