# Add & Replace Columns in Your Dataset
Source: https://docs.caplena.com/data-project-management/adding-replacing-data/add-replace-columns-in-your-dataset

Use Add & Replace to update specific rows or columns in your dataset

The **Add** & **Replace** function allows you to update existing rows in your Caplena dataset using a new file upload, without losing any manual coding or topic assignments.

This is especially helpful when refreshing or correcting your data while preserving previous work.

## When Should You Use "Replace Columns"?

The **Replace Rows** feature is ideal in the following scenarios:

### 1. You want to add a new column (Both TTA and Non-TTA)

*(TTA = Text to Analyze)*

Example: Add a demographic variable, metadata field, or custom tag that wasn't included in the original dataset.

<Note>
  **Use case:** Add new columns without re-uploading everything from scratch.
</Note>

### 2. You want to update values in a TTA column

If you've corrected or enriched your open-ended responses:

<Note>
  **Use case:** Replace rows while preserving existing coding or AI analysis.
</Note>

### 3. You want to update values in a non-TTA column

Example: Fixing or completing metadata like **Gender**, **Age**, or **Brand**.

<Note>
  **Use case:** Update values without re-uploading the whole dataset.
</Note>

## How to use Replace Rows

<iframe title="Loom video player" />

<Steps>
  <Step title="Open your project">
    Go to the **Data** section by clicking the **📄 document icon** in the left sidebar.
  </Step>

  <Step title="Click &#x22;Replace Rows&#x22;">
    In the top-right corner, click the **Replace rows** button.

    <Frame>
      <img alt="Screenshot 2026 05 22 At 12 49 51" title="Screenshot 2026 05 22 At 12 49 51" />
    </Frame>
  </Step>

  <Step title="Upload your new file">
    Upload a **CSV** or **Excel** file that contains the updated rows and/or new columns.
  </Step>

  <Step title="Match columns">
    In the column matching screen:

    **Select the identifier column** (e.g. "ID") — this is **required**. Caplena uses it to match the new rows to your existing dataset.

    <Warning>
      If no identifier is selected, the system won't know which rows to update, and the replacement process will not be possible.
    </Warning>

    When combined, these fields can form a unique identifier for each response.\\

    You can select **multiple identifier columns** if your dataset doesn't contain a unique response ID. For example, a combination of **Date**, **Name**, and **Open-end content** can together form a unique identifier.

    <Frame>
      <img alt="Screenshot 2026 05 22 At 12 52 29" />
    </Frame>

    Then **select only the columns you want to update** — columns that stay the same don't need to be selected.\\

    <Frame>
      <img alt="Select Columns" />
    </Frame>

    <Note>
      When creating a new TTA column, don't forget to enable it by selecting the **TTA** checkbox.
    </Note>
  </Step>

  <Step title="Validate and finalize">
    Click **Validate** to preview changes, then click **Finalize** to complete the replacement.

    <Frame>
      <img alt="Screenshot 2026 05 22 At 12 54 54" />
    </Frame>

    <Check>
      Done! Your dataset is now updated while all existing work (coding, topics, etc.) remains intact.
    </Check>
  </Step>
</Steps>


# Append Rows to an Existing Project
Source: https://docs.caplena.com/data-project-management/adding-replacing-data/append-rows-to-an-existing-project

Easily upload new data to your existing project, no need to start over or reconfigure your analysis.

Need to add more responses to your existing Caplena project? You can do this easily from the **Data View** tab.

<Note>
  As long as your existing data has already been analyzed (i.e., topics are in place), any newly added data will automatically be assigned to topics using the current setup.
</Note>

## Step 1: Go to the Data Tab

* In your project, click the **Data** icon in the left-hand navigation bar.
* Then click **Add new rows** in the top-right corner.

<Frame>
  <img alt="Clean Shot 2025 07 20 At 19 30 00" />
</Frame>

## Step 2: Upload Your File

In the import screen:

* Drag and drop your file, or click to browse
* File types supported: `.xls`, `.xlsx`, `.csv`, `.sav`, `.spss`
* *(Optional)* Add a name for the data source
* Make sure your file includes column headers in the **first row**
* Click **Continue** to proceed

<Note>
  Your file **does not need to match** the previous column order or column count
</Note>

## Step 3: Match Your Columns

Caplena will guide you through matching the new file’s columns with those already in your project.

**What happens automatically:**

* Columns with the same name are matched
* Order doesn’t matter, Caplena accepts columns in any order

<Frame>
  <img alt="Screenshot 2026 05 22 At 13 02 08" />
</Frame>

**Additional options:**

* Skip columns you don’t want to import
* Create new columns for unmatched fields
* Manually match columns if needed

<iframe title="Loom video player" />

<Tip>
  **Tip:** Use the filters at the top of the screen to focus on specific column types (text, numeric, date, etc.)
</Tip>

## Step 4: Validate and Finalize

* Click **Validate** to confirm your column mappings
* Click **Finalize** to upload the new rows

<Check>
  Your new data will now be added to the project and analyzed automatically.
</Check>

### Auto-Translation

If you plan to use **auto-translation**, please enable it when **creating the project**.\
It cannot be activated retroactively for existing projects.

<Note>
  Learn more about auto-translation →
</Note>

### Duplicate Row Handling

To avoid importing duplicates:

* Enable the **“Skip existing rows based on matched column”** toggle
* Select the column used for deduplication, usually an \*\*ID field

<Frame>
  <img alt="Screenshot 2026 05 22 At 13 04 05" />
</Frame>

This ensures that already-uploaded rows are not imported again. You can select multiple columns to match by. A row is considered a **duplicate** if **all column values are identical**.


# How to Add Additional Columns for Analysis After Upload
Source: https://docs.caplena.com/data-project-management/adding-replacing-data/how-to-add-additional-columns-for-analysis-after-upload

Missed a TTA column during import? Here's how to bring it in later—no reupload of the full dataset needed.

Did you forget to include a column for analysis during your data upload? No worries — there are two ways to bring that column into your analysis using **Smart Columns** or **Add & Replace**.

## Option 1: Using Add & Replace

If Smart Columns are not available or preferred, you can re-import the column using the **Replace** flow.

<Tip>
  The original dataset must contain a **unique identifier** column (for example, UUID or user ID).
</Tip>

<iframe title="Loom video player" />

<Steps>
  <Step title="Prepare your file">
    Include the **unique identifier** column (e.g., UUID, respondent ID) and the **column(s)** you forgot to include originally.
  </Step>

  <Step title="Replace Data">
    In your project, go to **Data → Replace Data** and upload your new file.
  </Step>

  <Step title="Match and add columns">
    Select the **identifier column** to match existing rows, then select the **new column(s)** to be added.
  </Step>

  <Step title="Configure and complete">
    **Check the TTA box** if the column should be treated as open text, select the option to **add as a new column**, and complete the upload.
  </Step>
</Steps>

## Option 2: Using a Smart Column (if included in your plan)

If you have **Smart Columns** enabled, you can turn an existing column into a **Text to Analyze (TTA)** column.

<Steps>
  <Step title="Open Smart Columns">
    Go to your project and open the **Smart Columns** panel, then click **Create Smart Column**.
  </Step>

  <Step title="Select column type">
    Select the column type **"Text to Analyze"**.

    <Frame>
      <img alt="Screenshot 2026 05 23 At 14 58 34" />
    </Frame>
  </Step>

  <Step title="Choose Formula and Variable">
    Choose **Formula**, click on **Variable**, and select the column you'd like to turn into a TTA field.

    <Frame>
      <img alt="Screenshot 2026 05 23 At 14 59 29" />
    </Frame>
  </Step>

  <Step title="Create & Fill">
    Click **Create & Fill**.

    <Frame>
      <img alt="Screenshot 2026 05 23 At 15 00 12" />
    </Frame>
  </Step>
</Steps>

<Tip>
  Your selected column will now behave like any other open-ended field and can be included in your analysis.
</Tip>


# AI-Generated Smart Columns
Source: https://docs.caplena.com/data-project-management/common-smart-columns-intro/ai-generated-smart-columns

Create, adapt, and refine Smart Columns in seconds, without writing complex formulas.

AI-generated Smart Columns help you transform your data using simple, natural-language instructions. Whether you’re building something new or fine-tuning existing logic, AI makes it faster and easier to get the results you want.

<iframe title="Loom video player" />

### What can GenAI do for Smart Columns?

With AI, you can:

* Generate new formulas and mappings from scratch
* Turn an idea into a working Smart Column using plain language
* Adapt or extend existing formulas as your analysis evolves
* Iterate quickly without rebuilding everything manually

Instead of worrying about syntax, you focus on *what* you want to achieve, AI takes care of the *how*.

### How GenAI understands your data

The generator works with context from your project:

* It knows which columns exist
* It understands whether columns contain text or numeric values
* It looks at up to 100 example values per relevant column

This helps GenAI create logic that fits your **actual data**, not generic assumptions

### Best practices for great results

* Reference existing column names
* Start with a simple instruction, then refine
* Use follow-up prompts to adjust edge cases

GenAI works best as an interactive partner, you can iterate until the Smart Column does exactly what you need.


# Creating a Helper Column (e.g. Wave or Year)
Source: https://docs.caplena.com/data-project-management/common-smart-columns-intro/creating-a-helper-column-e.g.-wave-or-year

Add simple wave or year labels to keep your datasets organized and comparable.

When you upload several datasets, or example, monthly or yearly data, it’s helpful to **differentiate between uploads** by assigning a label such as *Wave 1*, *Wave 2*, or *2024 / 2025*.

This allows you to:

* Filter or segment results per upload
* Compare time periods (e.g., “Wave 1 vs Wave 2”)
* Create clear visualizations over time

Caplena offers an easy way to do this using Smart Columns.

You can easily create a new **Formula Column** that assigns the same value to all records in your dataset. This is the easiest and most efficient method. When you upload new data waves, you can include this column directly in your dataset to clearly highlight which records belong to each wave or year.

**How to do it:**

<Steps>
  <Step>
    Go to **Columns → Add Column → Smart Columns → Formula**
  </Step>

  <Step>
    Choose **Output type:** Text
  </Step>

  <Step>
    Enter the following formula: `Wave 1   ` or `2025   `
  </Step>

  <Step>
    Save the column
  </Step>
</Steps>

This will add a new column with the same value (“Wave 1” or “2025”) for every row in your dataset.

<iframe title="Loom video player" />


# Creating a unique ID using Smart Columns
Source: https://docs.caplena.com/data-project-management/common-smart-columns-intro/creating-a-unique-id-using-smart-columns

Create a unique row identifier to safely update your data

Sometimes, your data doesn’t come with a built-in unique ID, and that’s totally fine! If you ever need to update or enrich your dataset later on, having a unique identifier is super helpful (and sometimes essential). 

Here’s how you can create and use it, and why it makes your life easier.

### Why This Matters

Whenever you want to **replace or update** data in Caplena, the system needs to know exactly which row you’re referring to. If there’s no unique ID, things can get messy. By creating a unique ID, you give each row a clear identity, making updates simple and safe, no accidental overwrites or mismatches.

### Step 1: Create a Row ID Using Smart Columns

<Frame>
  <img alt="Clean Shot 2025 09 15 At 15 17 30 (3)" />
</Frame>

<Steps>
  <Step>
    Go to your project and open the **Smart Columns** panel. Select **Formula**.
  </Step>

  <Step>
    Click **Create New Smart Column**.
  </Step>

  <Step>
    Give it a name, like `row_id`.
  </Step>

  <Step>
    Set the **Output Type** to `Text`.
  </Step>

  <Step>
    Choose `Row ID` as the formula.
  </Step>

  <Step>
    Hit **Compute Preview** to see how it looks.
  </Step>

  <Step>
    Click **Create & Fill,** and you’re done!
  </Step>
</Steps>

### Step 2: Convert Smart Column to a Regular Column

Right now, smart columns are dynamic and can't be used when replacing data. But no stress, it’s super easy to turn it into a regular one:

<Frame>
  <img alt="Clean Shot 2025 09 15 At 15 22 47 (3)" />
</Frame>

<Steps>
  <Step>
    Go back to the **Smart Columns** tab.
  </Step>

  <Step>
    Click the delete icon next to your `row_id` smart column, this **only deletes the smart logic**, not the values.
  </Step>

  <Step>
    Click the delete icon next to your `row_id` smart column. In the confirmation dialog, leave **Delete underlying column** unchecked and confirm — this **only deletes the smart logic**, not the values.
  </Step>

  <Step>
    Now the column becomes a static, regular part of your dataset, ready to use!

    <Note>
      Now that your row ID is ready, check out [this guide on how to replace data](/data-project-management/adding-replacing-data/add-replace-columns-in-your-dataset) for the next steps.
    </Note>
  </Step>
</Steps>


# Extracting Numeric Values From Customer Feedback
Source: https://docs.caplena.com/data-project-management/common-smart-columns-intro/extracting-numeric-values-from-customer-feedback

Turning customer text into measurable numeric insights.

Most customer and employee feedback is unstructured, people express emotions, describe problems, share expectations, compare experiences, and add lots of subtle detail.\
Numeric Smart Columns help you convert this free-form text into **clear, measurable values** that can be used in charts, filters, reports, and driver analyses.

This turns qualitative text into **quantitative insights** your team can act on.

Some examples of numeric Smart Columns are:

* **Severity Score**: how painful or serious an issue is
* **Satisfaction Score**: how satisfied the user feels based on their message
* **Engagement Score:** how engaged employees are

All these examples show how numeric extraction unlocks deeper analysis inside Caplena.

Numeric values allow you to:

* **quantify** text-based feedback
* **prioritize** what needs attention
* identify **key drivers** of dissatisfaction or satisfaction
* track **trends over time**

### **Example: Severity Score** 

This Smart Column assigns a value from **1 to 5** based on how severe the user’s problem is.\
It helps Support, CX, and Product teams quickly identify high-impact issues. 

<iframe title="Loom video player" />

**Use cases:**

* Identify high-severity complaints
* Filter severity ≥ 4
* Build driver chart (What drives severity?)
* Visualize severity by topic or brand

### Example: Employee Engagement Score

This is especially helpful for internal HR, pulse surveys, and employee listening programs.

<iframe title="Loom video player" />

**Use cases:**

* Track engagement across teams or locations
* Identify early signs of burnout or dissatisfaction
* Compare engagement drivers (workload, leadership, recognition)
* Combine with topics to reveal root causes


# How to Combine Likes & Dislikes for Joint Analysis
Source: https://docs.caplena.com/data-project-management/common-smart-columns-intro/how-to-combine-likes-dislikes-for-joint-analysis

Easily merge multiple columns (e.g., likes & dislikes) using Smart Columns, no extra tools needed.

Want to analyze *likes and dislikes* together in one go without any manual copying or external tools? With **Smart Columns** in Caplena, you can now merge multiple open-ended responses, like positive and negative feedback, and analyze them together in just a few clicks.

Here’s how to do it step by step:

<Danger>
  When merging **Likes** and **Dislikes** into a single column, please note the following to avoid unnecessary credit consumption:

  * **Likes and Dislikes must be imported as *Text* columns**, not as TTA (Text-to-Analyze).
  * If Likes and Dislikes are uploaded as separate TTA columns and then merged, the system will count **three TTA columns in total** (Likes + Dislikes + Merged), and credits will be charged accordingly.
</Danger>

<iframe title="Loom video player" />

## Step 1: Create a New Smart Column

<Steps>
  <Step>
    Go to your **Data** page.
  </Step>

  <Step>
    Click on **"Create New Smart Column."**
  </Step>

  <Step>
    Give your new column a name, for example:\
    `All Feedback Combined` or `Likes & Dislikes`.
  </Step>

  <Step>
    Under **Column Type**, choose:\
    `Text-to-analyze` – this will ensure the column is available for AI topic analysis.

    <Frame>
      <img alt="Screenshot 2026 05 22 At 17 03 51" />
    </Frame>
  </Step>
</Steps>

## Step 2: Choose the Smart Column Mode

<Steps>
  <Step>
    Select the **Formula** mode.\
    This allows you to merge the content from multiple columns.
  </Step>

  <Step>
    Use the **"Likes & Dislikes" template** — it's specifically designed for this type of task and will automatically generate a helpful formula.

    <Frame>
      <img alt="Screenshot 2026 05 22 At 17 06 34" />
    </Frame>
  </Step>
</Steps>

## Step 3: Select Columns to Merge

* Choose the two columns you want to combine, e.g.:
  * `What did you like?`
  * `What didn’t you like?`
* Optionally, add labels like:
  * `"Positive: "` and `"Negative: "`\
    This helps you (and the AI) better understand the source of each text.

<Frame>
  ## Step 4: Preview & Create
</Frame>

<Steps>
  <Step>
    Click **"Generate Sample"** to preview the result.
  </Step>

  <Step>
    If everything looks good, click **"Create & Fill"**.
  </Step>

  <Step>
    Done! 🎉\
    Your new column will now be populated and ready to use
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot 2026 05 23 At 14 51 32" />
</Frame>


# How to Combine Multiple Columns for Joint Analysis
Source: https://docs.caplena.com/data-project-management/common-smart-columns-intro/how-to-combine-multiple-columns-for-joint-analysis

Analyze all your questions in one place, even if they live in different columns.

Sometimes your open-ended feedback ends up spread across several different text columns, for example *Likes*, *Dislikes*, *Improvements*, or *Additional comments*.\
If you want a clearer, stronger picture of what your customers are saying, it often makes sense to **bring these fields together** and analyze them as one.

With **Smart Columns** in Caplena, you can merge any text fields in just a few clicks and run a **single, unified AI analysis**. No Excel formulas, no manual work, just clean, streamlined insights.

<Note>
  **Tip to Save Credits:**

  To merge efficiently:

  * Import the original columns as **Text**
  * Create **one** Smart Column as **Text-to-analyze (TTA)**

  If the originals are imported as TTA, each one counts toward credit usage.

  The best setup is:

  **Text → merge → one TTA Smart Column.**
</Note>

<iframe title="Loom video player" />

## Quick option: Merge via smart columns

If the columns you want to combine already exist in your project, you can create the merged smart column in two clicks straight from the **Data** tab.

<Steps>
  <Step>
    On the **Data** tab, select the checkboxes next to **two or more** text columns you want to merge.
  </Step>

  <Step>
    Open the **Add / Replace** dropdown in the top-right and choose **Merge via smart columns**.
  </Step>

  <Step>
    Caplena creates a new **Text-to-analyze** smart column in **Formula** mode, pre-filled with a template that joins the selected columns. You're taken straight to the smart column detail page to review the name, tweak the formula if needed, and click **Create & Fill**.
  </Step>
</Steps>

<Note>
  This shortcut is only available when at least two columns are selected, and when your project still has TTA smart column capacity left. If you've hit the TTA column limit, free up an existing TTA column or contact support before retrying.
</Note>

If you'd rather build the merge step by step, or you want to combine columns with more advanced rules, follow the manual flow below.

## Step 1: Create a New Smart Column

<Steps>
  <Step>
    Go to your **Data** page.
  </Step>

  <Step>
    Click on **"Create New Smart Column."**
  </Step>

  <Step>
    Give your new column a name, for example:\
    `All Feedback Combined` or Unified Feedback.
  </Step>

  <Step>
    Under **Column Type**, choose:\
    `Text-to-analyze` – this will ensure the column is available for AI topic analysis.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot 2026 05 23 At 15 13 06" />
</Frame>

## Step 2: Select Formula Mode

<Steps>
  <Step>
    Choose **Formula** as the Smart Column mode.
  </Step>

  <Step>
    You can use the **Merge Columns template** as a starting point, it’s flexible and can be adapted for any fields you want to merge.

    <Frame />
  </Step>
</Steps>

## \\

Step 3: Pick the Columns You Want to Combine

Choose any text fields you want to analyze together, such as:

This is especially useful when your survey includes **multiple comment fields that touch on the same topic** (e.g., satisfaction, experience, feature requests), and you want to understand the full picture without jumping between columns.

<Frame>
  <img alt="Screenshot 2026 05 23 At 15 15 12" />
</Frame>

## Step 4: Preview & Create

<Steps>
  <Step>
    Click **Generate Sample** to check if the merged text looks right.
  </Step>

  <Step>
    If everything looks good, click **Create & Fill**.

    <Frame>
      <img alt="Screenshot 2026 05 23 At 15 19 05" />
    </Frame>
  </Step>
</Steps>

Caplena will instantly populate your new combined column for all rows.


# Specific Topic Deep-Dive
Source: https://docs.caplena.com/data-project-management/common-smart-columns-intro/specific-topic-deep-dive

Use Smart Columns to Precisely Classify or Extract Topic-Specific Feedback

When analyzing open-text feedback, you may want to isolate comments related to a specific topic, such as pricing, onboarding, churn risk, usability, or billing.

While automatic topic assignment helps explore themes, some use cases require more control over how a topic is defined or extracted.

An LLM-powered Smart Column allows you to apply custom logic to either:

* **Classify comments** (e.g., Yes/No, labels)
* **Extract specific comments** related to a topic
* **Return structured outputs** based on defined criteria
  <iframe title="Loom video player" />

### Practical Use Cases

You might use a Smart Column when you want to:

* Detect **churn risk** only when cancellation intent is clearly expressed
* Flag **pricing complaints** only when dissatisfaction is mentioned
* Extract comments describing **implementation challenges**
* Identify feedback about a **specific process stage** (e.g., onboarding phase)
* Separate **product issues** from **service-related issues**

These scenarios often require stricter logic than topic clustering provides.

### Best Practices

<Steps>
  <Step title="Step 1: Define the Topic Clearly">
    Avoid vague instructions such as:

    > “Extract comments about pricing.”

    Instead, define the scope:

    > Identify comments that refer to pricing structure, subscription costs, perceived value for money, or price transparency.
  </Step>

  <Step title="Step 2: Add Inclusion and Exclusion Criteria">
    Example structured prompt:

    > Determine whether the comment refers to \[TOPIC].
    >
    > <br />
    >
    > <br />
    >
    > Include comments that clearly describe or evaluate defined elements of \[TOPIC].
    >
    > <br />
    >
    > <br />
    >
    > Exclude comments that mention the topic only incidentally or focus primarily on other themes.

    You can then configure the output as:

    * Yes/No classification
    * Summaries
    * Extracted comments
    * Structured categories
  </Step>
</Steps>


# Exporting Your Data
Source: https://docs.caplena.com/data-project-management/data-export/exporting-your-data

Export your project data in the format that fits you best

Caplena makes it easy to export your coded data so you can analyze, share, or report outside the platform. Whether you want a detailed row-by-row file or a high-level summary, you're just a few clicks away.

## Where to export from

You have two main options:

* **From the Topic Assignment view** → export one open-ended question at a time.
* **From the Data page** → export the entire dataset with multiple questions at once.

<Note>
  The steps and options are basically the same wherever you export from. The only difference is how much data you get. When exporting from the Topics view, only the current text-to-analyze column will be included. To export all TTA columns, trigger the export from the Data page.
</Note>

## How to export

<Frame>
  <img alt="Clean Shot 2025 08 21 At 11 11 55 (2)" />
</Frame>

<Steps>
  <Step title="Open the export dialog">
    Open your project and go to the **Topics view**. Click **Export** (top right).
  </Step>

  <Step title="Choose your file type">
    Select your preferred **File type** (Excel, CSV, etc.).
  </Step>

  <Step title="Select the Topic format">
    Choose one of the following formats:

    * **Tabular format with a column per topic** — For each record, topics are marked with their sentiment value (if enabled) in the corresponding column based on the occurrence of a given topic in the text.
      <Frame>
        <img alt="Screenshot 2026 05 23 At 15 31 18" />
      </Frame>
    * **Topics in order of assignment** — Topics are listed one after another in column placeholders in the order they were assigned in the topic view.
      <Frame>
        <img alt="Screenshot 2026 05 23 At 15 32 43" />
      </Frame>
    * **Long format (easy-to-use for BI tools)** — Each topic assignment gets its own row. Each row also includes:
      * *AI Reasoning* — why this topic was assigned to this response
      * *AI Representative Phrases* — the exact text span(s) from the response that triggered the assignment
      <Frame>
        <img alt="Screenshot 2026 05 23 At 15 34 10" />
      </Frame>

    <Tip>
      Use the long format when you need topic-level granularity — for BI tools, deeper analysis, or when you want to see the specific phrases that drove each topic assignment.
    </Tip>
  </Step>

  <Step title="Select data to download">
    Under **Data to download**, pick what you need:

    * Additional columns (metadata you uploaded)
    * Text (original responses)
    * Translated text (if enabled)
    * Topics
    * Metadata (such as review status or highlighted in Caplena, etc.)
  </Step>

  <Step title="Choose topic attributes">
    Select **Topic attributes** like Category or Topic label.
  </Step>

  <Step title="Optional: Advanced settings">
    * **Legacy format** — Single header row; originally an older format for compatibility, but also allows you to export data with the numerical code so you can process it based on the unique numerical code with the topic collection.
      <Frame>
        <img alt="Screenshot 2026 05 23 At 15 38 19" />
      </Frame>
    * **Add category columns** — Adds a column for each category, showing whether a topic from that category is present.
  </Step>

  <Step title="Export">
    Click **Export**, and your file will be ready to go. 🎉
  </Step>
</Steps>

## Exporting your Topic Collection summary

In addition to the row-level export, you can also export a **Topic summary** — a high-level overview of your topic collection.

From the export dialog, click the **Topic summary** tab, select your preferred **File type** (e.g. Excel), and click **Export**.

<Frame>
  <img alt="Screenshot 2026 05 23 At 15 23 47" />
</Frame>

This gives you an aggregated view of your topics rather than a row-by-row breakdown — useful for quickly sharing top-level results.

<Frame>
  <img alt="Screenshot 2026 05 23 At 15 41 58" />
</Frame>

## Exporting with filters

<Frame>
  <img alt="Screenshot 2026 05 23 At 15 43 24" />
</Frame>

Exports respect any filters you apply in the Topics view, so you can download just a subset of your data instead of the full dataset. You can filter by:

* Topics & Categories
* Sentiment
* Reviewed / Highlighted
* Demographics & other variables (Age, Gender, Area, etc.)

<Tip>
  Apply filters first, then export — perfect for sharing targeted subsets, like only negative responses or a specific customer group.
</Tip>

## Topics in order of assignment

This is the most commonly used format and the one you'll see by default. Each response is represented by a single row. Topics are placed in **Topic 1, Topic 2, Topic 3…** columns in the order they were assigned (manually or by AI). If a response has fewer topics, later columns will remain empty — that's normal.\\

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 26 32" />
</Frame>

It's different from order of appearance: instead of reflecting how topics were phrased in the verbatim, it prioritizes clarity for analysis.

<Tip>
  Use this format when you want clean, structured data for reporting or deeper analysis.
</Tip>

## Topics in order of appearance

This format mirrors how respondents expressed themselves. Topics are shown in the exact sequence they appeared in the original text. Each topic is exported as a pair: **Topic Category + Topic Name**. If a verbatim contains many topics, they'll stretch across multiple column pairs.

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 28 08" />
</Frame>

<Tip>
  Choose this format if you want to analyze response flow or phrasing, or keep context for linguistic/narrative analysis.
</Tip>

## BI Tool export

Caplena allows you to seamlessly connect and analyze your data in your preferred BI tools like Power BI, Looker, and Tableau. This guide explains how to export your Caplena data and connect it to those platforms using BigQuery.

<iframe title="Loom video player" />

### Step 1: Choose your data format

You'll be asked to choose between two formats:

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 30 22" />
</Frame>

* **Long Format** — Ideal for working with open-ended text and topic analysis. Each row represents a single topic assignment per response.
* **Wide Format** — More suitable if you're comfortable using Power Query or SQL. All topics are returned in a single row with multiple columns or as arrays.

<Tip>
  If your focus is on qualitative feedback (open-ends and topic sentiment), the long format is generally easier to work with.
</Tip>

<Note>
  The exported data is updated nightly, so if you make changes in Caplena (e.g., assign new topics), those updates will be reflected the next day.
</Note>

### Step 2: Access your export credentials

Once the export is ready, you'll be provided with:

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 32 57" />
</Frame>

* **Account Email**
* **Service Account Key**

You'll use these credentials to connect to the data via **Google BigQuery**, which is Caplena's hosting and data warehouse provider.

### Step 3: Connect your BI tool

**Power BI**

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 35 02" />
</Frame>

1. Open Power BI and go to **Power Query** (via Dataflows or the Desktop App).
2. Click **Add data source** and search for **BigQuery**.
3. Create a new connection using the Account Email and Service Account Key from Caplena.
4. After authentication, navigate to your dataset. It will appear with a name such as `project_960_long_format` (or similar).

**Tableau**

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 36 49" />
</Frame>

1. In **Authentication**, choose **Sign in using Service Account (JSON)**.
2. Upload the `.json` key file.
3. Click **Sign In** and authenticate.
4. Click **Accept** to grant access.

<Tip>
  If you're using Tableau Server or Tableau Cloud, make sure to first log in to the Tableau product and then add your saved BigQuery credentials in account settings. This avoids the common "Invalid credentials" error. [Full guide from Tableau](https://help.tableau.com)
</Tip>

**Looker**

Follow this official guide to configure your connection: [Connecting Looker to BigQuery](https://cloud.google.com/looker/docs/db-config-google-bigquery)

### Step 4: Understand the long format structure

In long format:

* Each response may appear in **multiple rows**, one for each topic assigned.
* Repeated columns (like respondent ID, submission date, or other variables) will remain the same across rows.
* Each row includes:
  * A topic label
  * The sentiment assigned
  * The full response text (if included)
  * Any other quantitative variables (e.g. brand, date, source)

**Example:** One response assigned two topics results in two rows:

| Topic    | Sentiment |
| -------- | --------- |
| Price    | Negative  |
| Coverage | Negative  |

### Step 5: Build your visualizations

Now that the data is available in your BI tool, you can start building visualizations:

* Bar charts of top topics by volume
* Sentiment trends over time
* Filtering by brand, wave, or product line

<Note>
  In long format, duplicate rows for multiple topics may affect calculations like averages or NPS scores. If needed, use de-duplication logic or switch to wide format to avoid duplication.
</Note>


# Data Source Page
Source: https://docs.caplena.com/data-project-management/data-tab-sources/data-source-page

Easily unify feedback from surveys, reviews, and integrations, no matter the source.

Caplena makes it easy to **merge different data sources in a single project**, whether the data is uploaded via file or pulled automatically via integrations. You can:

* **Combine reviews from multiple platforms**, such as the **Apple App Store** and **Google Play Store**, into one cohesive analysis.
* **Mix manually uploaded data (Excel, CSV)** with **integrated data sources** like Amazon or Trustpilot — all in one place.

This allows for a **360° view of your feedback** across channels, perfect for analyzing multiple products, apps, or markets under one project umbrella.

<Tip>
  **Example:** Create one project for a fitness app that includes survey responses from existing users (via Excel upload) and app store reviews (via Google and Apple integrations). This lets you compare internal feedback with public store reviews, all in one place.
</Tip>

## Adding a new data source

To add a new file or connect an integration, click the **"Add data source"** button in the **Data Sources** section of your project. You can either:

* **Upload a file** (`.xls`, `.xlsx`, `.csv`, `.sav`, `.spss`)
* **Select an integration** from platforms like Amazon, Google Play, Trustpilot, etc.

<Frame>
  <img alt="Addingdatasurce" />
</Frame>

After uploading your file or connecting an integration, you'll be asked to **match your columns** to existing ones in the project. Caplena shows:

* The **new columns** you're adding
* The **existing columns** in your project
* Suggested **matches**, especially for text to analyze (TTA), date fields, etc.

If there's no exact match, you'll be prompted to take action.

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 41 30" />
</Frame>

<Note>
  If you **don't want to include a specific column**, simply **uncheck the box** next to it under the *"Keep"* column. This is especially useful for skipping irrelevant metadata like internal IDs or unused tags.
</Note>

## Activity log

The activity log lists recent **file uploads**, including:

* **Date and time** of the upload
* **Name** of the source file
* **Number of rows** added
* **Status** (e.g. Completed, Cancelled)
  <Frame>
    <img alt="Screenshot 2026 05 24 At 10 42 32" />
  </Frame>

<Tip>
  Use this log to track upload history, troubleshoot issues, or ensure your latest data made it in.
</Tip>

## Integrations

This section shows all **active or pending external data connections**, including:

* **Name/label** of the integration
* **Source URL** (e.g. from Trustpilot, Amazon, App Stores, etc.)
* **Type** of integration
* **Row count** (how many reviews have been imported)
* **Sync status** (e.g. Initializing, Completed)

Once initialized, integrations will automatically pull in new data if synchronization is enabled. You can turn synchronization off anytime by toggling it in the integration item settings, or disable it in bulk for all integrations at once:

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 43 38" />
</Frame>


# Data Tab Overview
Source: https://docs.caplena.com/data-project-management/data-tab-sources/data-tab-overview

Everything you can do in Caplena's Data Tab, from editing to exporting

The **Data Tab** is where you view, clean, and manage your dataset in Caplena. Whether you are preparing data for analysis, fixing errors, or customizing the table view, you stay in control without re-uploading files.

## Accessing the Data Tab

To get started, click on **Data** in the sidebar. You'll see an interactive table showing the data you uploaded.

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 47 57" />
</Frame>

The Data Tab includes:

* **Toolbar** – Filter, edit, and customize your dataset
* **Table View** – See rows (responses) and columns (data fields)
* **Checkboxes** – Select rows for bulk actions

## Viewing column details

To inspect a column's full data profile, click on any column header. A Column Details panel will open with two sections.

<Frame>
  <img alt="Clean Shot 2026 06 08 At 17 42 08" />
</Frame>

**Settings**

* **Name** — edit the column's display name directly
* **Favorite** — pin this column to the top of dropdowns and filter menus for faster access
* **Default score** — set this column as the primary scoring reference across your project
* **Sensitive** — mark the column as containing sensitive data (available on auxiliary columns). Only users with the **View sensitive columns** permission can see the toggle, see sensitive columns in project data, and export them. See [object-level permissions](/settings-administration/permissions-deep-dive/object-level-permissions) for details.

**Column content** *(read-only)*

* **Column Ref** — the internal ID
* **Data Type** — e.g. Numerical, Text
* **Populated rows** — how many rows have a value in this column
* **Unique Values Count** — number of distinct values
* **Last Value Added** — timestamp of the most recent entry
* **Data Source** — where the data originated
* **# of Empty Rows** — rows with no value in this column
* **Sample values** — a quick preview of actual entries

<Tip>
  If a column shows a high number of empty rows, check whether the data was imported correctly or whether a Smart Column needs to be re-run.
</Tip>

## Favoriting and hiding columns

These features help you focus on relevant fields without permanently changing your dataset.

### Favorite columns

Mark a column as a favorite to pin it to the top of dropdown menus (e.g. when selecting filters), making it quicker to find and use. This is especially helpful when working with many columns.

<Frame>
  <img alt="Favorite columns in dropdowns" />
</Frame>

When you mark a column as a favorite, it will appear at the top of dropdown menus (e.g., when selecting filters), making it quicker to find and use.

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 50 28" />
</Frame>

### Hide columns

* Click **Show/Hide Columns**
* Uncheck any column you don't want visible
* The table updates immediately

<Frame>
  <img alt="Show or hide columns" />
</Frame>

## Marking columns as sensitive

Use **Sensitive** to restrict who can see a column's values. Sensitive columns are hidden from rows, coding views, and filters for any user who doesn't have the `Projects View Sensitive Columns` permission — even if they otherwise have access to the project.

Typical uses include hiding free-text fields that may contain personal data, internal identifiers, or commercially sensitive responses, while still letting analysts work with the rest of the dataset.

To mark a column as sensitive:

<Steps>
  <Step>
    Click the column header to open **Column Details**.
  </Step>

  <Step>
    Toggle **Sensitive** on.
  </Step>
</Steps>

To remove the sensitive flag, open the same **Column Details** panel and toggle **Sensitive** off. The column's values become visible again to all users with project access.

The toggle is only available on auxiliary columns (not on text-to-analyze columns) and only visible to users with the `Projects View Sensitive Columns` permission. See [Object-level permissions](/settings-administration/permissions-deep-dive/object-level-permissions) for how to grant it.

<Note>
  Marking a column sensitive controls visibility only. To irreversibly remove personal data from text values, use [Anonymization](/get-started/project-settings/anonymization) at upload time.
</Note>

## Editing text fields

You can edit responses or text rows directly from the table, which is helpful for fixing typos or clarifying entries.

<Steps>
  <Step>
    Click the field you want to change
  </Step>

  <Step>
    Make your edits
  </Step>

  <Step>
    Press **Enter**, or click outside the cell to save
  </Step>
</Steps>

<Frame>
  <img alt="Inline edit of a text cell" />
</Frame>

<Danger>
  Each verbatim edit uses 1 credit, as Caplena reprocesses the entry to update insights like sentiment and topics.
</Danger>

## Deleting rows and columns

Use this when you want to permanently remove data you no longer need.

### Delete rows

* Use the checkboxes to select rows
* Click **Delete Rows** in the toolbar
* Confirm deletion

<Frame>
  <img alt="Delete selected rows" />
</Frame>

### Delete columns

* Click **Delete Columns**
* Choose the column to remove
* Confirm the action

<Frame>
  <img alt="Delete columns flow" />
</Frame>

<Tip>
  If you're unsure about removing something, consider hiding the column instead.
</Tip>

## Filtering the table

Use filters to focus on a specific subset of data (e.g., only 5-star reviews or responses from a certain region).

<Steps>
  <Step>
    Click **Filters** in the toolbar
  </Step>

  <Step>
    Select a column
  </Step>

  <Step>
    Choose a condition
  </Step>

  <Step>
    Apply the filter

    <Frame>
      <img alt="Clean Shot 2025 07 20 At 16 43 34 (1)" />
    </Frame>
  </Step>
</Steps>

## Adding or replacing data

Keep your dataset up to date without having to re-upload everything from scratch.

<Frame>
  <img alt="Screenshot 2026 05 24 At 10 53 44" title="Screenshot 2026 05 24 At 10 53 44" />
</Frame>

### Add rows

Appends new data to your existing dataset without affecting existing rows — perfect for continuously adding new feedback over time.

[Read the full article on Adding Data](/data-project-management/adding-replacing-data/append-rows-to-an-existing-project)

### Replace rows

Useful when correcting or updating existing fields.

[Read the full article on Replacing Data](/data-project-management/adding-replacing-data/add-replace-columns-in-your-dataset)

## Exporting data

Once you've cleaned or filtered your dataset, you can export it for further analysis or reporting. Options include exporting the full dataset or only the filtered data.

[Read the full article on Exporting Data](/data-project-management/data-export/exporting-your-data)


# Managing an Existing Project: Settings & Permissions
Source: https://docs.caplena.com/data-project-management/project-management/managing-an-existing-project-settings-permissions

Everything you need to manage your project's privacy, access, and setup, all in one place.

Already created your project? Here's how to adjust permissions, privacy limits, and more, all from one place.

<Tip>
  This guide is for managing settings **after** a project has been created.\
  If you're looking for help setting up a new project (e.g. with translation or anonymization), [check out this article →](/get-started/project-settings/project-settings-overview)
</Tip>

## How to Access Project Settings

To open your settings:

<Steps>
  <Step>
    Open your project in Caplena
  </Step>

  <Step>
    Click the **gear icon** (⚙️) in the left-hand menu
  </Step>

  <Step>
    Switch between **General**, **Permissions**, and **Anonymization** **Permissions**, and **Anonymization** tabs at the top

    <Frame>
      <img alt="CleanShot 2025-07-29 at 10.51.56" />
    </Frame>
  </Step>
</Steps>

## General Tab

Here you can adjust basic project-level behavior related to appearance and privacy.

<Frame>
  <img alt="Screenshot 2026 05 30 At 17 52 09" />
</Frame>

* **Language & Translation Engine**\
  The language and translation engine are selected during project setup. For more information, please [follow this link](/get-started/project-settings/languages-and-translations).

<Warning>
  These **cannot be changed** after the project is created.
</Warning>

* **Selected Theme**\
  Choose the visual theme for your reports. For more information, please [follow this link](/insight-and-reports/creating-and-customizing-reports/custom-theme).
* **Report Case Limit**  \
  A privacy feature that hides insights if there are too few responses for a segment. For more information, please [follow this link](/insight-and-reports/creating-and-customizing-reports/case-limit).

#### **Project Permissions**

These determine what a user can do with the  **project data** and its structure (e.g., topics, coding, imports). For more information, please [follow this link](/settings-administration/understanding-access/introduction-permission-types).

#### Anonymization Tab

<Frame>
  <img alt="Screenshot 2026 07 06 At 12 45 45" />
</Frame>

Update which PII types are anonymized, along with your allow-list and block-list, at any point after the project is created. Changes are saved automatically and apply to **future imports only** — data that has already been imported is not re-processed, and anonymization on existing data cannot be undone.

Editing anonymization requires the **Edit** project permission and a subscription plan that includes anonymization. For details on classes, allow-lists, and block-lists, see the [Anonymization guide](/get-started/project-settings/anonymization).

##


# Smart Columns Overview
Source: https://docs.caplena.com/data-project-management/smart-columns-intro/smart-columns-overview

Transform and enrich your data using mappings, formulas, or LLM prompts

If you want to get truly valuable insights from your data, step one is making sure it’s clean, structured, and enriched with the right information. That’s exactly why we built **Smart Columns.**

With smart columns, you can:

* Recode values into cleaner categories
* Apply formulas to transform data
* Extract new attributes like emotions or brand mentions

There are three modes you can choose from:

<CardGroup>
  <Card title="Mappings" icon="angles-right" href="/data-project-management/smart-columns-intro/smart-columns-overview#mapping" />

  <Card title="Formulas" icon="angles-right" href="/data-project-management/smart-columns-intro/smart-columns-overview#formula" />

  <Card title="LLMs" icon="angles-right" href="/data-project-management/smart-columns-intro/smart-columns-overview#llm" />
</CardGroup>

Let’s go through them step by step.

<iframe title="Loom video player" />

## Quick start

Regardless of the mode you choose, creating your first Smart Column is easy:

1. **Pick your source column** → the data you want to transform (e.g. `Language`, `Text to analyze`, or `Country`).
2. **Choose a mode** → Mapping, Formula, or LLM, depending on your goal.
3. **Configure the transformation** → add logic, mappings, prompts, or formulas.

## Drafts and live columns

Every Smart Column starts as a **draft**. A draft lets you experiment freely — preview results, iterate on the configuration, and tweak prompts or mappings — without using up a Smart Column slot from your plan. Drafts don't compute values for your full dataset and don't appear alongside your live columns in analyses.

<Frame>
  <img alt="Screenshot 2026 06 22 At 08 35 02" />
</Frame>

When you're happy with a draft, **activate** it to make it live. Live columns count against your plan's Smart Column slots, compute values for all rows, and stay in sync as new data is added.

<Frame>
  <img alt="Screenshot 2026 06 22 At 08 37 21" />
</Frame>

<Note>
  Once a Smart Column is live, it cannot be reverted back to a draft. You can still edit a live column's configuration — just keep in mind the change applies immediately. If you no longer need a live column, delete it instead.
</Note>

This means you can keep more drafts than your plan's slot count to try things out, but only activate as many columns as your plan allows.

## How to select your source column

Before anything can be transformed, you need to tell Caplena **which column** to use.

<Frame>
  <img alt="Screenshot 2026 05 30 At 22 14 49" />
</Frame>

**Here's how:**

<Steps>
  <Step>
    Click into the **Expression for "Source Value"** field.
  </Step>

  <Step>
    Click the `{ƒx}` icon to the right — this opens the variable selector.
  </Step>

  <Step>
    Choose from available project variables (like `Text to analyze`, `Country`, etc.).
  </Step>

  <Step>
    Caplena will insert the correct variable syntax automatically.
  </Step>
</Steps>

## 1. Mapping mode

Got inconsistent values that need standardizing? **Mapping mode** is your best friend. You define a source value and map it to a desired output.

### Example

* LV → Latvian
* ❓ Anything else → becomes your **fallback value** (e.g., “Other”)

You can enter mappings manually or upload them as a JSON dictionary, perfect for large sets.

 Once set up, this column auto-updates whenever you upload new data.

## 2. Formula mode

Want to reverse a string, calculate something, or clean up a date? Use **Formula mode**, powered by **Jinja** syntax.

<Note>
  Not a coding wizard? No problem! Ask ChatGPT to write formulas for you.
</Note>

### Example: Reverse a String

To reverse the content of a column (e.g., `Text to analyze`), use:

This formula:

* Converts the string into a list of characters
* Reverses that list
* Joins it back into a string

 **Output:** `Caplena is awesome` → `emosewa si anelpaC`

### Jinja Flavor & Sandbox

Formula mode runs on [Jinja2](https://jinja.palletsprojects.com/) using a **sandboxed environment** (`SandboxedEnvironment`). This means all standard Jinja2 features are available — conditionals, loops, filters, string/number/date manipulation — while unsafe operations (arbitrary Python execution, file access, etc.) are blocked for security. A few things to keep in mind:

* Variables that are **missing** for a row (e.g. a column has no value for that row) are treated as falsy in `{% if %}` checks and as not-equal in comparisons, rather than raising an error.
* Output is always coerced to a string before being parsed into the column's target type (Text, Number, Boolean, Date).
* Empty string output is treated the same as no value — the cell will be left blank.

### Custom Filters

On top of standard Jinja2 filters, Caplena provides the following built-in custom filters:

#### `address_to_coordinates`

Geocodes a free-text address or place name to its `[longitude, latitude]` coordinates using the Mapbox API. **Usage:**

```jinja theme={null}

{{ col_abc123 | address_to_coordinates }}
```

**Returns:** A list `[longitude, latitude]` as floats, e.g. `[8.5417, 47.3769]`. To extract individual components, use Jinja's index access:

```jinja theme={null}

{{ (col_abc123 | address_to_coordinates)[0] }}  {# longitude #}
{{ (col_abc123 | address_to_coordinates)[1] }}  {# latitude #}
```

**Note:** For an accurate coordinate lookup, make sure to always provide full addressees, **including the country** as input value.

Formulas are incredibly flexible for working with numbers, text, dates, or any custom logic you need.

## 3. LLM mode

This mode applies AI models (LLMs) to process free-text inputs, enabling more advanced use cases like summarization or classification.

**Common use cases:**

* Extracting brand names
* Detecting emotion or sentiment
* Removing slurs or sensitive content
* Creating summaries

### Templates Available

Caplena provides a growing **template library** with ready-to-use prompts for common use cases. These templates help you:

* Get started quickly
* Ensure consistent and high-quality results
* Customize further if needed

You can start from a template and then edit the prompt to match your specific use case.

<Frame>
  <img alt="Screenshot 2026 05 30 At 22 16 00" />
</Frame>

## Config history

Every time you change a Smart Column's configuration, Caplena keeps the previous version. **Config history** lets you browse those past versions, compare them with your current setup, and roll back if needed.

### Where to Find It

Open a Smart Column's detail page. A **Config history** button appears in the header **once the column has at least one earlier version** — for a brand-new column with no changes yet, the button stays hidden.

### Compare Versions

Config history shows a timeline that runs from when the column was created through to the **Current version**. Use the **Compare with** selector (or the timeline) to pick any earlier version, then read the two panels side by side: the selected historical configuration on the left and your current configuration on the right. This works for all three modes — Mapping, Formula, and LLM — so you can see exactly what changed (timestamps are shown in your local timezone).

<Frame>
  <img alt="Config history modal" />
</Frame>

### Restore a Version

To roll back, select the version you want and click **Restore Version**. Caplena applies that historical configuration and recomputes the column for new rows.

<Note>
  Restoring is disabled while the column is still computing. Wait for the current run to finish before rolling back.
</Note>

## Delete a smart column

When you no longer need a smart column, you can delete it from the **Smart Columns** tab (row actions) or from the column's detail modal. Caplena gives you two options in the confirmation dialog:

<Frame>
  <img alt="Screenshot 2026 06 22 At 08 41 05" />
</Frame>

* **Delete the smart column only** (default): removes the smart column configuration but keeps the resulting column and its values in your dataset. The column becomes a regular, static column on the Data tab. Use this when you want to "freeze" the computed values — for example, after using a smart column to generate a row ID.
* **Delete the underlying column too**: removes both the configuration and the resulting column, including all of its values. Use this when the column is no longer needed anywhere in the project.

### Deleting the underlying column

Tick **Delete underlying column** in the confirmation dialog to also remove the column itself. Because this affects more than just the smart column configuration, Caplena runs a few extra checks:

<Steps>
  <Step>
    **Impact preview.** Caplena lists any **reports, alerts, or other computed columns** that depend on the column. If a report or alert blocks deletion, you'll see a warning and the **Delete** button stays disabled until you resolve the dependency.
  </Step>

  <Step>
    **Typed confirmation.** Type `Delete` into the confirmation field to enable the **Delete** button. This guard prevents accidental removal of data that is referenced elsewhere.
  </Step>

  <Step>
    **Confirm.** Click **Delete**. Caplena removes the smart column configuration and the underlying column, then refreshes the table.
  </Step>
</Steps>

<Warning>
  Deleting the underlying column permanently removes its values. This cannot be undone — make sure no reports, dashboards, or downstream smart columns still rely on it.
</Warning>

## Best practices

* **Start small**: Test your logic on a small dataset or with a few rows using the preview.
* **Use templates**: Especially for LLM tasks, templates can save time and provide a solid base.
* **Use fallback values**: Always define a fallback in mappings to handle unexpected inputs.
* **Name your columns clearly**: This helps when chaining multiple Smart Columns together.
* **Chain columns**: You can use the output of one Smart Column as the input for another (e.g., extract brand → map to numeric code).
* **Keep prompts concise**: For LLMs, simpler prompts tend to yield more consistent results.


# Chat Conversation Analysis
Source: https://docs.caplena.com/get-started/analyze-chat-conversations/chat-conversation-analysis

Turn raw transcripts into structured, readable conversations.

If you've ever imported a chat transcript and seen it display as one long block of text, you know how hard that is to work with. Caplena can display each message as its own bubble, clearly labeled by speaker, just like a real conversation thread.

<Frame>
  <img alt="Chat conversation view" />
</Frame>

***

### How It Works

Three things need to be in place for chat parsing to work:

<CardGroup>
  <Card title="Speaker Labels" icon="tag">
    Tell Caplena who said what. Every message must start with one.
  </Card>

  <Card title="Column Configuration" icon="sliders">
    Tell Caplena which labels to look for. Without this, the column shows as plain text.
  </Card>

  <Card title="Consistent Formatting" icon="align-left">
    Ensure every row follows the same pattern so every message gets parsed correctly.
  </Card>
</CardGroup>

If all three are in place, Caplena renders the conversation as structured chat. If it can't reliably detect the structure, it falls back to the original text — nothing gets lost, but the structured view is much easier to read and analyze.

***

### Supported Formats

#### Speaker labels only

The most common format. Each message starts with a label, followed by the message text:

```text theme={null}
<<USER>> Hello<<BOT>> Hi!
Alice Miller: Hallo
Peter Smith: Salve
[Agent] Hello
>>Customer>> Hi there
```

#### Speaker labels with timestamps

Timestamps before the speaker label are fully supported. Caplena handles the most common date and time formats automatically:

```text theme={null}
[12:34] <<USER>> Hello
[12:35] <<BOT>> Hi!
03.12.2023, 18:01:56: Alice Miller: Hallo
[03.12.2023, 18:37:56] Peter Smith: Salve
03/12/2023, 6:01 PM - Alice Miller: Hallo
2023-12-03T18:01:56Z <<USER>> Hello
```

<Tip>
  **The golden rule:** as long as every message starts with a recognizable label and that label is configured in Caplena, the transcript will parse correctly.
</Tip>

<Note>
  Not sure if your format will parse? [Download the sample file →](/hubfs/chat_transcripts_test.xlsx?hsLang=en) — it covers every supported format with real examples and shows exactly which speaker labels to configure for each one.
</Note>

***

### Configure Speaker Labels

To enable chat parsing, tell Caplena which speaker labels appear in your data. This is done in column settings.

1. Open your project and go to **Project Settings**
2. Enable the **Chatbot conversation** toggle — this unlocks the speaker configuration fields
3. Under **Define who is speaking in your data**, click **+ Add speaker**
4. For each speaker, fill in:
   * **Speaker name** – a display label (e.g. *User*, *Agent*). For display only.
   * **Speaker identifier** – the **exact prefix string as it appears in your data** (e.g. `<<USER>>`, `Question:`, `Jon Doe:`)
   * **Position** – whether the speaker's bubbles align **Left** or **Right**, just like a messaging app (e.g. customer on the left, agent on the right).
   * **Color** – a bubble color so each speaker is easy to tell apart at a glance.
5. Add one entry per speaker. You can have up to 10.

<Frame>
  <img alt="Speaker editor with name, identifier, position, and color" />
</Frame>

The **Position** and **Color** styling applies everywhere chat transcripts are shown — the topic assignment row list, coding drawer, focus mode, and the row widgets in reports.

<Tip>
  You don't have to set position and color manually — when Caplena detects the speakers it assigns sensible defaults automatically, alternating left/right so conversations stay readable. Adjust them only when you want something different.
</Tip>

The **Position** and **Color** styling applies everywhere chat transcripts are shown — the topic assignment row list, coding drawer, focus mode, and the row widgets in reports.

<Tip>
  You don't have to set position and color manually — when Caplena detects the speakers it assigns sensible defaults automatically, alternating left/right so conversations stay readable. Adjust them only when you want something different.
</Tip>

<Warning>
  The Speaker identifier field is a **free-text input**. Type the exact prefix from your data, including any brackets, colons, or special characters. Caplena matches character by character — a missing colon or extra space will prevent parsing.
</Warning>

<Tip>
  Copy a real line from your data and paste just the prefix into the Speaker identifier field to avoid typos.
</Tip>

***

### Troubleshooting

<AccordionGroup>
  <Accordion title="The conversation isn't showing as chat messages">
    **Why this happens:** Speaker labels either weren't configured or don't exactly match the data.

    **What to check:** Take one real row from the dataset and compare it character by character with what's been configured. Pay close attention to spaces, brackets, colons, and capitalization. Then check a handful of other rows to confirm the same format is used throughout — different styles across rows can prevent parsing.
  </Accordion>

  <Accordion title="Messages are getting merged together">
    **Why this happens:** When a line doesn't start with a recognized speaker label, Caplena treats it as a continuation of the message above.

    **What to check:** Look for label variations that haven't been configured — a third speaker, a bot with a slightly different label, or a line that was formatted differently. Make sure every label variation that appears in the data has been added to the column configuration.
  </Accordion>

  <Accordion title="The raw transcript keeps showing up">
    **Why this happens:** When the format is too inconsistent to parse reliably, Caplena falls back to the original text rather than risk splitting messages incorrectly.

    **What to check:** Look for rows that use a different pattern — a different label style, a different timestamp format, or a mix of both. Standardizing those outlier rows before import will usually resolve it.
  </Accordion>

  <Accordion title="Translated messages are missing structure">
    **Why this happens:** Translations sometimes strip or reformat speaker labels, so the translated transcript loses the structure needed for chat parsing.

    **What to check:** Compare an original row and its translated counterpart side by side. If labels are missing or reformatted in the translated version, the structured chat view won't be available for that content.
  </Accordion>
</AccordionGroup>


# File Import
Source: https://docs.caplena.com/get-started/file-import

How to prepare and upload your dataset to Caplena.

### Preparing Your File

Format your file using these guidelines before uploading:

<Frame>
  <img alt="Clean Shot 2026 05 18 At 15 49 33@2x" />
</Frame>

* Each **row** should represent one individual record, a respondent, review, or feedback entry
* The **first row** must contain **column headers** (variable names or question labels)

<Tip>
  If your file has more than one header row (e.g. the first row with variable names, the second with descriptions), merge them into one row or remove the extra before uploading.
</Tip>

**Accepted formats:** `.xls` `.xlsx` `.csv` `.txt` `.spss` `.sav`

<Warning>
  Password-protected Excel files (`.xls`, `.xlsx`) can't be uploaded. Remove the password in Excel (**File → Info → Protect Workbook → Encrypt with Password**, then clear the password and save) before uploading.
</Warning>

***

### Understanding Column Types

#### Text-to-Analyze (TTA)

This is where Caplena applies its AI analysis. TTA columns should contain open-ended responses — customer feedback, survey comments, or reviews.

In the screenshot above, the green-highlighted *"Reason for Rating"* column is a TTA column. Caplena supports up to **25 open-text columns** per project, each treated individually — no need to create separate projects per question.

<Tip>
  Keep each TTA column clear and focused. Avoid combining unrelated responses unless they logically belong together.
</Tip>

#### Other Columns

Other columns provide context but are not analyzed by AI. They're optional but highly recommended to enrich your analysis.

<CardGroup>
  <Card title="Metadata" icon="user">
    Age, gender, customer segment, region
  </Card>

  <Card title="Identifiers" icon="fingerprint">
    Response ID, user ID
  </Card>

  <Card title="Closed-ended" icon="list-check">
    NPS score, star ratings, yes/no answers
  </Card>
</CardGroup>

Use these columns to **segment** responses by group or **filter** feedback during fine-tuning and reporting.

<Note>
  You're only billed for TTA columns, other columns are free.
</Note>

***

### Working with Dates

Include a date column if you'd like to filter or trend results over time.

<Frame>
  <img alt="Date column example" />
</Frame>

**Supported formats:**

| Format       | Example    |
| ------------ | ---------- |
| `YYYY-MM-DD` | 2022-01-30 |
| `DD.MM.YYYY` | 30.01.2022 |
| `DD/MM/YYYY` | 30/01/2022 |

<Warning>
  US-style dates (`MM/DD/YYYY`) are not supported. Convert them to a day-first format before uploading.
</Warning>

Caplena automatically converts valid formats to ISO (`YYYY-MM-DD`) and supports timestamps (e.g. `2022-01-30 14:35:00`).

**Timezone handling**

Date-time values without a specified timezone are interpreted as **UTC**. In the Data tab, hovering over a date-time entry shows the original UTC value; individual row views display time in **your local timezone**. If your data includes a timezone, Caplena will respect it.

<Frame>
  <img alt="Timezone display" />
</Frame>

***

### Merging Multiple Columns

If several columns relate to the same question, merge them before uploading using Excel's `CONCATENATE` function:

```excel theme={null}
=CONCATENATE(A2," || ",B2)
```

The `||` separator helps Caplena identify content from different sources. Add as many cells as needed.

<Frame>
  <img alt="Merging columns in Excel" />
</Frame>

<Tip>
  You can also use Smart Columns inside Caplena after import,  no need to modify your file.
</Tip>

***

### Uploading Your File

<iframe title="Loom video player" />

Drag and drop your file into the upload box, or click to browse your device. Caplena will guide you through the next steps automatically.

### Finalizing Your Data Setup

After uploading, Caplena takes you to the **Organize Your Data** screen to configure everything before analysis begins.

**1. Select the right columns**

Use the checkboxes to include the columns you need. Use the filter bar to quickly find specific columns in larger datasets.

<Tip>
  Make sure your main TTA column is selected — it's required for AI analysis.
</Tip>

**2. Understand column types**

Each column is automatically detected and categorized:

| Type                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| TTA (Text to Analyze) | The main open-text field(s) Caplena will analyze   |
| Text Columns          | Fields used for filtering, like age or region      |
| Date Columns          | Used for time-based filtering or trend analysis    |
| Numerical Columns     | Numeric data such as employee count or survey wave |

**3. Preview your data**

Check the sample data shown for each column to confirm formatting — especially for dates and numeric values.

**4. Finalize**

* **Validate** – confirm and continue
* **Back** – re-upload your file if something looks wrong
* **Cancel** – exit without saving changes


# Quick Start
Source: https://docs.caplena.com/get-started/getting-started-with-caplena

Turn open-ended feedback into actionable insights in minutes.

Caplena helps you quickly turn open-ended survey responses, reviews, and other unstructured text into clear, actionable insights. This quick-start guide will walk you through the essentials so you can start uncovering what really matters in your data.

## 🎥 Prefer Video?

Watch a quick video below for a guided demo:

<iframe title="Loom video player" />

***

## Step 1: Create a New Project

1. From your **Project List**, click **New Project**
2. Enter a **project name** (e.g., *NPS Survey Analysis*)
3. *(Optional)* Add **project context** – e.g., the goal, audience, or product you're analyzing. This helps generate more relevant insights
4. Set the **project language** (this determines how responses are analyzed)
5. *(Optional)* Enable:
   * **Translation** – if your data includes multiple languages
   * **Anonymization** – to automatically mask personal information

[Learn more about project setup →](/get-started/starting-a-new-project/setting-up-a-project)

***

## Step 2: Upload and Validate Your Data

1. Upload your file (Excel, CSV, etc.) or connect an integration
2. Caplena will auto-detect open text columns. Select which ones to analyze
3. You can use additional columns (e.g., age, gender) for filtering/segmentation
4. Click **Validate**, then **Continue**

<Tip>
  Keep an ID column if you'll re-upload updates later.
</Tip>

[Learn more about data upload →](/get-started/file-import)

***

## Step 3: Generate Topics with AI

1. Click **Start Analysis**
2. Choose one of the following:
   * **Start from scratch** – Caplena auto-generates topics
   * **Import** a predefined topic collection
   * **Reuse** topics from a previous project
3. Review the topic structure. Caplena organizes topics into categories. You can:
   * Rename, merge, or delete topics
   * Update topic descriptions
   * Create custom categories

If **sentiment detection** is enabled, comments are automatically marked as *positive*, *neutral*, or *negative*.

[Learn more about topic generation →](/topic-assignment/understanding-the-basics/starting-the-analysis)

***

## Step 4: Review AI Assignments

1. Open the **Topics** view
2. **Check topic descriptions** to make sure they make sense
3. **Check coverage** – if \~90% of rows have topics, you're in great shape
4. **Spot-check 10–15 responses** to make sure assignments make sense
5. *(Optional)* Use **AI certainty** – rows with low confidence might reveal topics that need better descriptions
6. **Focus on weak spots** – review topics with low coverage or unclear descriptions

<Tip>
  Improving topic quality leads to stronger insights in reports.
</Tip>

[Learn more about fine-tuning →](/topic-assignment/new-ai/how-to-ensure-high-quality-results-with-the-new-llm)

***

## Step 5: Visualize & Share Insights

1. Go to **Reports** and create a new one (from scratch or a template)
2. Use **Edit Mode** to customize charts or apply filters
3. Create **segments** to compare groups or timeframes
4. Share reports with internal or external stakeholders

[Report-building guide →](/insight-and-reports/creating-and-customizing-reports/creating-reports)

***

## Step 6: Ask Questions with Insight Agent

Use **Insight Agent** to explore your data using natural language. Just type your question, e.g.:

> "What are customers saying about delivery time?" "Why are promoters happy?"

Get quick answers and discover trends without manual digging.

<Tip>
  Perfect for quick deep-dives or stakeholder demos.
</Tip>

[Insight Agent overview →](/insight-and-reports/insight-agent/insight-agent)


# Network Requirements
Source: https://docs.caplena.com/get-started/network-requirements

Find out which domains to whitelist to ensure Caplena works on corporate networks.

**Firewall & Network Requirements** *Ensure Caplena works smoothly on corporate networks*

If you're experiencing issues loading Caplena, or receiving emails, this is often caused by network restrictions such as firewalls, proxy settings, or domain blocking.

Please ask your IT team to whitelist the following domains:

| Domain                  | Purpose                 |
| :---------------------- | :---------------------- |
| `caplena.com`           | Main domain             |
| `www.caplena.com`       | Website                 |
| `app.caplena.com`       | Application             |
| `api.caplena.com`       | API                     |
| `docs.caplena.com`      | Documentation           |
| `changelog.caplena.com` | Product updates         |
| `email.caplena.com`     | Transactional emails    |
| `hs.caplena.com`        | Support & live chat     |
| `ph.caplena.com`        | Product analytics       |
| `trust.caplena.com`     | Trust & security portal |

Allowing these domains should resolve most access, loading, or email delivery issues.

<Tip>
  > **Still having issues?** Contact us at [support@caplena.com](mailto:support@caplena.com) and we'll help you identify what's being blocked.
</Tip>


# Anonymization
Source: https://docs.caplena.com/get-started/project-settings/anonymization

Protect personal data and safely analyze or share sensitive feedback.

Enable anonymization to automatically remove **personally identifiable information (PII)** from your text before analysis, keeping you compliant with GDPR and other privacy regulations.

<Warning>
  Anonymization **cannot be undone**. Only the anonymized version is stored in Caplena. The original data is automatically and permanently deleted from Caplena's servers within 7 days of upload.
</Warning>

***

### Enabling Anonymization

Anonymization is configured when creating a new project:

1. Click **New Project** and proceed through the upload flow
2. At the **Anonymization** step, toggle it on
3. Select which PII types to anonymize (see below)
4. Click **Continue** to proceed with your import

<Note>
  Anonymization is a plan-gated feature. If your subscription doesn't include anonymization, creating a project with it enabled is blocked. Contact support to upgrade your plan.
</Note>

<iframe title="Loom video player" />

***

### Editing Anonymization Settings After Setup

You can update a project's anonymization settings at any time from **Project Settings → Anonymization**.

<Steps>
  <Step>
    Open your project and click the **gear icon** (⚙️) in the left-hand menu
  </Step>

  <Step>
    Switch to the **Anonymization** tab
  </Step>

  <Step>
    Adjust the enabled PII classes, advanced settings, allow-list, or block-list. Changes are saved automatically.
  </Step>
</Steps>

<Warning>
  Changes apply to **future imports only**. Data already imported into the project is not re-processed, and previously anonymized text cannot be restored — anonymization on existing data cannot be undone.
</Warning>

Editing anonymization requires the **Edit** project permission and a subscription plan that includes anonymization.

**What you can change:** the enabled PII classes (including advanced classes), the allow-list, and the block-list.

***

### Choosing What to Anonymize

Once enabled, a settings panel lets you select the PII types to mask:

<Frame>
  <img alt="Anonymization settings panel" />
</Frame>

For more granular control, click **Advanced Settings** to include additional PII types (ZIP code, religion, gender, and more), add custom sensitive data fields, or tailor anonymization to industry-specific compliance requirements.

<Frame>
  <img alt="Advanced anonymization settings" />
</Frame>

***

### Allow-list & Block-list

Fine-tune anonymization behavior with two optional lists:

**Allow-list** — Terms that should *never* be anonymized, even if they look like names (e.g. `Smith`, `John Doe`).

**Block-list** — Terms that should *always* be anonymized, even if they aren't names (e.g. `is`, `very curious`).

To add terms, click **"Add term"** or paste a list directly from Excel. Matching is **case-insensitive** and **whole-word only** — partial matches are ignored.

| Input                 | Output                          | Notes                                    |
| --------------------- | ------------------------------- | ---------------------------------------- |
| Hello Mr **Smith**    | Hello Mr **Smith**              | Exact match; preserved due to allow-list |
| Hello Mr **smith**    | Hello Mr **smith**              | Case-insensitive match; preserved        |
| Hello Mr **Smithson** | Hello Mr **\[NAME\_FAMILY\_1]** | Not an exact match; anonymized           |
| I am **John Doe**     | I am **John Doe**               | Exact match; preserved                   |
| **Doe**               | **\[NAME\_1]**                  | Not a full match; anonymized             |

**Block-list example** — `is` and `very curious` configured as blocked terms:

| Input                        | Output                                 | Notes                                 |
| ---------------------------- | -------------------------------------- | ------------------------------------- |
| This **is** the Smith family | This **\[CUSTOM\_1]** the Smith family | "is" is in the block-list; anonymized |
| I am **very curious**        | I am **\[CUSTOM\_1]**                  | Exact phrase match; anonymized        |
| Just **curious**             | Just **curious**                       | Not a full match; not anonymized      |

***

### Address vs. Location

Caplena distinguishes between two related but different PII types:

| Type         | What it captures                                        | Example                               |
| ------------ | ------------------------------------------------------- | ------------------------------------- |
| **Address**  | Structured location formats — street, number, ZIP, city | `25 Oxford Street, London W1D 2LF`    |
| **Location** | General geographic mentions or landmarks                | `Central Park`, `Northern California` |

> "I visited **Lake Victoria**." → with *Location* enabled → "I visited **\[location]**."
>
> "I live at **12 Abbey Road, 23783 London**." → with *Address* enabled → "I live at **\[address]**."

How Address, Street, City, and ZIP interact:

| Option            | Example (Original Text)                                                                                 | Output                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Address only      | "Anna Smith, 742 Evergreen Terrace, Springfield, IL 62704, [anna@example.com](mailto:anna@example.com)" | "Anna Smith, \[LOCATION\_ADDRESS\_1], [anna@example.com](mailto:anna@example.com)" |
| ZIP/Postcode only | "742 Evergreen Terrace, IL 62704"                                                                       | "742 Evergreen Terrace, \[postal code]"                                            |
| City only         | "I moved to London last year."                                                                          | "I moved to \[city] last year."                                                    |
| Street only       | "She lives at Oxford Street."                                                                           | "She lives at \[street]."                                                          |

<Danger>
  If you anonymize too much or something goes wrong, you'll need to re-upload the data in a new project. Reach out to support — we're happy to help and will reimburse credits if needed.
</Danger>

***

### Anonymization & Translation

Anonymization runs **before translation**. Anonymized source text will also produce anonymized translations — the two features work seamlessly together.

<Note>
  Not all languages are currently supported for anonymization. Texts in unsupported languages may be only partially anonymized.
</Note>

**Supported languages:**

| Language                | ISO Code |
| ----------------------- | -------- |
| Afrikaans               | af       |
| Arabic                  | ar       |
| Bambara                 | bm       |
| Belarusian              | be       |
| Bengali                 | bn       |
| Bulgarian               | bg       |
| Burmese                 | my       |
| Cantonese (Traditional) | zh-TW    |
| Catalan                 | ca       |
| Croatian                | hr       |
| Czech                   | cs       |
| Danish                  | da       |
| Dutch                   | nl       |
| English                 | en       |
| Estonian                | et       |
| Finnish                 | fi       |
| French                  | fr       |
| Georgian                | ka       |
| German                  | de       |
| Greek                   | el       |
| Hebrew                  | he       |
| Hindi                   | hi       |
| Hungarian               | hu       |
| Icelandic               | is       |
| Indonesian              | id       |
| Italian                 | it       |
| Japanese                | ja       |
| Khmer                   | km       |
| Korean                  | ko       |
| Latvian                 | lv       |
| Lithuanian              | lt       |
| Luxembourgish           | lb       |
| Malay                   | ms       |
| Mandarin (Simplified)   | zh-CN    |
| Moldovan                | ro       |
| Norwegian (Bokmål)      | nb       |
| Persian (Farsi)         | fa       |
| Polish                  | pl       |
| Portuguese              | pt       |
| Punjabi                 | pa       |
| Romanian                | ro       |
| Russian                 | ru       |
| Slovak                  | sk       |
| Slovenian               | sl       |
| Spanish                 | es       |
| Swahili                 | sw       |
| Swedish                 | sv       |
| Tagalog                 | tl       |
| Tamil                   | ta       |
| Thai                    | th       |
| Turkish                 | tr       |
| Ukrainian               | uk       |
| Vietnamese              | vi       |


# Languages and Translations
Source: https://docs.caplena.com/get-started/project-settings/languages-and-translations

Enable automatic translation and work with multilingual data across your project.

Caplena supports automatic translation through **DeepL** and **Google Translate**, letting you analyze multilingual datasets in a single unified language. Enable it in project settings with one toggle.

<iframe title="Loom video player" />

All text-to-analyze columns will be translated into the **Main Language** selected during project setup.

<Tip>
  Set your Main Language to the same language you'll use for your topic collection. This ensures topics and translations stay aligned.
</Tip>

<Note>
  Translation fees are included in your subscription and Ad-Hoc credits — no additional charges apply.
</Note>

***

### When to Enable Translation

Turn on automatic translation if any of the following apply:

* Your dataset contains **multiple languages** (e.g. English, German, and Chinese in the same file)
* Your text is in a language **not natively supported** by Caplena
* Your topic collection needs to be in a **different language** than the source text
* You don't speak the language your responses are written in

***

### DeepL vs. Google Translate

DeepL generally produces higher quality translations but supports a smaller set of languages. When DeepL is selected, Caplena uses it where supported and automatically falls back to Google Translate for everything else.

| Language                                                                 | Google Translate | DeepL |
| ------------------------------------------------------------------------ | :--------------: | :---: |
| Afrikaans                                                                |         ✓        |       |
| Albanian                                                                 |         ✓        |       |
| Arabic                                                                   |         ✓        |       |
| Bulgarian                                                                |         ✓        |   ✓   |
| Chinese (Simplified)                                                     |         ✓        |   ✓   |
| Chinese (Traditional)                                                    |         ✓        |       |
| Czech                                                                    |         ✓        |   ✓   |
| Danish                                                                   |         ✓        |   ✓   |
| Dutch                                                                    |         ✓        |   ✓   |
| English                                                                  |         ✓        |   ✓   |
| Estonian                                                                 |         ✓        |   ✓   |
| Finnish                                                                  |         ✓        |   ✓   |
| French                                                                   |         ✓        |   ✓   |
| German                                                                   |         ✓        |   ✓   |
| Greek                                                                    |         ✓        |   ✓   |
| Hungarian                                                                |         ✓        |   ✓   |
| Indonesian                                                               |         ✓        |   ✓   |
| Italian                                                                  |         ✓        |   ✓   |
| Japanese                                                                 |         ✓        |   ✓   |
| Latvian                                                                  |         ✓        |   ✓   |
| Lithuanian                                                               |         ✓        |   ✓   |
| Malay                                                                    |         ✓        |       |
| Polish                                                                   |         ✓        |   ✓   |
| Portuguese                                                               |         ✓        |   ✓   |
| Punjabi                                                                  |         ✓        |       |
| Romanian                                                                 |         ✓        |   ✓   |
| Russian                                                                  |         ✓        |   ✓   |
| Slovak                                                                   |         ✓        |   ✓   |
| Slovenian                                                                |         ✓        |   ✓   |
| Spanish                                                                  |         ✓        |   ✓   |
| Swedish                                                                  |         ✓        |   ✓   |
| Thai                                                                     |         ✓        |       |
| Turkish                                                                  |         ✓        |   ✓   |
| Vietnamese                                                               |         ✓        |       |
| [All other languages](https://cloud.google.com/translate/docs/languages) |         ✓        |       |

***

### Language Detection

By default, Caplena auto-detects the source language of each entry. This works well for most text, though single-word entries may occasionally be misidentified.

**Specifying source language manually**

If you know the source language, add a dedicated column to your file using [ISO 639-1 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) (e.g. `en`, `de`, `ja`). During upload, set that column type to **Source language**.

<Frame>
  <img alt="Source language column setup" />
</Frame>

A few things to watch out for:

* Caplena may auto-detect the column as a Text column — adjust it manually before confirming the upload if needed
* For multilingual countries (e.g. Switzerland, Belgium), **leave the cell blank** if unsure — Caplena falls back to auto-detection for that row
* Language codes must be **lowercase ISO 639-1** — common mistakes: Japanese is `ja` not `jp`, Austrian German is `de` not `at`

***

### Viewing Translations in the App

Translations are accessible throughout Caplena — you're never locked into one view.

**Fine-tuning view**

<Frame>
  <img alt="Fine-tuning translation toggle" />
</Frame>

Each comment shows both the translated and original text. Use the **"See original / See translated"** toggle in the bottom-right corner of each comment. The translated version is shown by default.

**Visualizations**

<Frame>
  <img alt="Verbatim browser with translation" />
</Frame>

Charts are interactive — click any element to open the verbatim browser showing all comments behind that topic. Switch between original and translated versions directly within the browser.

**Data export**

<Frame>
  <img alt="Export with translation options" />
</Frame>

Translations are included by default in all data exports. Under **Advanced Export Options** you can reposition the translation column or exclude it entirely.


# Project Settings Overview
Source: https://docs.caplena.com/get-started/project-settings/project-settings-overview

A complete guide to project settings in the Caplena setup flow.

Getting your project settings right takes less than two minutes, and it makes a real difference. The details you enter here shape how Caplena's AI understands your data, generates topics, and surfaces insights.

<iframe title="Loom video player" />

**Project Name** — Choose something clear and descriptive. Helpful when managing multiple projects.

**Tags** *(optional)* — Categorize and filter projects using tags like `NPS`, `Customer Service`, or `Q1 2025`.

**Main Language** — The language topics will be generated in. Even with multilingual data, pick the one language you want to work in.

**Project Theme** — Sets the color scheme used across your reports.

***

**Project Context** *(optional)*

This is one of the most impactful fields in setup. The more context you give, the more relevant the AI-generated topics will be. Think of it as a brief for the AI.

<Note>
  **Example:** "This is an annual NPS survey targeting B2B clients in North America. We're trying to identify main drivers behind promoter/detractor ratings."
</Note>

**Anonymize Text Comments** *(optional)*

Enable if your dataset contains PII — names, emails, phone numbers. Caplena masks sensitive details before analysis to keep you GDPR compliant.

[Read more about Anonymization →](/get-started/project-settings/anonymization)

***

**Automatic Translation** *(optional)*

Enable if your dataset includes multiple languages. Caplena translates everything into your Main Language before analysis — one unified view across your entire dataset.

<Tip>
  If you're analyzing mixed-language data, enable **Automatic Translation** — Caplena handles the rest.
</Tip>

[Read more about Translation →](/get-started/project-settings/languages-and-translations)


# Setting a Project to Live
Source: https://docs.caplena.com/get-started/project-settings/setting-a-project-to-live

How to make a project available for querying through outbound integrations

Before a project can be queried through any outbound connector, such as Slack, Microsoft Teams, Claude Desktop, it needs to be set to **Live**. This is a deliberate step that gives you control over which projects are accessible externally.

<Tip>
  **Note:** *Setting a project to Live does not change anything about how the project works inside Caplena. It only makes it available for querying through connected outbound tools.*
</Tip>

### How to Set a Project to Live

* Open the project in Caplena.
* Go to **Overview**.
* Find the **Live Project** toggle and switch it on.
  <Frame>
    <img alt="Screenshot 2026 05 28 At 10 42 40" />
  </Frame>

Once enabled, the project becomes immediately available to any outbound connectors you have set up.

### Where This Setting Is Required

You’ll need to set a project to Live before using it with any of the following integrations:

| **Integration**          | **What it enables**                                             |
| :----------------------- | :-------------------------------------------------------------- |
| **Slack**                | Query your feedback data directly from a Slack channel.         |
| **Microsoft Teams**      | Ask the Caplena bot questions about your projects inside Teams. |
| **Claude Desktop (MCP)** | Query projects using natural language through Claude.           |

### Turning Live Off

You can disable Live at any time by switching the toggle back off. The project will immediately stop being accessible through outbound connectors, nothing inside Caplena is affected.


# Semi-Open Mode: Quick Guide
Source: https://docs.caplena.com/get-started/starting-a-new-project/semi-open-mode-quick-guide

Analyze list-based responses quickly and consistently.

Semi-open mode is designed for **structured open-text questions** where responses follow a **limited and repeatable pattern** — think brand awareness surveys, competitor lists, or short 1–3 word answers.

Rather than exploring themes, Semi-Open mode focuses on standardizing similar answers, grouping variations of the same term, and creating clean, consistent categories.

<Frame>
  <img alt="Screenshot 2026 05 18 At 15 24 22" />
</Frame>

**Typical use cases:**

* Brand awareness ("Which brands do you know?")
* List-based answers (products, competitors, sources)
* Short, repetitive responses

***

## Step 1: Select Your Text Columns

Before starting the analysis, decide how to handle your columns:

<CardGroup>
  <Card title="Analyze Separately" icon="table-columns">
    Select each column as **Text-to-Analyze (TTA)**. Use this when you want to **compare results across questions**.

    <Note>
      Each TTA column is analyzed separately and consumes credits.
    </Note>
  </Card>

  <Card title="Combine Columns" icon="merge">
    Use **Smart Columns** to merge multiple columns into one unified analysis. Best when columns contain the **same or very similar question**.

    [Smart Columns guide →](/data-project-management/common-smart-columns-intro/how-to-combine-multiple-columns-for-joint-analysis)
  </Card>
</CardGroup>

***

## Step 2: Start the Analysis

<Frame>
  <img alt="Starting analysis" />
</Frame>

Choose how to build your topic structure:

* **Start from scratch** – AI generates initial topics and categories automatically
* **Reuse existing structure** – Import a topic collection or reuse categories from another project

***

## Step 3: Configure Key Settings

<Frame>
  <img alt="Screenshot 2026 05 18 At 15 27 58" />
</Frame>

**Term Similarity**

Controls how strictly terms are grouped together.

| Value | Behavior                                              |
| ----- | ----------------------------------------------------- |
| 100%  | Exact matches only                                    |
| \~75% | Groups similar variations (e.g. spelling differences) |

**Minimum Count**

Defines how often a term must appear to become its own topic. For example, setting this to `2` means only terms mentioned at least twice will appear as separate topics.

**"Other" Topic**

Controls how low-frequency responses are handled:

| Option          | Description                              |
| --------------- | ---------------------------------------- |
| None            | No "Other" topic created                 |
| Unassigned Rows | Only responses without any topic         |
| Rare Terms      | Low-frequency terms grouped into "Other" |

When **Unassigned Rows** or **Rare Terms** is selected, you can assign a custom **code ID** (any integer ≥ 0) to the "Other" topic — useful when exporting results and aligning topic codes with an existing coding scheme.

<Note>
  You can modify the **Term Similarity**, **"Other" topic handling**, and the **"Other" code ID** at any time from the question’s **Settings** menu in the topic assignment view.

  Changes are saved automatically and will take effect during the next topic assignment run.
</Note>

<Frame>
  <img alt="Screenshot 2026 06 22 At 13 48 13" />
</Frame>

## Step 4: Review Topics & Keywords

Before finalizing, review and fine-tune your topics and keywords to ensure accurate results.

**Review Topics**

* Confirm each topic represents a **distinct answer or concept**
* Rename topics to improve clarity
* Merge duplicates and remove irrelevant topics

**Adjust Keywords**

Each topic uses keywords to assign responses correctly. To edit them, click on a topic and open the keyword list.

<Frame>
  <img alt="Screenshot 2026 05 18 At 15 31 30" />
</Frame>

Best practices for keywords:

* **Include abbreviations** – e.g. "FB" for Facebook
* **Add spelling variations** – e.g. "McDonalds", "Mc Donald's"
* **Include common phrasing** – different ways users might refer to the same concept
* **Be specific** – especially for similar or overlapping topics

<Warning>
  Keywords have a maximum length of 30 characters including spaces. If a keyword exceeds this limit, it will not trigger assignments — shorten it or split it into a shorter variation.
</Warning>

<Note>
  Punctuation doesn't matter — "Iqos, TEREA, Plum" works the same as "Iqos TEREA Plum". Only `||` is treated as a separator.
</Note>

**How keyword matching works**

The system always matches the **most specific keyword** in the text. If two keywords overlap, the longer one wins.

> **Example:** Keywords are `Tesla` and `Tesla Model 3`. For the text *"I like my Tesla Model 3"*, the system matches **Tesla Model 3 ✅** and ignores `Tesla` since the longer keyword already covers it.

## How Semi-Open Learns from Your Input

Semi-Open mode updates assignments automatically as you refine your codebook. Two things trigger reassignment:

* **Keyword changes** — adding or editing keywords on a topic causes Caplena to re-evaluate all rows against the updated keyword list within a few minutes.
* **Manual reviews** — when you manually assign a topic to a row and mark it as reviewed, the system learns from that correction and applies the same logic to similar unreviewed rows.

<Note>
  After making changes, assignments update automatically in the background — you don't need to trigger a manual run. If you don't see the changes reflected immediately, refresh the page.
</Note>

<Tip>
  Keywords are the most efficient way to control assignments at scale. Manual reviews are useful for edge cases and exceptions that keywords alone can't reliably capture.
</Tip>

## Video Walkthrough

<iframe title="YouTube video player" />

***


# Setting Up a Project
Source: https://docs.caplena.com/get-started/starting-a-new-project/setting-up-a-project

Learn how to create and configure a new project in Caplena.

<iframe title="Loom video player" />

## Step 1: Start a New Project

Navigate to the **Projects** tab and click **New Project** in the top-right corner.

<Tip>
  Want to explore Caplena before importing your own data? Click **Import demo project** next to **New Project** to copy a ready-made example into your workspace. See [Try Caplena with a demo project](#try-caplena-with-a-demo-project) below.
</Tip>

## Step 2: Enter Project Details

**Project Name & Context** Give your project a clear and descriptive name. You can also add optional context — such as the target audience or goal of your analysis — to help the AI generate more relevant insights.

**Main Language** Select the primary language of your text data. If your dataset contains multiple languages, you can enable **Automatic Translation**.

## Step 3: Configure Settings (Optional)

* **Anonymization** – Automatically removes personal information from your text data. [Learn more →](/get-started/project-settings/anonymization)
* **Automatic Translation** – Enable if your dataset includes multiple languages to ensure consistent analysis. [Learn more →](/get-started/project-settings/languages-and-translations)

## Step 4: Proceed to Data Import

Click **Continue** to move on to the data import step. You'll be presented with three options:

* **Upload a File** – Import `.xls`, `.xlsx`, `.csv`, `.txt`, `.spss`, or `.sav` files. [Learn more →](/get-started/file-import)
* **Use an Integration** – Connect to one of our pre-built integrations. [Learn more →](/integrations/integrations-in-caplena-overview)
* **Import via API** – Automate data import from your internal systems. [Learn more →](https://caplena.com/docs/developers/118d96045bd54-caplena-rest-api)

## Try Caplena with a demo project

If you want to explore Caplena's features before bringing in your own data, you can copy a pre-built demo project into your workspace. Demo projects contain example datasets with topics and reports already configured, and they don't consume credits.

**When to use it**

* You're new to Caplena and want to see what a finished project looks like.
* You want to test reports, filters, or Insight Agent on realistic data.
* You're preparing a stakeholder demo and need example content fast.

**How to add a demo project**

<iframe title="Loom video player" />

<iframe title="Loom video player" />

1. Go to the **Projects** page.
2. Click **Import demo project** (next to **New Project**).
3. Choose one of the two tabs at the top of the modal:
   * **From project list** – Copy a curated demo into your workspace.
   * **Generate my own demo data** – Have Caplena create a synthetic demo project for a use case you describe.

### Option A: Copy a curated demo

Use this option when you want a finished project immediately, with no setup required.

1. On the **From project list** tab, browse the available demos. Use the search box to filter by name.
2. Choose how to import:
   * **Single project** – Click **Add** on any project to copy it into your workspace.
   * **Multiple projects** – Select several projects, then click **Add N projects** to import them all at once.
3. Once the copy finishes, the new projects appear in your project list and behave like any other project — you can edit, share, or delete them.

### Option B: Generate a synthetic demo project

Use this option when none of the curated demos match the use case you want to explore — for example, when you'd like sample data for a specific industry, survey type, or research question before connecting your own data.

Caplena generates a brand-new project with synthetic open-ended responses and (by default) a fully analysed report. Generation runs in the background, and you'll receive an email when the project is ready.

1. On the **Generate my own demo data** tab, configure the project:
   * **Feedback source** – The type of study you want to simulate: *Ad-hoc study*, *NPS / CSAT*, *Online reviews*, or *Employee feedback*.
   * **Language** – The language the synthetic responses should be written in.
   * **Use case prompt** – A short description of the question or use case to generate data for. Pick one of the suggested prompts (such as *Product test*, *Ad test*, or *AB test*) to prefill the field, or write your own (up to 300 characters). For example: *"What do business travellers think of the in-flight services?"*.
2. (Optional) Expand **Advanced options** to personalize the generated report with a **Company name**, **First name**, and **Last name**. Leave any field empty to use the values from your account.
3. (Optional) Enable **Data only** if you want just the raw synthetic responses, without an automatic topic analysis or report. Leave it off to receive a fully analysed project.
4. Click **Generate project**. The modal closes and Caplena starts generating in the background — you'll get an email as soon as the project is ready, and it will appear in your project list like any other project.

<Note>
  The **Import demo project** button is only visible to users with permission to create projects. If you don't see it, ask your workspace admin to grant you the project-create permission. Both copying a curated demo and generating a synthetic one are free and do not consume credits.
</Note>


# Caplena Documentation
Source: https://docs.caplena.com/index

Find answers quickly and move from setup to insight.

<div>
  <section>
    <div />

    <div>
      <h1>
        Welcome to <br />Caplena Documentation
      </h1>

      <p>
        Use Caplena docs to set up projects, analyze open-ended feedback with AI topic assignment, and build and share insights faster.
      </p>

      <div>
        <a href="/get-started">
          Get Started
        </a>

        <a href="/integrations">
          Integrations
        </a>
      </div>
    </div>
  </section>

  <section>
    <div>
      <a href="/get-started">
        <div>
          <div>
            <svg>
              <path />
            </svg>
          </div>

          <h3>Get started</h3>

          <p>
            Start here to learn the essentials, from navigating the interface to your first analysis.
          </p>
        </div>
      </a>

      <a href="/topic-assignment">
        <div>
          <div>
            <svg>
              <path />
            </svg>
          </div>

          <h3>Topic Analysis</h3>

          <p>
            Learn how to generate topics with AI, refine your topic structure, and get accurate assignments.
          </p>
        </div>
      </a>

      <a href="/insight-and-reports">
        <div>
          <div>
            <svg>
              <path />
            </svg>
          </div>

          <h3>Insight & Reports</h3>
          <p>Learn how to generate and share insights</p>
        </div>
      </a>

      <a href="/data-project-management">
        <div>
          <div>
            <svg>
              <path />
            </svg>
          </div>

          <h3>Data Management</h3>
          <p>Learn how to organize your data in Caplena</p>
        </div>
      </a>

      <a href="/integrations">
        <div>
          <div>
            <svg>
              <path />
            </svg>
          </div>

          <h3>Integrations</h3>

          <p>
            Learn how to connect external platforms, automate data imports, and manage your integrated data sources.
          </p>
        </div>
      </a>

      <a href="/settings-administration">
        <div>
          <div>
            <svg>
              <path />
            </svg>
          </div>

          <h3>Settings & Administration</h3>

          <p>
            Manage users, permissions, and platform settings to keep your workspace secure and organized.
          </p>
        </div>
      </a>
    </div>
  </section>
</div>


# Setting Up Alerts
Source: https://docs.caplena.com/insight-and-reports/alerts/setting-up-alerts

Learn how to set up alerts to track topic trends and discover new issues automatically.

The **Alerts** feature in Caplena helps you stay on top of emerging trends, spikes in feedback, and important changes in sentiment or topic frequency

## Types of Alerts

When you click **Create new alert**, you’ll be prompted to choose one of three options:

**Agent Prompt** *(featured)* Get AI-generated reports delivered on a schedule or on demand. Write a plain-language prompt describing what you want to know and how often, Caplena's agent will analyze your data and send you a report.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 08 54" />
</Frame>

<Note>
  *Example prompt:* "Send me a weekly report on which topics changed most drastically."
</Note>

**New Topics Alert** Get notified when brand-new topics emerge in your feedback, revealing early signs of market shifts, product issues, or opportunities.

**Topics Trend Alert** Stay ahead of trends by auto-detecting shifts in sentiment, mentions, or frequency. Customize thresholds or let auto-digest do the work.

## How to Set Up an Alert

* Go to your project and open the **Alerts** tab.
* Click **Create new alert**.
* Choose your alert type and click **Next**.
* Fill in the details and configure your schedule.
  <iframe title="Loom video player" />

## Agent Prompt Alerts

This is the most flexible alert type. You write a custom prompt telling Caplena what to analyze and report on.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 10 26" />
</Frame>

**Configuration options:**

* **Alert name** — Give your alert a descriptive name (e.g. "Weekly Pricing Changes Report").
* **Filters** — Scope the alert to specific segments of your data.
* **Alert prompt** — Write your instruction in plain language (up to 1,000 characters). Describe what to analyze, what to summarize, and any comparisons to make.
* **Schedule** — Choose *One off*, *Weekly*, *Monthly*, or *Quarterly*. For recurring schedules, set the day of week and hour.
* **Notification delivery** — Send to yourself or to someone else. The recipient becomes the alert owner if they're a member of your organization (see [Alert ownership](#alert-ownership)).

<Note>
  *Example prompt:* "Analyze the customer feedback and identify all mentions related to pricing changes. Summarize the key themes, sentiment, and frequency of pricing-related feedback. Compare the findings to the previous period."
</Note>

**What You'll Receive**

Once your Agent Prompt alert runs, Caplena will send you a formatted email report tailored to your prompt. The agent decides the best way to present the findings — this could include narrative summaries, tables, breakdowns by segment, or a mix, depending on what makes most sense for the question you asked.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 11 31" title="Screenshot 2026 05 24 At 11 11 31" />
</Frame>

## New Topics Alert

Get notified as soon as brand-new topics appear in your feedback. This is useful for catching emerging issues, product bugs, or shifts in customer language before they show up in trend data.

**Configuration options:**

* **Alert name** — A descriptive name (e.g. "New Topics – Support Feedback").
* **Filters** — Scope the alert to a segment of your data (e.g. a specific channel, product, or time window).
* **Column** — Choose which text column to monitor for new topics.
* **Minimum mentions** — Set how many times a topic must appear before it's flagged as "new". Higher thresholds reduce noise; lower thresholds surface issues earlier.
* **Schedule** — Choose *Weekly*, *Monthly*, or *Quarterly*. For recurring schedules, set the day of week and hour the alert should run.
* **Notification delivery** — Send to yourself or to another user. If the recipient is a member of your organization, they become the alert owner (see [Alert ownership](#alert-ownership)).

**What you'll receive**

An email listing each newly detected topic, the number of mentions, and sample verbatims so you can quickly assess whether it warrants action.

<Tip>
  Pair a New Topics Alert with a broad filter (e.g. all support tickets) to act as an early-warning system for issues you haven't defined categories for yet.
</Tip>

## Topics Trend Alert

Stay ahead of shifts in your data by monitoring how existing topics change over time. Use it to spot spikes in complaints, drops in praise, or sentiment swings on specific themes.

**Configuration options:**

* **Alert name** — A descriptive name (e.g. "Pricing Sentiment Drop").
* **Filters** — Scope the alert to a specific segment (channel, region, product line, etc.).
* **Topics to monitor** — Select one or more topics, or use **auto-digest** to let Caplena surface the topics that changed most.
* **Metric** — Choose what to track: mention count, share of feedback, or sentiment.
* **Threshold** — Define the change that should trigger the alert (e.g. sentiment drops by more than 10%, or mentions increase by more than 25%). Leave blank when using auto-digest.
* **Comparison period** — Compare against the previous period, the same period last year, or a custom baseline.
* **Schedule** — Choose *Weekly*, *Monthly*, or *Quarterly*.
* **Notification delivery** — Send to yourself or another user.

**What you'll receive**

An email highlighting each topic that crossed your threshold, the direction and size of the change, and a comparison against the baseline period.

<Tip>
  Use auto-digest when you want a broad "what changed this week" summary. Use explicit thresholds when you're monitoring a specific KPI or known risk area.
</Tip>

## Alert ownership

Each alert has an owner — by default, the user who created it. Ownership controls who can edit or delete an alert and where it appears.

**Visibility**

* **Project Alerts tab** — shows every alert configured on the project, regardless of owner. Use the **Owner** filter to narrow the list to a specific teammate.
* **Report Alerts tab** — shows only the alerts you own.

**Editing and deleting**

By default, you can only edit or delete alerts you own. In addition to the owner, the following users can also edit, delete, and send test runs for alerts they don't own:

* **Organization root users**
* **Project owners** — the user listed as the owner of the project the alert belongs to

Other project members with edit access on the project cannot manage alerts they don't own — the project-level edit permission on its own does not grant alert management. If you can't edit an alert, ask the owner, a project owner, or an organization root user to make the change, or have them transfer ownership.

**Transferring ownership**

To hand an alert over to a teammate, edit it and set **Notification delivery** to their email address. If the recipient is a member of your organization, they automatically become the new owner and the alert moves to their Report Alerts tab.


# Case Limit
Source: https://docs.caplena.com/insight-and-reports/creating-and-customizing-reports/case-limit

Protect respondent anonymity by hiding insights with too few cases

The case limit is a privacy feature that hides insights when there are too few responses for a segment. To enable it, send a message to [support@caplena.com](mailto:support@caplena.com).

<Note>
  If the limit is set to **5**, any topic or filter combination based on **5 or fewer responses** will be hidden, helping protect respondent anonymity.
</Note>

## How it works

When the case limit is active, clicking a topic with fewer responses than the threshold will hide the view and show a case-limit notice instead of individual responses.

<iframe title="Loom video player" />

## Behavior with global filters

When you apply a **global filter** in the report, the behavior of your insights depends on whether the selected topics meet the minimum case number required for insights to be calculated.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 16 57" />
</Frame>

### Case A: Only topics below the minimum

All insight elements will appear **blank** — insights cannot be calculated for topics with too few cases.

### Case B: Mix of topics below and above the minimum

Insight elements will still be shown. Topics with enough cases display as usual, while topics below the minimum will still appear in charts but individual responses will be hidden.


# Creating Reports
Source: https://docs.caplena.com/insight-and-reports/creating-and-customizing-reports/creating-reports

Learn how to create a report in Caplena to generate powerful visual insights.

Once your data is analyzed, the **Reports** section helps bring your insights to life through dynamic, easy-to-read visualizations. Whether you're monitoring customer satisfaction, identifying key trends, or preparing presentations, Caplena reports make storytelling with data simple and impactful.

## What you can do with reports

* Visualize your data using charts, graphs, and summaries.
* Share compelling insights with your team or stakeholders.
* Track performance and feedback over time.

<Tip>
  Think of reports as the final chapter of your analysis, where raw data becomes actionable insight.
</Tip>

## Step 1: Access the Reports section

<Steps>
  <Step>
    Open your Caplena project.
  </Step>

  <Step>
    Click on the **Reports** tab in the top navigation bar.
  </Step>

  <Step>
    Select the **New Report** button in the top-right corner.

    <Frame>
      <img alt="Step 1 - Access the reports section" />
    </Frame>
  </Step>
</Steps>

## Step 2: Choose a report template

Caplena lets you choose between two report types at the top of the "Create new report" screen:

* **Static** – A point-in-time report
* **Over time** – A report comparing results across periods (e.g., months, weeks)

Once you select the report type, you can choose how you want to start building your report.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 22 37" />
</Frame>

<Note>
  **✨ Auto-Generate Report**

  Generates a tailored report instantly based on your dataset. Caplena highlights key segments, meaningful differences, and the main drivers behind sentiment and experience. Click **Generate Report** to create it automatically.
</Note>

Depending on the report type you selected, you can pick a template that matches your goal:

| Template           | Best For                                                                         |
| :----------------- | :------------------------------------------------------------------------------- |
| **NPS & CSAT**     | Tracking satisfaction over time and identifying long-term trends in loyalty.     |
| **Online Reviews** | Monitoring shifts in sentiment and spotting emerging themes or issues.           |
| **Blank**          | Full flexibility — start with an empty structure and define everything yourself. |

<Tip>
  If you want to analyze how customer satisfaction evolved after a product update, choose **NPS & CSAT** under the **Over time** tab.
</Tip>

Click **Start** under your preferred template to continue.

<Warning>
  Some templates may limit or customize the types of charts available based on the focus of the report.
</Warning>

## Step 3: Configure your report

Let's walk through the configuration using the **NPS Over Time** template as an example.

<Frame>
  <img alt="Step 3 - Configure your report" />
</Frame>

### Basic info

* **Report Name** — e.g., *Q2 2025 NPS Trend Report*
* **Description** *(optional)* — brief goal or context, e.g., *"Tracking NPS after April onboarding update"*

### Data columns

* **Score** — numeric field (e.g., *NPS Score*, *Satisfaction Rating*)
* **Open-Text** — explanation field (e.g., *Why did you give this score?*)
* **Date** *(optional)* — for time-based charts (e.g., *Survey Completion Date*)

## Step 4: Generate and customize your report

Click **Generate Report** to instantly create your first draft. From there, you can:

* Drag & drop visual elements.
* Apply filters by segments like country, product, or sentiment.
* Add titles and annotations to tell a clear story.


# Custom Theme
Source: https://docs.caplena.com/insight-and-reports/creating-and-customizing-reports/custom-theme

Tailor your visuals to match your brand

Caplena allows you to personalize your reports with a **Custom Theme** that reflects your brand identity. Whether you want to match your company's color palette, align visuals across projects, or impress stakeholders with a polished look, custom themes are the way to go.

<Note>
  You can create and manage your theme in your **Project Settings → Theme** tab.
</Note>

<iframe title="Loom video player" />

## How It Works

* **Primary Color** – used mainly for buttons and key interface elements
* **Gradient Colors 1–8** – used for data visualizations like charts and segments,
* **Additional Colors** – up to 11 total colors to shape your visual story

<Note>
  It’s **not currently possible to manually assign specific colors to specific topics, or brands**. In other words:

  * You can set the palette
  * But you cannot say: “Brand A should always be blue”
</Note>

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 28 17" />
</Frame>


# Customizing Report
Source: https://docs.caplena.com/insight-and-reports/creating-and-customizing-reports/customizing-report

Learn how to structure, customize, and present your Caplena report.

Caplena reports are designed to make insight-building simple, structured, and powerful. This guide explains everything you need to know to build, structure, and customize reports in Caplena.

## The Core Concept: How Reports Are Structured

<iframe title="Loom video player" />

Every report in Caplena has two layers:

* **Report Master** – where you build the structure
* **Views** – different perspectives on top of that structure

Let's walk through each one.

<Frame>
  <img alt="Core report structure: Master and Views" />
</Frame>

## Report Master: Where You Build the Report

The **Report Master** is the blueprint of your report. This is where you build and edit the *actual content* of your report — what appears, how it's structured, and how the story flows.

In the Master, you can:

* Add / remove / rename **Sections**
* Add and arrange **Insight Elements**
* Reorder anything via drag-and-drop
* Adjust layout and structure
* Build Segments

<Frame>
  <img alt="Report Master editing" />
</Frame>

Any change you make here automatically updates every View. This keeps your report consistent, clean, and easy to maintain — no version drift, no duplicates.

**Use the Report Master when you want to change the content or structure of the report.**

## Views: Tailored Perspectives for Your Audience

Views let you create different angles on top of the same structure.

A **View** is a perspective where you can:

* Apply or lock local filters
* Choose specific segments
* Share a single View without sharing the entire report
  <Frame>
    <img alt="Master" />
  </Frame>

Views allow you to tailor insights for different stakeholders, teams, or themes, without modifying the underlying structure.

Common examples:

* **By region:** DACH, North America
* **By segment:** New vs. returning customers
* **By feedback type:** Detractors, negative sentiment
* **By product/channel:** Mobile app, checkout flow
* **By time period:** Pre-/post-launch, last 30 days
* **By stakeholder:** Leadership summary, Product view

Views do not change the structure. Sections, insights, and layout always remain controlled by the Master.

Use Views when you want to customize **what data** appears, not **how the report is built.**

## Sections: Organize Your Report

Sections help you break down complex data into manageable chunks, making your report easier to read and understand.

<Frame>
  <img alt="Sections" />
</Frame>

**How to Add a Section:**

1. In **Edit Mode**, click **+ Add New Section**.
2. Give your section a name (e.g., *"NPS Breakdown"*, *"Sentiment by Product"*).
3. Add visualizations, summaries, or custom text.

**Benefits:**

* **Better Organization** — Keep related insights grouped together.
* **Improved Readability** — Help readers focus on one topic at a time.
* **Drag-and-Drop Order** — Rearranging sections is as simple as dragging them in the side panel.

## Insight Elements: Visualize What Matters

Insight Elements are pre-built components that let you analyze and display your data in a powerful, digestible format.

<Frame>
  <img alt="Insight elements catalog and selection" />
</Frame>

**Available Elements:**

* **NPS & Ratings** — Show Net Promoter Scores, star ratings, and score distributions.
* **Trends & Drivers** — Reveal what's impacting sentiment over time.
* **Sentiment Analysis** — Show overall or category-specific sentiment.
* **Topic Insights** — Break down feedback into themes or categories.

**How to Add an Insight:**

1. In Edit Mode, choose an insight type from the left panel.
2. Review its preview and purpose.
3. Click **Select Columns** to map the correct data fields.
4. The insight will be added to the current section.

## Filters & Segments: Focus Your Analysis

Caplena's **Filters** and **Segments** let you dive deeper into your data by zooming in on what's most relevant, whether that's a specific brand, region, or time frame.

**Filters**

Use filters to narrow your data view:

* **By Brand** — Compare customer experiences across products.
* **By Country** — Identify regional differences.
* **By Rating** — Focus on 1–2 star reviews to uncover pain points.
  <Frame>
    <img alt="Filters" />
  </Frame>

<Note>
  **Example:** Filter for 1–2 star reviews from Germany to understand local pain points.
</Note>

**Creating Segments**

You can create segments in two ways — using AI or manually.

<iframe title="Loom video player" />

**AI-assisted segment creation**

In **Edit Master**, select the **Overall** segment and click **Edit**. You'll see the option to describe the segment you want in plain language, for example, *"Create segments by country."* Caplena will look at the additional variables in your dataset and automatically generate the relevant segments.

**Manual segment creation**

Prefer to build segments yourself? Select a variable (e.g., *Gender*), choose the values you want, and create all segments in one go.

**Managing segments**

Once created, you can:

* **Change the color** of any segment — colors are assigned automatically, but you can customize them to match your preferences or branding
* **Control visibility** in specific views
* **Duplicate** a segment if you need a variation of it

<Note>
  Segments are great for comparing different data cuts side by side, like Brand A vs. Brand B.
</Note>

## Date Range Filter

The **Date Range** filter helps you examine how key metrics, customer sentiment, or feedback trends evolve over time. It's especially powerful when tracking changes before and after events like product updates, marketing campaigns, or customer service improvements.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 42 30" />
</Frame>

**Date as a Filter**

You can add a **Date filter** to narrow down which reviews or responses to include in your analysis.

**How to find it:** Go to **Filters → Review Date**. You can then choose between two modes:

* **Rolling range** — Automatically updates over time (e.g., "Last 12 months," "Last quarter," "Last 30 days").
* **Static range** — Lets you manually pick exact start and end dates from the calendar.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 43 05" />
</Frame>

<Tip>
  Use "Rolling range" if you want your dashboard or report to stay up to date automatically.
</Tip>

**Comparing Date Ranges**

You can use **Date range** and **Comparison** settings to visualize changes over time and compare key metrics between different periods.

**Selecting a Date Range**

Under **Date range**, choose how far back your data should go. You can pick from:

* **All time** – includes your entire dataset.
* **Fixed timeframes** such as *Last 7 days*, *Last month*, or *Last year*.
* **Dynamic ranges** like *Most recent week/month/quarter/year with data*, which automatically adjust based on when new data comes in.
* **Custom date range** – manually select start and end dates.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 44 23" />
</Frame>

<Tip>
  "Most recent year with data" is a great option for ongoing projects that update automatically as new feedback arrives.
</Tip>

**Choosing Intervals**

The **Date aggregation** (or interval) setting defines how results are grouped over time. Each data point on your chart represents one interval — so choosing the right granularity has a big impact on how trends are read.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 45 38" />
</Frame>

**Available intervals**

| Interval    | Best for                                                                                     |
| ----------- | -------------------------------------------------------------------------------------------- |
| **Day**     | Short windows, tracking immediate reactions to launches, campaigns, or incidents.            |
| **Week**    | Useful for spotting weekly patterns without the noise of daily variation.                    |
| **Month**   | Balances detail with readability and aligns with business reporting cycles.                  |
| **Quarter** | Ideal for business reporting cycles or when you want to compare performance across quarters. |
| **Year**    | Long-running projects with multiple years of feedback.                                       |

**How to choose the right interval**

* **Match the interval to your date range.** A daily interval over two years produces a crowded, unreadable chart; a yearly interval over three months gives you a single bar.
* **Consider data volume per interval.** If a single day only has a handful of responses, daily aggregation will look spiky and unreliable. Move up to weekly or monthly so each point reflects a meaningful sample.
* **Align with how the business reports.** If stakeholders track results monthly or by quarter, mirror that interval so your report drops straight into existing reviews.
* **Use shorter intervals to investigate, longer intervals to communicate.** Drill down to daily or weekly when diagnosing a spike, then switch back to monthly or quarterly for the shareable view.

<Tip>
  Changing the interval doesn't change your underlying data or filters, only how points are grouped on the chart. You can switch back and forth freely while exploring.
</Tip>


# Row-level weights
Source: https://docs.caplena.com/insight-and-reports/creating-and-customizing-reports/row-level-weights

Applying weights in Caplena Reports

If you are using weighting to balance your sample, you can apply a weight variable directly in Caplena's reporting. Once applied, all results displayed in the report will automatically reflect the specified weighting.

## Applying weights to a report

You can apply weights during the report creation process via **Advanced settings**.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 49 58" />
</Frame>

<Steps>
  <Step>
    Go to **Reports → Create new report**
  </Step>

  <Step>
    Select the template you want to use
  </Step>

  <Step>
    Expand **Advanced settings**
  </Step>

  <Step>
    Under **Select the Weight column**, choose the column containing your numeric weights
  </Step>

  <Step>
    Create the report
  </Step>
</Steps>

After the report is created, Caplena automatically incorporates the chosen weights into all displayed metrics and shows a confirmation banner at the top of the report.

<Frame>
  <img alt="Screenshot 2026 05 30 At 16 29 02" />
</Frame>

<Note>
  Once a report is created, the weight column cannot be added or changed. If you need a version without weights, create a new report using the same setup but leave the weight column unselected.
</Note>

## The weight variable must be numerical

Caplena requires the weight column to be numerical. When importing your data, make sure the column is set as a numerical type — this happens automatically if it contains only numerical values.

<Note>
  Additional weighting-related features and improvements may be introduced in future updates.
</Note>

## How rounding works when weighting is applied

When weighting is applied, each respondent receives a weight value — often a decimal (e.g., 0.7, 1.2, 2.3), which means counts can naturally include decimal numbers. Caplena handles this in two ways:

**Displayed counts are rounded**

All counts shown in the UI (charts, tooltips, key figures) are rounded to whole numbers to avoid confusing values like 0.4 or 7.8 respondents.

**Calculations use full precision**

Behind the scenes, all analytics use the full precise weighted decimals, including for frequencies, percentages, category and topic totals, correlations, drivers, and significance tests.


# Getting the Most Out of the Caplena Insights Agent
Source: https://docs.caplena.com/insight-and-reports/insight-agent/getting-the-most-out-of-the-caplena-insights-agent

How to Get Better Results from the Caplena Insights Agent

The Insights Agent is your conversational partner in data analysis. Like any large language model, its quality scales with the quality of your prompts — think of it as a capable junior analyst: the more context and direction you give, the sharper the output.

<Frame>
  <img alt="Screenshot 2026 05 24 At 11 54 36" />
</Frame>

## The Golden Rule: Context Is Everything

The Insights Agent doesn't intuitively know your intent — it reacts to the data and the prompts you provide. To get precise, actionable answers, include as much context as possible: the timeframe, the specific category, or the survey column you want to analyze.

<Note>
  **Iteration tip:** Treat the first answer as a starting point. If it's too broad, follow up: "That's interesting — can you show me specific verbatim examples for that negative trend?"
</Note>

## How the Agent Shapes Its Responses

The Insights Agent doesn't use a fixed template. It dynamically selects the visualizations, charts, or summaries that best answer your specific prompt. A simple question might return a clean text summary. A broader request about "most common issues" will automatically generate a multi-layered analysis with statistical trends, sentiment breakdowns, and representative customer comments.

## What to Do: Master the Conversation

These strategies consistently produce better, more targeted answers.

| Strategy                         | Why it works                                                                                            | Example prompt                                                                            |
| :------------------------------- | :------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------- |
| Onboard yourself first           | Quickly understand the scope of a new project                                                           | "What data can I see in this project?" or "What are the most common themes here?"         |
| Define your persona              | Tailors output to your specific role and priorities                                                     | "My role is Product Manager for the web app. What feedback is relevant for me?"           |
| Be ultra-specific                | Prevents generic answers by targeting exact data points                                                 | "Compare sentiment on 'Ease of Use' between Q1 and Q2 for Enterprise users."              |
| Explain by example               | Sets a clear template for format or tone                                                                | "Summarize in three bullet points, then one Key Action Item for the dev team."            |
| Check active filters             | Ensures you're analyzing the right data subset                                                          | Check the system note in chat to see which dashboard filters are currently active.        |
| Ask product and how-to questions | The Agent can consult Caplena's official documentation to explain features, concepts, and configuration | "What's a smart column and when should I use one?" or "How do I share a filtered report?" |

## What to Avoid: Common Pitfalls

Watch out for these habits:

* **Blind trust:** The Agent is highly accurate, but it augments your expertise rather than replacing it. If an insight contradicts your intuition, investigate it — ask for an explanation of its reasoning or cross-reference the raw data.
* **Ignoring filters:** If results feel "off," a dashboard filter is often still applied. Always verify active filters in the Meta Text at the start of your response.
* **Expecting magic knowledge:** The Agent can analyze data uploaded to Caplena and can consult Caplena's product documentation for how-to and feature questions. It cannot access your internal documents, Slack messages, or external market trends unless they are part of the current project.
* **Vague terminology:** Avoid pronouns like "it" or "that" when the conversation has covered multiple topics. Use explicit category or segment names to keep the Agent on track.
* **Using it as a manual calculator:** Don't ask the Agent to do arithmetic on numbers already shown in chat. The Agent provides pre-calculated Key Quantitative Findings from the raw dataset — manual math in a chat thread introduces errors. For value mappings or mathematical operations, use the **Smart Column** feature instead.


# Insight Agent
Source: https://docs.caplena.com/insight-and-reports/insight-agent/insight-agent

Learn how to uncover insights instantly with AI-powered agent.

The **Insight Agent** is an AI-powered feature in Caplena that lets you interact with your data using natural language. It provides instant responses, visualizations, and summaries to help you uncover actionable insights quickly.

## Why use Insight Agent?

It streamlines data analysis, enabling faster decisions and more customer-focused strategies to improve satisfaction and efficiency.

## How to access Insight Agent

You can open Insight Agent from three places in Caplena:

* **Insight Agent tab** — click the dedicated tab in the left sidebar to open the full Insight Agent interface
* **Project overview** — use the chat input at the bottom of the project overview page to ask questions directly
* **Reports** — access it from within any report to ask questions in the context of that report's data

## The interface

Once open, the Insight Agent interface has two panels on the left:

* **History** — search and revisit past conversations, or start a new one. Conversations are stored for 60 days.
* **Agent Alerts** — view any alerts triggered by the agent

<Note>
  Conversations are only visible where they were created. A chat you start on the **project overview** appears in that project's history, while a chat you start on a **specific report** appears only in that report's history. If you can't find a past conversation, check that you've opened the Insight Agent from the same place where you originally created it.
</Note>

To start a new conversation, click the icon at the top of the History panel and choose:

* **New conversation** — start fresh with no filters
* **New conversation with filters** — narrow your analysis to a specific segment before you begin

<Frame>
  <img alt="Screenshot 2026 05 24 At 15 36 22" />
</Frame>

The main area shows a chat input at the bottom. Type your question and press **Enter** to submit.

<Tip>
  Not sure what to ask? Click the **i** icon in the chat input and Caplena will generate question ideas based on your data.
</Tip>

## Getting insights from your data

Insight Agent is fully conversational — you drive the analysis by asking questions and following up to go deeper. There's no fixed flow; the more context and direction you give, the sharper the output.

A good way to get started:

1. **Orient yourself** — *"What are the most common themes in this project?"*
2. **Dig into something interesting** — *"Can you break down sentiment on delivery time by region?"*
3. **Follow up** — *"Show me specific examples from customers who mentioned that negatively."*

<Frame>
  <img alt="Screenshot 2026 05 24 At 15 57 29" />
</Frame>

This works even for topics that haven't been explicitly coded — Insight Agent will analyze the raw data to find relevant patterns.

## Ask product and how-to questions

In addition to analyzing your data, Insight Agent can answer questions about Caplena itself by pulling from the official [Caplena documentation](https://docs.caplena.com). Ask it things like:

* *"What's a smart column and when should I use one?"*
* *"How do I share a filtered report with a stakeholder?"*
* *"What's the difference between drivers and sentiment share?"*
* *"How do I set up the Slack integration?"*

When the agent answers from the docs, it cites the relevant pages so you can read more. This means you can stay in the conversation to learn product concepts, configuration steps, and best practices without leaving Caplena.

<Frame>
  <img alt="Screenshot 2026 06 25 At 08 54 55" />
</Frame>

## Create and edit Smart Columns from chat

Insight Agent can build [Smart Columns](/data-project-management/smart-columns-intro/smart-columns-overview) for you directly in the conversation — no need to leave the chat or write formulas yourself. Ask for a transformation in plain language and the agent will pick the right mode (mapping, formula, or LLM), draft the configuration, and preview the results before anything is saved live.

<Frame>
  <img alt="Screenshot 2026 06 25 At 08 58 53" />
</Frame>

A typical flow looks like this:

1. **Describe what you need** — for example, *"Add a column that classifies each response as positive, neutral, or negative"* or *"Create a column that extracts the brand mentioned in the feedback."*
2. **Review the preview** — the agent runs the new column on a small set of rows so you can sanity-check the output before committing.
3. **Iterate if needed** — refine the prompt (*"Only flag complaints, not neutral mentions"*) and the agent will update the draft and re-preview.
4. **Apply** — once you confirm, the agent activates the column. For large projects, it can also run a free sample first so you can validate quality before consuming credits.

You can also ask the agent to **edit an existing Smart Column** — for example, *"Update the sentiment column to also detect sarcasm"* — and it will preview the change before saving.

<Note>
  Editing a live Smart Column is a one-way action: once you confirm an edit, the column is updated immediately and cannot be reverted to a draft. The agent will always show you a preview and ask for confirmation first, and you can choose whether to apply the change to new rows only or recompute everything.
</Note>

Smart Columns created or modified through the agent count toward your plan's Smart Column slots in the same way as those created from the Smart Columns tab. See [Smart Columns Overview](/data-project-management/smart-columns-intro/smart-columns-overview) for more on draft vs. live columns and slot limits.

## Understanding the insights

Insights highlight **strengths** (what customers value most) and **weaknesses** (recurring issues to address), based on topics with the highest positive and negative sentiment shares.

Insight Agent also surfaces **driver analysis** — showing how specific topics impact customer satisfaction.

<Frame>
  <img alt="Screenshot 2026 05 24 At 15 59 31" />
</Frame>

## Use Insight Agent in Slack or Microsoft Teams

You don't have to be in Caplena to use Insight Agent. With the Slack and Microsoft Teams integrations, your team can ask questions and get instant AI-powered answers directly in the tools they already use — no tab switching needed.

[Set up the Slack or Teams integration →](/integrations/outbound-accounts-microsoft-teams-slack-and-more)

## Share Insight Agent with stakeholders

When sharing a report, you can enable Insight Agent for recipients so they can ask their own questions — scoped only to the filtered data you've shared with them. This lets stakeholders explore insights independently without accessing your full dataset.

[Learn how to share a filtered report with Insight Agent →](/insight-and-reports/sharing-reports/sharing-reports)

## Shortcut: the magic-wand icon

In a few places across Caplena, you'll see a small **magic-wand icon** (<Icon icon="wand-magic-sparkles" />) next to the surrounding UI. Clicking it opens Insight Agent with a prompt already filled in for that context — you can edit the prompt before sending, or send it as-is.

<Frame>
  <img alt="Screenshot 2026 07 14 At 17 08 10" />
</Frame>

The wand currently appears on:

* **AI quality score** (Topic Assignment page) — pre-fills *"Optimize the AI quality score"* so the [Topic Critique Agent](/insight-and-reports/insight-agent/topic-critique-agent) can suggest description or structure changes that lift the score.
* **Add topic** button in the topic browser — pre-fills a request to suggest more topics for the selected category.
* **Topic edit menu** (title and description fields) — pre-fills a request to improve the assignment or description of that specific topic.

Because these shortcuts are launched from a specific page, Insight Agent also picks up the **page context** automatically — so you don't need to spell out which TTA column you mean when you're already on the Topics page for that column. See [Page context](/insight-and-reports/insight-agent/topic-critique-agent#page-context) for details.

<Note>
  The magic-wand shortcuts are only visible to users on a plan that includes **Conversational Insights** (Insight Agent access). Users without that entitlement won't see the icon.
</Note>

## Critique and improve topic assignment from chat

For questions about topic assignment quality — *"Why isn't this topic being assigned?"*, *"How do I improve the AI score?"*, *"The topics overlap, can you fix them?"* — Insight Agent hands off to the [Topic Critique Agent](/insight-and-reports/insight-agent/topic-critique-agent). It analyzes your topic collection, explains what's off, and can edit the topic collection for you (with confirmation) to fix the issues it finds.

## Go further

For tips on how to write better prompts, avoid common pitfalls, and get the most targeted answers, see [Getting the Most Out of the Insight Agent](/insight-and-reports/insight-agent/getting-the-most-out-of-the-caplena-insights-agent).


# Topic Critique Agent
Source: https://docs.caplena.com/insight-and-reports/insight-agent/topic-critique-agent

Ask Insight Agent to review your topic collection and suggest — or apply — improvements.

The **Topic Critique Agent** is a specialist inside [Insight Agent](/insight-and-reports/insight-agent/insight-agent) that focuses on the quality of your topic assignment. It inspects a text-to-analyze (TTA) column's topic collection, diagnoses assignment problems, and — with your confirmation — edits the topic collection to fix them.

## When to use it

Reach for the Topic Critique Agent when the AI-assigned topics don't match your expectations. Typical questions it handles:

* *"Why isn't topic X assigned to these rows?"*
* *"How can I improve the AI score on this column?"*
* *"Why do so many rows have no topic?"*
* *"The topics overlap — can you fix them?"*
* *"Help me improve the topic descriptions."*
* *"The sentiment on topic X is often wrong — how do I fix it?"*

It can also diagnose and improve **per-topic sentiment** (positive / neutral / negative) alongside topic labels and descriptions — checking whether sentiment is enabled on the right topics, measuring its accuracy against reviewed rows, and toggling it on or off as part of its proposed edits. If sentiment is disabled at the column level, the agent skips sentiment discussion entirely.

<Note>
  The Topic Critique Agent is only available to users with **edit** permission on the project. Report-only viewers can't invoke it, because it can modify the topic collection.
</Note>

## How to invoke it

There's no separate tab — you use it through Insight Agent. Open Insight Agent from the project overview, the Insight Agent tab, or a report, and ask a topic-assignment question. Insight Agent hands the conversation off to the Topic Critique Agent automatically when the question is about assignment quality or the topic collection.

<iframe title="Loom video player" />

If your project has more than one TTA column, mention which column you want reviewed in your prompt — for example, *"Critique the topic assignment on the 'Overall Feedback' column."*

### Page context

Insight Agent now knows which page you started the conversation from. If you open it — or click a magic-wand shortcut — from the **Topic Assignment** page of a specific TTA column, the Topic Critique Agent automatically targets that column, so you don't need to name it in your prompt.

* Say *"Improve the topic descriptions"* while viewing the "Overall Feedback" column and the agent will critique **Overall Feedback**.
* Switch to a different column and ask the same question, and the agent will critique that column instead.
* Page context is a hint per message, never a filter — it isn't persisted with the conversation, and you can always override it by naming a column explicitly (*"Critique the 'NPS Reason' column instead"*).

<Tip>
  Combined with the magic-wand shortcut next to the **AI quality score** and topic entries, this means the fastest path to a targeted critique is: open the Topic Assignment page for the column you care about, click the wand, and send.
</Tip>

## What the agent does

The Topic Critique Agent works in phases and always explains its reasoning before proposing a change:

1. **Analyzes the topic collection** — detects overlapping or ambiguous descriptions, labels or categories that contradict the description, descriptions that are too narrow or too broad, and topics whose sentiment configuration looks off (for example sentiment enabled on a purely factual topic, or disabled on one where tone clearly matters).
2. **Checks manual reviews** — looks at how consistently reviewed rows have been labeled and how much review coverage exists, including how accurate current sentiment assignments are versus reviewer choices.
3. **Grounds findings in real rows** — pulls concrete example rows and topic statistics so its diagnosis is tied to your actual data.
4. **Proposes changes** — presents a prioritized list of recommendations (usually description refinements first, then structural changes like merges, splits, adding new topics, or enabling/disabling per-topic sentiment, then manual-review suggestions).
5. **Optionally tests before applying** — before committing, the agent can run the proposed edits on a small subset of rows so you can see the effect. Subset tests support description and label tweaks, toggling per-topic sentiment, adding brand-new topics, and excluding existing ones — so you can preview structural changes, not just wording changes, before applying them.
6. **Edits the topic collection** — only after you confirm. All edits from a single conversation are grouped into one entry in the version history, so they can be reverted together.

<Tip>
  After the agent edits your topic collection, it will recommend running a full AI reassignment on the column. Subset-test results are directional only — a full run is what actually applies the new topic descriptions to every row.
</Tip>

## Understanding the AI score

A common reason to call the Topic Critique Agent is to raise a column's AI score. The score reflects how confident the AI is in its own topic assignments across the whole column — it isn't a comparison against manually reviewed rows.

<Frame>
  <img alt="Screenshot 2026 07 08 At 18 10 33" />
</Frame>

That means:

* **Reviewing more rows on its own does not raise the AI score.** Manual reviews are useful for sanity-checking assignments and spotting ambiguous topics, but they don't change what the model predicts on unreviewed rows.
* **Improving topic descriptions almost always does.** A low score usually indicates overlapping, ambiguous, or poorly worded descriptions — exactly what the Topic Critique Agent is built to find and fix.

If you're chasing a higher AI score, ask the agent to critique your topic descriptions first.

## Reviewing changes the agent made

Every edit the Topic Critique Agent applies is recorded in the topic assignment version history, alongside your manual edits and AI reassignments. Agent edits are marked with a distinct **sparkles badge** on each affected topic, so you can quickly tell which changes came from the agent.

To review or revert them:

1. Open the column's **Topic Assignment** page.
2. Click **History** in the top-right corner.
3. Pick the timestamp just before the agent's changes.
4. Topics that were edited by the agent are highlighted with the sparkles badge; topics changed by manual or other AI edits use the standard "changed" badge.
5. Use **Restore** to roll the topic collection back to that point if you want to undo the agent's changes.

<iframe title="Loom video player" />

See [Topic Assignment History](/topic-assignment/advanced-functionality/topic-assignment-history) for the full history workflow.

## Tips for better critiques

* **Be specific about the column and the problem.** "Why is 'Delivery Speed' rarely assigned even though customers mention it a lot?" is much easier for the agent to act on than "the topics look wrong."
* **Let it plan before it edits.** The agent is designed to explain its diagnosis first — read the reasoning before confirming an edit.
* **Use subset tests for risky changes.** For big description rewrites, category restructures, adding brand-new topics, or removing existing ones, ask the agent to validate on a subset first — it will show how the change moves assignments (and sentiment, when applicable) before you commit.
* **Follow up with a full run.** After confirming edits, kick off a full AI reassignment so every row benefits from the new topic collection.


# Driver Analysis
Source: https://docs.caplena.com/insight-and-reports/insight-elements/driver-analysis

Understand which topics have the greatest influence on KPIs like NPS, satisfaction, or star ratings.

Key driver analysis is a powerful way of measuring the **relative impact of topics on a KPI**. It helps you understand how much a topic influences performance metrics such as:

* Likelihood to recommend (e.g., NPS)
* Overall satisfaction
* Star ratings
* Other custom KPIs

## What's included in the driver analysis

The driver analysis includes four key elements:

<Frame>
  <img alt="Driver analysis overview" />
</Frame>

| Chart section                   | Details                                                                                                  |
| :------------------------------ | :------------------------------------------------------------------------------------------------------- |
| **Impact per mention**          | Measures impact on the performance metric on an individual basis, based on multiple regression analysis. |
| **Net impact**                  | Shows overall impact by combining driver strength and frequency of mentions.                             |
| **Suggestions for improvement** | AI-powered recommendations on how to improve key topics.                                                 |
| **Driver Impact vs. Mentions**  | Scatter plot showing driver strength vs. frequency for easy prioritization.                              |

## Impact per mention

Topic sentiment plays a key role in driver analysis, allowing Caplena to determine the impact of a topic based on positive and negative experiences.

* The **color coding** of the bars reflects sentiment-based impact.
* The **numbers next to the bars** show regression coefficients.
* The higher (or lower) the number, the stronger the impact on the likelihood to recommend.

**NETWORK QUALITY / Reliability** — the red and green bars are nearly equal in length, meaning both positive and negative experiences significantly influence the likelihood to recommend.

<Note>
  Someone mentioning unreliable network quality would likely not recommend the provider.
</Note>

**CUSTOMER SERVICE / Level of service** — a negative perception has a very strong negative impact, while a positive perception does not significantly boost recommendation.

<Note>
  This indicates a **"hygiene driver"** (Kano model): customers expect good service and react strongly when it falls short.
</Note>

## Net impact

The impact per mention measures individual cases, but to understand the overall effect on a KPI across the full sample, frequency must also be considered. Net impact combines **driver strength** with **mention frequency** to show how much a topic moves the needle overall.

<Note>
  NPS is not a simple linear metric — it's based on a non-linear step function. For example, a score increase from 2 to 6 still counts as a detractor, leaving overall NPS unchanged. To address the limitations introduced by this rigid structure, Caplena uses advanced probabilistic modeling to estimate the true net impact more accurately.
</Note>

### How net impact is calculated

Here's the step-by-step process behind the number:

1. **Calculate the baseline score** — Caplena calculates your actual overall score using all responses as they are.
2. **Determine the isolated pull of the topic** — Using statistical modeling, Caplena finds an impact coefficient for the topic: how many points a positive, negative, or neutral mention tends to pull a single person's rating up or down.
3. **Run a simulation for positive mentions** — To measure how much positive mentions moved the needle:
   * The positive pull of the topic is mathematically removed from everyone's rating and the overall score is recalculated.
   * The difference between this simulated score and the baseline is then scaled down by the actual percentage of respondents who mentioned the topic positively.
   <Note>
     Simulating across everyone and then scaling down is a technique used to prevent volatile results that occur when respondents are right on the edge of an NPS boundary.
   </Note>
4. **Repeat for negative and neutral mentions** — The same simulation is run separately for negative and neutral mentions.
5. **Combine for the final net impact** — The simulated impacts of positive, negative, and neutral mentions are added together. The result is the **Net Impact** — the total points this topic contributed to your overall score.

###

Taking **BRAND PERCEPTION / Overall perception**:

* This topic has the highest net impact based on the combination of driver strength and frequency.
* Although it has a significant negative impact when raised individually, it is most often associated with positive experiences — resulting in a strong overall net contribution.
* With **n = 203** mentions, driver strength and the balance of positive vs. negative mentions ultimately determine the net impact.

> **BRAND PERCEPTION / Overall perception = +11.1 points**

<Note>
  The driver chart currently supports NPS and 5-Star Rating as dependent variables. Additional performance metrics will be added soon.
</Note>

## Suggestions for improvement

For each topic, Caplena provides AI-generated suggestions based on open text analysis and driver calculation results.

## Driver Impact vs. Mentions

<Frame>
  <img alt="Driver Impact vs Mentions scatter plot" />
</Frame>

Clicking the icon in the top-left of the suggestion box toggles a scatter plot that visualizes:

* **Horizontal axis** — Impact (right = positive, left = negative)
* **Vertical axis** — Mention frequency

This helps you quickly identify which topics to prioritize.

## Video walkthrough

<iframe title="YouTube video player" />


# Insight Elements - General Overview & Settings
Source: https://docs.caplena.com/insight-and-reports/insight-elements/insight-elements-general-overview-settings

Overview of Insight Elements in Caplena: Types, Use Cases, and Customization Options

**Insight elements** are modular blocks you can add to any report in Caplena to highlight key findings, add context, or visualize data. They help turn your analysis into a narrative that's easy to understand and share with stakeholders.

Caplena offers different types of Insight Elements, grouped by purpose:

* **Scores & Ratings** – For metrics like NPS or star ratings
* **Drivers & Trends** – To show what impacts scores and how topics evolve
* **Topic Visualizations** – To compare frequency or sentiment across topics
* **Text-Based Elements** – For summaries, notes, or verbatim quotes
* **Distributions & Overviews** – To display numerical or categorical patterns

<Tip>
  **Tip:**

  Combine elements from different groups to create a well-rounded, insight-driven report.
</Tip>

## How to Add an Insight Element

* Go to the Report Master.
* Click **"+ Add new insight element here"**.
* Choose your desired element.

<iframe title="Loom video player" />

Once you've added your Insight Elements, you can tailor both how they look and what they include.

## View Options (Insight Elements Display)

**View options** control **how** the data is displayed. View options do **not** change the base of respondents.

<Frame>
  <img alt="Screenshot 2026 06 22 At 15 41 50" />
</Frame>

Examples of view types:

* Bar chart vs. treemap
* Segmented bar vs. breakdown layout
* Show "Top 10 Topics" or a specific category

<Note>
  > **Example**:
  >
  > Switching from "Topics Overview (Segmented)" to "Topics Overview (Treemap)" presents the same data in a different layout, no change to the respondent base.
</Note>

## Displayed timeframe

For elements that pair a single-value summary (such as a gauge, score, or headline number) with a chart over time, you can choose **which time period the summary value reflects**. The setting only affects the summary, not the time-series chart next to it.

<Frame>
  <img alt="Screenshot 2026 06 22 At 15 48 45" />
</Frame>

You can choose between:

* **Entire period** – the summary is computed across all data in the report's date range.
* **Most recent period** – the summary is computed only from the most recent time bucket (week, month, quarter, etc.) in the report's date range.

The selected period is reflected in the element's AI-generated description (for example, "*…computed over only the most recent time period*" vs. "*…computed over the entire period*"), so it's clear which slice of data the headline number represents.

**Where it's available**

The **Displayed timeframe** option is supported on the time-aware summary widgets of:

* **Overall Sentiment** – the net-sentiment gauge and segmented bar chart
* **Generic Score** and **Multi Score** – the score gauge, pie, and segmented bar chart
* **Row Count over time** – the headline row-count number
* **Topic Trends**

<Tip>
  Use *Most recent period* when you want the headline to track the latest state of your data (e.g., "this month's net sentiment"), and *Entire period* when you want a stable benchmark across the full report range.
</Tip>

## Individual Filters

Each Insight Element lets you **refine the data it shows,** without affecting other elements in the report. These filters **do** change the base of respondents shown in that specific element.

<Frame>
  <img alt="Screenshot 2026 06 22 At 15 50 37" />
</Frame>

You can:

* Include or exclude specific **topics** or **categories**
* Skip empty rows

<Note>
  > **Example**:
  >
  > Show only comments mentioning "flight delays" in a Topics Overview chart.
</Note>

## Explore Responses Behind the Data

You can **click on any Insight Element** to drill down and see the actual responses that power it.

If **Sentiment Analysis** is enabled, you'll also be able to **filter by sentiment** to explore positive, neutral, or negative feedback in context.

<iframe title="Loom video player" />


# Insight Elements Values Explained
Source: https://docs.caplena.com/insight-and-reports/insight-elements/insight-elements-values-explained

Why topic totals may exceed category totals

## Why topic totals inside a category can be higher than the category total

In Caplena, **all chart values and percentages are calculated on a respondent level** — every number represents how many respondents mentioned something, not how many topic assignments exist.

Because of this, it is expected and correct that:

<Frame>
  <img alt="Screenshot 2026 05 24 At 16 47 57" />
</Frame>

> The sum of all topics inside a category can be higher than the category's total.

## How counts in charts work

**Category counts** — the number of respondents who mentioned any topic in that category. Each respondent is counted once, even if their answer matches multiple topics inside the category.

**Topic counts** — the number of respondents who mentioned that specific topic. If a respondent mentions multiple topics, they count once for each.

This is why topic totals can exceed the category total: topic counts include multiple mentions from the same respondent, while the category count includes each respondent only once. This is intentional and reflects the true underlying data structure.

## Example: "PRODUCT QUALITY"

<Frame>
  <img alt="Screenshot 2026 05 24 At 16 49 06" />
</Frame>

**Category: PRODUCT QUALITY — 38.2%**

This means 38.2% of all respondents mentioned something about Product Quality. Each respondent is counted once, even if their answer covers several quality aspects.

**Topics inside PRODUCT QUALITY:**

* Picture Quality — 18.4%
* Reliability — 16%
* Durability — 6.8%
* Sound Quality — 6%

Adding these up exceeds 38.2% — and that's correct, because a single respondent can match multiple topics within the same category.

**Real-world example**

<Frame>
  <img alt="Screenshot 2026 05 24 At 16 49 54" />
</Frame>

Caplena assigned this response three topics:

* **Picture Quality** (under PRODUCT QUALITY)
* **Sound Quality** (under PRODUCT QUALITY)
* **Accessories** (under PRODUCT FEATURES)

Numerically, this respondent counts:

* **1** for Picture Quality
* **1** for Sound Quality
* **1 total** for PRODUCT QUALITY (the category)

They do not count twice in the category even though they triggered two topics within it.


# Markdown Block
Source: https://docs.caplena.com/insight-and-reports/insight-elements/markdown-block

Learn how to format text, add images, and create multi-column layouts in your reports.

The **Markdown Block** is a versatile tool in your reporting toolkit that lets you add formatted text, visuals, and tables to make reports more informative and engaging.

<Frame>
  <img alt="Screenshot 2026 05 24 At 17 02 19" />
</Frame>

## Why use the Markdown Block?

Markdown supports lightweight formatting syntax that helps you:

* Structure content with **headers**, **lists**, and **emphasis**
* Embed **images** using simple syntax
* Create **tables and columns** to organize information

## Creating a multi-column layout

One of the Markdown block's most powerful features is multi-column formatting, perfect for side-by-side comparisons or content grouping.

<Frame>
  <img alt="Screenshot 2026 05 24 At 17 03 19" />
</Frame>

<Steps>
  <Step>
    Choose the number of columns (1, 2, or 3).
  </Step>

  <Step>
    Use Markdown tables to define the structure.
  </Step>

  <Step>
    Add your text or images inside each column cell.
  </Step>
</Steps>

<Tip>
  Ideal for presenting product features, pros & cons, or visual + text combinations.
</Tip>

## Prefer visual editing? Use the Rich Text Editor

If you're not familiar with Markdown, the **Rich Text Editor** offers an intuitive formatting experience with:

* **Text formatting** — bold, italic, headers, lists, and links
* **Images** — easily upload and place them in context
* **Tables** — create structured layouts visually
* **Live preview** — see changes instantly as you edit
  <Frame>
    <img alt="Screenshot 2026 05 24 At 17 04 21" />
  </Frame>

## Image sizing and alignment

Markdown offers flexibility in image placement and custom sizing through HTML.

### Resize an image

Click **Edit** on your Markdown block, paste the following, replace `IMAGE_URL_HERE` with your image's URL, and save:

```html theme={null}
<img src="IMAGE_URL_HERE" width="50%"/>
```

<Frame>
  <img alt="Screenshot 2026 05 24 At 17 05 17" />
</Frame>

### Resize and center an image

Click **Edit** on your Markdown block, paste the following, replace `IMAGE_URL_HERE` with your image's URL, and save:

```html theme={null}
<center><img src="IMAGE_URL_HERE" width="50%"/></center>
```

<Frame>
  <img alt="Screenshot 2026 05 24 At 17 06 13" />
</Frame>


# Net Sentiment Score
Source: https://docs.caplena.com/insight-and-reports/insight-elements/net-sentiment-score

How to Interpret and Visualize Net Sentiment in Caplena

The Net Sentiment Score is a key metric used to measure the overall sentiment of your text data. Each comment is classified as positive, negative, or neutral based on its content and the topics assigned to it.

This classification follows the same principles as the Net Promoter Score (NPS), providing a simple and effective way to understand the general sentiment of your feedback.

## How Is the Net Sentiment Score Calculated?

The formula is simple:

> **Net Sentiment Score = % Positive – % Negative**

This results in a score ranging from:

* **+100** → all responses are positive
* **0** → equal balance between positive and negative
* **–100** → all responses are negative

🟢 A **higher score** indicates more positive feedback\
🔴 A **lower score** suggests a predominance of negative sentiment

<Frame>
  <img alt="Screenshot 2026 05 25 At 10 51 21" />
</Frame>

In the screenshot shown above:

* **84.5%** of comments are classified as **positive**
* **13.2%** are **negative**

So the Net Sentiment Score is:

> **84.5 – 13.2 = 71.3**

## Visualizing Net Sentiment

There are **two ways to visualize** Net Sentiment in Caplena using Insight Elements:

### 1. **Net Sentiment (Gauge + Summaries)**

<Frame>
  <img alt="Screenshot 2026 05 25 At 10 52 21" />
</Frame>

No date variable required

This view shows:

* A **gauge** displaying the current score
* An **AI-generated Positive Sentiment Summary**
* An **AI-generated Negative Sentiment Summary**

<Check>
  Best for one-time reports, dashboard overviews, and highlighting what customers like or dislike.
</Check>

### 2. **Net Sentiment Over Time**

<Frame>
  <img alt="Screenshot 2026 05 25 At 10 53 05" />
</Frame>

Date variable required

This view includes:

* A **gauge** displaying the current score
* A **line chart** showing how sentiment changes over time

<Check>
  Best for tracking sentiment development over time or identifying turning points in customer perception.
</Check>

## Choosing the Period for the Gauge

For both views, you can control which period the **gauge** (and any sentiment summary number) reflects using the **Displayed timeframe** option:

* **Most recent period** *(default)* – the gauge shows net sentiment for the most recent time bucket in the report's date range. Use this when the headline should track the latest state of sentiment.
* **Entire period** – the gauge shows net sentiment averaged across the full date range. Use this for a stable benchmark.

The line chart in *Net Sentiment Over Time* is unaffected by this setting — it always shows sentiment across every period in the report's date range. See [Insight Elements – General Overview & Settings](/insight-and-reports/getting-started-with-insight-elements/insight-elements-general-overview-settings) for more on displayed timeframe.

## Use Cases

Use the Net Sentiment Score to:

* Benchmark overall customer sentiment
* Track emotional tone over time (with date variable)
* Supplement or replace metrics like NPS or CSAT


# Topic Breakdown / Heatmap
Source: https://docs.caplena.com/insight-and-reports/insight-elements/topic-breakdown-heatmap

Compare topics across segments, brands, or regions to identify trends and significant differences.

The **Topic Breakdown / Heatmap** is a powerful visualization tool that helps you compare **brands, segments, or regions** across key topics. With **color intensity** and **significance indicators**, it makes spotting trends in large datasets simple and effective.

## Key Components

<Frame>
  <img alt="Topic Breakdown / Heatmap overview" />
</Frame>

1. **Rows** — Represent topics (e.g., *Customer Service*, *Pricing*)
2. **Columns** — Represent segments, brands, or regions (e.g., *Brand One*, *Germany*, *USA*)
3. **Cell values** — Show the **% of responses** that mention a specific topic
4. **Color intensity** — Light blue = lower mention %, dark blue = higher mention %

## Statistically Significant Differences

One of the most valuable features of the Heatmap is its ability to highlight **statistically significant differences** using **yellow boxes** — these flag where a topic is mentioned significantly more or less in one segment versus others.

<Frame>
  <img alt="Statistically significant differences highlighted in yellow" />
</Frame>

For example, if *Customer Service* is mentioned by 39.6% of respondents in Brazil but 80.4% in the USA, that difference is flagged as significant because it's unlikely to be due to chance.

For clearer side-by-side comparison, you can **switch to a bar chart view** — each bar shows topic frequency per segment, and a **★ star** indicates a statistically significant difference (equivalent to the yellow boxes in the heatmap).

<Frame>
  <img alt="Bar chart view with significance stars" />
</Frame>

## Add Sentiment to Your Heatmap

Toggle **sentiment filters** to explore positive, neutral, or negative sentiment per topic and segment.

<Frame>
  <img alt="Sentiment filters on the heatmap" />
</Frame>

* **Spot strengths** — Topics with high positive sentiment
* **Identify weaknesses** — Topics with high negative sentiment
* **Compare across regions** — See how brand perception shifts by location

<Note>
  **Example:** *Customer Service* in **Germany** is mentioned in 12% of responses, mostly with negative sentiment — suggesting potential service issues in that region.
</Note>

## Video Walkthrough

<iframe title="YouTube video player" />


# Topic Correlations & Correlation Explanation
Source: https://docs.caplena.com/insight-and-reports/insight-elements/topic-correlations-correlation-explanation

Understand how Caplena measures the strength of relationships between topics, and how to interpret the results.

The **Topic Correlations** view helps you discover which themes in your data tend to appear together, and the **Correlation Explanation** shows *why* they're connected.

<Frame>
  <img alt="Screenshot 2026 05 25 At 11 23 25" />
</Frame>

## What It Shows

Caplena automatically detects relationships between topics that are frequently mentioned in the same responses. Each row in the table represents a **pair of correlated topics**, showing how strongly they are linked. The **correlation score (r)** tells you the strength of the relationship — higher values mean the topics co-occur more often.

<Note>
  **Example:** **Audio Quality ↔ Visual Quality (r = 0.53)** — respondents who mention sound quality also often talk about picture quality.
</Note>

## Switch Between Views

On the right-hand side, you can explore your correlations in two different views:

### Chord Diagram

A visual map showing how your topics connect.

* Each **bubble** represents a topic.
* **Lines** show connections between topics — the thicker the line, the stronger the correlation.
* **Bubble size** reflects how frequently a topic appears in your dataset.

Hover over a topic to highlight its links, or click to explore specific relationships.

### Correlation Explanation

When you switch to this view, Caplena's AI provides a **written summary** explaining the connection between the selected topics.

<Frame>
  <img alt="Screenshot 2026 05 25 At 11 24 27" />
</Frame>

## How the Correlation Metric Is Calculated

The correlation score is based on the **Kulczyński measure** (pronounced *Kool-chin-ski*). This score ranges from **0 to 1** and shows how likely two topics are to appear together.

* A value **close to 1** means the topics are strongly related.
* A value **close to 0** means they rarely appear together.

Unlike simpler methods, this measure accounts for how often each topic appears individually — so it works well even when one topic is far more common than the other.

### The Idea Behind It

> The Kulczyński score asks: "If I see Topic A, how often do I also see Topic B?" — and vice versa — then takes the average of both directions.

That's why it's great for spotting balanced, meaningful relationships rather than random overlaps.

**Formula:**

```text theme={null}
0.5 * (A / (A + B) + A / (A + C))
```

Where:

* **A** = number of responses mentioning *both* topics
* **B** = number of responses mentioning *only* Topic 1
* **C** = number of responses mentioning *only* Topic 2

**Example calculation:**

To calculate the Kulczyński value between Design and Product:

* Design and Product mentioned together: **A = 100**
* Design mentioned alone (without Product): **B = 20**
* Product mentioned alone (without Design): **C = 80**

```text theme={null}
0.5 * (100 / 120 + 100 / 180) = 0.7
```

### More Examples

| Topic A Mentions | Topic B Mentions | Both Together | Kulczyński | What It Means                                                 |
| :--------------- | :--------------- | :------------ | :--------- | :------------------------------------------------------------ |
| 100              | 100              | 50            | 0.50       | Appear together half the time — moderately related.           |
| 100              | 1                | 1             | 0.505      | Topic B is rare, but always appears with A — noticeable link. |
| 50               | 100              | 50            | 0.75       | Every time A appears, it's with B — strong connection.        |


# Understanding Scores
Source: https://docs.caplena.com/insight-and-reports/insight-elements/understanding-scores

Understand and visualize your key metrics: from NPS to Star Ratings

Caplena provides several ready-to-use **Score / Rating** elements that help you evaluate and visualize how your customers feel about your products, services, or experiences.\
This article explains each score type and how to interpret them in your reports.

## Where to Find Scores

All score-related insights are located under **Score / Rating** in the report editor.\
You’ll find the following elements:

* [Key Metrics Overview](#key-metrics-overview)
* [NPS Score](#nps-score)
* [Generic Score](#generic-score)
* [Star Rating](#star-rating)
* [Multi Score](#multi-score)

Each can be added to your report and customized to display your chosen numerical column.

<Frame>
  <img alt="Score and rating elements in report editor" />
</Frame>

## Key Metrics Overview

The **Key Metrics Overview** provides a quick snapshot of your project’s main metrics. You can use it to get an instant understanding of overall trends without diving into detailed charts.

<Frame>
  <img alt="Screenshot 2026 05 25 At 12 13 41" />
</Frame>

This example shows:

* **Sample size** – total number of responses included (e.g., 112)
* **Average Star Rating** – average of all star ratings in your dataset (e.g., 3.8 ⭐)
* **Net Sentiment** – percentage balance of positive versus negative feedback (e.g., +20.5)

When adding the **Key Metrics Overview** element, you can select which **numerical metric** to display (e.g., *Star Rating*, *NPS Score*).\
You can also choose a **Text to analyze** column,this determines which responses the metrics are based on.

<Tip>
  > **Tip:** If you leave *Text to analyze* blank, **Net Sentiment** won’t be shown.\
  > This is ideal for **non-sentiment projects.**
</Tip>

## NPS Score

The **Net Promoter Score (NPS)** helps you measure customer loyalty by grouping respondents into:

* **Promoters (9–10)**
* **Passives (7–8)**
* **Detractors (0–6)**
  <Frame>
    <img alt="Screenshot 2026 05 25 At 12 15 43" />
  </Frame>

You can visualize:

* **NPS Score Gauge** – your overall score
* **NPS Over Time** – trends across months or quarters

Formula:

> NPS = % Promoters − % Detractors

## Generic Score

The **Generic Score** element lets you visualize any numeric rating in your dataset, for example, satisfaction, quality, or agreement levels, even if your question isn’t a classic NPS one.

<Frame>
  <img alt="Screenshot 2026 05 25 At 12 17 35" />
</Frame>

### How to customize it

Click the ⚙️ icon in the top-right corner of the element to tailor how your score is calculated and displayed.

<Frame>
  <img alt="Screenshot 2026 05 25 At 12 18 23" title="Screenshot 2026 05 25 At 12 18 23" />
</Frame>

Here’s what you can adjust:

* **Score metric** – choose how you want Caplena to calculate the score:
  * *Average* → shows the average of all numeric values
  * *NPS* → calculates Net Promoter Score from 0–10 ratings
  * *Top 1 / Top 2 Buckets* → percentage of responses in the top rating groups
  * *Bottom 1 / Bottom 2 Buckets* → percentage of responses in the lowest rating groups
* **Number of buckets** – define how many segments you want on the gauge (for example, 3 for red, yellow, green).
* **Bucket ranges** – adjust the numeric ranges for each segment manually, or click **Distribute linearly** to let Caplena space them evenly.
* **Displayed timeframe** – choose whether the gauge value reflects the **most recent period** (default) or the **entire period** in the report's date range. The companion trend chart always shows every period. See [Insight Elements – General Overview & Settings](/insight-and-reports/getting-started-with-insight-elements/insight-elements-general-overview-settings) for details.

### Understanding “Buckets”

Buckets divide your rating scale into colored segments, such as:

* **0–5 → red**
* **6–7 → yellow**
* **8–10 → green**

Each bucket represents a group of responses within that range.\
When you select metrics like **Top 1 Bucket**, Caplena shows the share of responses in the highest range (e.g., 72% rated 8–10).

<Frame>
  <img alt="Screenshot 2026 05 25 At 12 19 25" />
</Frame>

## Star Rating

The **Star Rating** element visualizes ratings on a 1–5 scale, often used for:

* App reviews
* Product ratings
* Service feedback
  <Frame>
    <img alt="Screenshot 2026 05 25 At 12 20 07" />
  </Frame>

The element includes two parts:

* **Star Rating Breakdown** — shows how ratings are distributed (e.g., how many 1⭐, 2⭐, 3⭐, etc.)
* **Star Rating Over Time** — tracks how the average star rating changes across months or quarters

Together, they help you quickly spot shifts in customer satisfaction and identify periods of improvement or decline.

## Multi Score

The **Multi Score** element allows you to display up to three score gauges side-by-side , helping stakeholders instantly understand performance across key experience metrics.

Instead of switching between dashboards, you can compare KPIs in a single, executive-ready view.

<Frame>
  <img alt="Screenshot 2026 05 25 At 12 20 40" />
</Frame>

Each gauge in a Multi Score also supports the **Displayed timeframe** option, so you can show either the most recent period or the entire period for every KPI side-by-side.

## Best Practice

* Combine loyalty + satisfaction + pain for a full CX view
* Use bucket metrics when monitoring risk
* Use averages for operational tracking


# Proactive Insights
Source: https://docs.caplena.com/insight-and-reports/proactive-insights/proactive-insights

Surface AI-generated findings automatically inside your reports and review them all in one project-level list.

**Proactive Insights** are findings that Caplena generates automatically from your report views and surfaces in a side rail next to your report. Use them to spot shifts, drivers, and noteworthy patterns without having to ask the Insight Agent each time you open a report.

You can also add your own insights manually to capture observations alongside the AI-generated ones.

## Where you see Proactive Insights

Proactive Insights show up in two places:

* **Report side rail** — a collapsible panel on the right of any report view. The rail header shows the total insight count and the date of the most recent activity. Click the rail to expand it and browse the insight cards.
* **Per insight element** — each insight element shows a small sparkles button when it has related proactive insights attached. Hover or click it to see those insights in a popover, then open one to expand the rail directly to that card.
* **Project-level list** — a dedicated **Proactive Insights** page for the project, where you can browse, filter, and search every insight across all report views.

<Note>
  Proactive Insights are scoped to a saved report view. If you change filters or segments away from the view's saved configuration, the rail is disabled until you reset back to the saved view.
</Note>

## Reading an insight card

Each Proactive Insight card includes:

* **Title** — short summary of what was found.
* **Body** — markdown-formatted explanation, often with supporting numbers or topic references.
* **Chips** — metadata tags such as the source insight element, the public ID, whether the insight is outdated, and whether it was created by a user or by Caplena.
* **Actions menu** — open the details page, edit (for manual insights), or dismiss the insight.

Dismissed insights are hidden from the rail and the count, but remain available in the project-level list if you filter for them.

## Resizing and persisting the rail

Drag the left edge of the expanded rail to resize it. Caplena remembers your preferred width across reloads, so the rail opens at the same size next time you visit the report.

## Adding a manual insight

When you are in **view edit mode**, you can add your own insight to a report view:

1. Open the report in edit mode.
2. In the Proactive Insights rail (or the empty-state **Add insight** button on an insight element), click **Add insight**.
3. Enter a **title** and write the **content** using the markdown editor.
4. Click **Save**.

Your insight appears in the rail and the project-level list alongside AI-generated ones, marked as user-created so it's clear who authored it.

<Tip>
  Manual insights are useful for pinning analyst commentary, decisions made in review meetings, or context that the AI doesn't have access to (for example, a known data quality caveat).
</Tip>

## Disabled state: filters or segments diverge from the view

Proactive Insights are tied to the saved configuration of a report view. When you change the report's filters or segments so that they no longer match the saved view, the rail is disabled and the button shows a popover explaining why.

Click **Reset** in the popover to restore the view's saved filters and segments. The rail re-enables and shows insights again.

## Project-level Proactive Insights list

Open the **Proactive Insights** tab on a project to see every insight across all the project's report views in one place.

The list supports:

* **Toolbar filters** — narrow down by report view, insight element, source, status, and more.
* **Search and pagination** — find a specific insight quickly when you have many.
* **Back-to-report navigation** — open an insight in the original report view where it was generated, with the rail expanded on that insight.

Use the list view when you want a cross-cutting overview — for example, to triage new insights at the start of the week, or to find every insight that mentions a particular topic across all your views.


# Sharing Reports
Source: https://docs.caplena.com/insight-and-reports/sharing-reports/sharing-reports

Share insights with your team and external stakeholders.

Once your report is built, it's time to share your insights — whether with internal teams or external stakeholders. Caplena makes it easy to collaborate while maintaining control over who sees what and how they interact with your report.

## How to access sharing options

Open the report you want to share and click the blue **Share** button in the top-right corner. A pop-up window will appear with internal and external sharing options.

<Frame>
  <img alt="Screenshot 2026 05 30 At 16 44 31" />
</Frame>

## Control which columns recipients can see

When sharing a specific view, you can choose which data columns are visible to recipients. This lets you share a report with stakeholders while hiding columns that aren't relevant to them — or that contain sensitive information.

In the sharing modal, scroll to **Visible columns** and uncheck any columns you want to hide. By default, all columns are visible. Recipients will only see the columns you've enabled — they cannot unhide them.

<Warning>
  The column used as the date axis and any column used as a row weight stay visible, they're required for the report to render correctly and can't be hidden.
</Warning>

<iframe title="Loom video player" />

<Warning>
  If a hidden column is used as a **global source** (e.g. for segments or filters across the report), the view will show the following message:
</Warning>

<Frame>
  <img alt="Screenshot 2026 06 07 At 16 15 57 1" />
</Frame>

Recipients also can't see the configured values behind filters, segments, or widget buckets that reference a hidden column. The filter or bucket still applies to the report, but its values — for example the keywords in a text-contains filter or the categories in a bucket — are redacted in the view. This keeps sensitive setup details (such as PII used in a saved filter) private even when a filtered view is shared.

Recipients also can't see the configured values behind filters, segments, or widget buckets that reference a hidden column. The filter or bucket still applies to the report, but its values — for example the keywords in a text-contains filter or the categories in a bucket — are redacted in the view. This keeps sensitive setup details (such as PII used in a saved filter) private even when a filtered view is shared.

<Tip>
  Use this together with locked filters to create fully tailored views for different audiences — the right data, filtered to the right segment, with only the relevant columns showing.
</Tip>

## Share with team members

Share your report with other Caplena users by granting them access to the full report or a specific view.

<Frame>
  <img alt="Clean Shot 2026 03 19 At 09 39 44 (2) 1" />
</Frame>

<Steps>
  <Step title="Open sharing">
    Click the **Share** button in the top right corner of your report.
  </Step>

  <Step title="Choose what to share">
    Select a specific view (e.g. "French View") or the full report.
  </Step>

  <Step title="Add people">
    Enter teammates' email addresses in the **People with access** section and choose their access level — **View** for read-only, **Edit** for full access.
  </Step>

  <Step title="Confirm">
    Click **Done**.
  </Step>
</Steps>

<Tip>
  Use "View" access for stakeholders who just need to read, and "Edit" for collaborators who help build or update reports.
</Tip>

## Share externally (public link)

Generate a shareable public link to your selected views for people outside your organization.

<iframe title="Loom video player" />

<iframe title="Loom video player" />

<iframe title="Loom video player" />

<Steps>
  <Step title="Open sharing">
    Open your report and click **Share** on the right-hand side.
  </Step>

  <Step title="Choose scope">
    Select **This view only** or **All views**.
  </Step>

  <Step title="Configure the link">
    Optionally set a link name, password, or expiration date.
  </Step>

  <Step title="Copy and send">
    Click **Copy link** and send it to your stakeholders.
  </Step>
</Steps>

## Share filtered report views

When you share a report view, you can predefine which filters apply — sending personalized links to different stakeholders:

* A **marketing team** sees only feedback from their region
* A **product team** sees only comments about specific features
* A **country manager** sees only data from their market

<iframe title="Loom video player" />

<iframe title="Loom video player" />

<iframe title="Loom video player" />

<Steps>
  <Step title="Create a new view">
    Open your report and click **+ New View** on the left sidebar.
  </Step>

  <Step title="Apply filters">
    Apply the filters you want and give the view a clear name (e.g. "Report for Marketing Department").
  </Step>

  <Step title="Lock your filters">
    Lock the filters — this ensures recipients cannot remove or change them.
  </Step>

  <Step title="Share">
    Click **Share report & views** → choose the filtered view → copy the share link or embed code. Optionally add a password or expiration date.
  </Step>
</Steps>

<Tip>
  If you enable **Insight Agent**, recipients can ask AI-based questions about their filtered data only — helping them explore insights safely without accessing the full dataset.
</Tip>

## Embed a report in other platforms

<iframe title="YouTube video player" />

<iframe title="YouTube video player" />

<iframe title="YouTube video player" />

<Steps>
  <Step title="Create a view">
    Create and configure a **View** and enable **Shareable Link**.
  </Step>

  <Step title="Copy embed code">
    Click **Copy embed code** and paste it into any HTML-supported platform.
  </Step>
</Steps>

The embedded version always stays up to date with the latest edits in Caplena. No Caplena account is required for external viewers. You can still set passwords or expiration dates for access control.

## Embed in Power BI

<iframe title="Loom video player" />

<iframe title="Loom video player" />

<iframe title="Loom video player" />


# Integrations
Source: https://docs.caplena.com/integrations

Connect external platforms, automate data imports, and push insights to your team's tools.

<CardGroup>
  <Card title="How Integrations Work" href="/integrations/integrations-in-caplena-overview" icon="circle-info">
    Sync cycles, billing, and how integration items work.
  </Card>

  <Card title="Review Platforms" href="/integrations/review-platforms" icon="star">
    Google Maps, App Stores, Trustpilot, Tripadvisor, and more.
  </Card>

  <Card title="Survey & CX Platforms" href="/integrations/connected-accounts" icon="arrow-down-to-bracket">
    Qualtrics, Medallia, SurveyMonkey, Intercom, Zendesk, and more.
  </Card>

  <Card title="Slack & Teams" href="/integrations/outbound-accounts-microsoft-teams-slack-and-more" icon="comments">
    Query your feedback data from Slack or Microsoft Teams.
  </Card>

  <Card title="MCP" href="/integrations/mcp" icon="robot">
    Query projects in natural language from any MCP-compatible client.
  </Card>
</CardGroup>


# ChatGPT
Source: https://docs.caplena.com/integrations/chatgpt

Connect Caplena Insight Agent to ChatGPT using the Model Context Protocol (MCP).

Connect your Caplena workspace to ChatGPT using the Model Context Protocol (MCP) to query feedback data, summarize projects, and analyze customer comments directly from ChatGPT.

<Note>
  Custom MCP servers require a **ChatGPT Plus, Pro, Business, Enterprise, or Edu** subscription. **Developer Mode** must be enabled.

  Availability of custom MCP servers may vary by account, workspace, and region.
</Note>

## Before You Start

Before connecting Caplena, make sure that:

* You have a Caplena account.
* At least one Caplena project is set to **Live**.
* You have a supported ChatGPT subscription.
* Developer Mode is available on your ChatGPT account.

<Tip>
  Only projects set to **Live** are available through the Insight Agent.

  [Learn how to set a project to Live →](/get-started/project-settings/setting-a-project-to-live)
</Tip>

***

## Step 1: Enable the Insight Agent in Caplena

<Frame>
  <img alt="Screenshot 2026 06 28 At 18 06 19" />
</Frame>

1. Go to **Settings → Integrations** inside Caplena.
2. Locate the **Insight Agent (MCP)** integration and click **Enable**. Confirm the installation.
3. Copy the generated **MCP URL**\
   (e.g., `https://api.caplena.com/v2/outbound-connectors/mcp`).

## Step 2: Enable Developer Mode in ChatGPT

<Frame>
  <img alt="Screenshot 2026 06 28 At 18 30 38" />
</Frame>

1. Open ChatGPT and click your profile picture in the bottom-left corner.
2. Choose **Settings**, then navigate to **Apps → Advanced settings**.
3. Turn on **Developer Mode**.

This allows ChatGPT to connect to custom MCP servers.

## Step 3: Create the Caplena App

<Frame>
  <img alt="Screenshot 2026 06 28 At 18 31 40" />
</Frame>

1. Go to **Settings → Apps** and click **Create**.
2. Fill in the following:
   * **Name:** Caplena
   * **MCP Server URL:** paste the URL copied from Caplena
3. ChatGPT automatically discovers the OAuth issuer, authorization endpoint, token endpoint, Dynamic Client Registration, and supported scopes from the MCP server — no manual entry required.
4. Review the detected configuration and click **Create**.
5. You'll be redirected to Caplena. Sign in if necessary, review the requested permissions, and click **Authorize**.
6. You'll be redirected back to ChatGPT with the connection active.

## Step 4: Start Using Caplena

Start a **new ChatGPT conversation**.

Enable the **Caplena** app from the available Apps/Tools menu.

You can now ask questions such as:

> List the projects I have access to.

> Summarize the latest customer feedback.

> What are the top themes in our NPS survey?

> Compare the latest wave with the previous quarter.

> Show me comments mentioning delivery delays.

<Note>
  The first time ChatGPT accesses Caplena, it may ask for your permission.

  You can choose **Always allow** if you don't want to approve every request individually.
</Note>

***

## Advanced: Deep Research with Caplena Data

ChatGPT's **Deep Research** feature can combine your Caplena feedback data with web sources in a single research task — useful for contextualizing customer feedback against external information.

Example prompts:

> Using my Caplena NPS project and recent industry reports, write a competitive analysis of how our product perception compares to the market.

> Cross-reference the top complaints from my Caplena support feedback with publicly reported issues for \[competitor] and summarize the gaps.

> Based on my Caplena Q1 feedback and current market trends, draft a product prioritization recommendation.

To use it: open a chat, click **Deep Research** under the input field, add Caplena as a source, and enter your prompt.

<Note>
  Deep Research is available on ChatGPT **Pro** and higher plans.
</Note>

***

## Troubleshooting

### I don't see "Developer Mode"

Developer Mode is only available for supported ChatGPT plans and may not yet be enabled for every account or workspace.

### Authentication fails

Make sure:

* your MCP installation is enabled in Caplena
* you're signing in with the correct Caplena account
* your project is set to **Live**

### No projects are returned

Only **Live** projects are accessible through the Insight Agent.

Check that:

* the project is Live
* your Caplena user has permission to access it

### Do I need to copy the OAuth configuration?

No.

ChatGPT automatically discovers the OAuth configuration from the MCP server.

The additional OAuth details displayed in Caplena are primarily intended for MCP clients that require manual configuration.


# Survey & CX Platforms
Source: https://docs.caplena.com/integrations/connected-accounts

Connect Qualtrics, Medallia, SurveyMonkey, Intercom, Salesforce, Zendesk and more for automatic daily sync

Connect your survey or CX platforms directly to Caplena to import feedback automatically. These integrations use authenticated API access to pull new responses daily, so you can analyze open-ended feedback without manual exports.

## Brandwatch

Our Brandwatch integration allows you to seamlessly import social media query results directly into Caplena for analysis.

<Steps>
  <Step title="Open Integrations Settings">
    Log in to your Caplena account. Navigate to **Account Settings → Integrations**. Select **Brandwatch** from the available options.

    <Note>
      [Here](/settings-administration/general-settings/general-settings-overview) you can find more info on the Settings page
    </Note>
  </Step>

  <Step title="Add Your Brandwatch Account">
    Click **Add Account** and fill in the following fields:

    <Frame>
      <img alt="Screenshot 2026 05 26 At 08 39 23" />
    </Frame>

    * **Connection name** – Give your connection a unique name
    * **Username** – Your Brandwatch username
    * **Password** – Your Brandwatch password
    * **Project name** – You can find this in your Brandwatch account
  </Step>

  <Step title="Connect the Account">
    Click **Add Integration** to authorize.
  </Step>

  <Step title="Import Brandwatch Data">
    Go to **Projects → Import Data → Brandwatch**. Choose the account and specific survey you'd like to import.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 08 38 17" />
    </Frame>
  </Step>
</Steps>

## Qualtrics

<Steps>
  <Step title="Access Integration Settings">
    Log in to your Caplena account. Navigate to **Account Settings → Integrations → Qualtrics**.

    <Note>
      [Here](/settings-administration/general-settings/general-settings-overview) you can find more info on the Settings page
    </Note>
  </Step>

  <Step title="Set Up OAuth in Qualtrics">
    Create an OAuth client in Qualtrics following the [official guide](https://api.qualtrics.com/). You'll receive a **Client ID** and **Client Secret**. Required scopes: `read:users`, `read:surveys`, `read:survey_responses`.
  </Step>

  <Step title="Fill in Connection Details">
    Click **Add Account** and complete:

    <Frame>
      <img alt="Screenshot 2026 05 26 At 08 42 12" />
    </Frame>

    * **Connection Name** – A custom label (e.g. "Client A – Q Feedback")
    * **Client ID** – From your Qualtrics OAuth setup
    * **Client Secret** – From your Qualtrics OAuth setup
    * **Datacenter** – Found in Account Settings → Qualtrics IDs → User
  </Step>

  <Step title="Connect and Import">
    Click **Add Integration**. Then go to **Projects → Import Data → Qualtrics** and select the desired account and survey.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 08 48 34" />
    </Frame>
  </Step>
</Steps>

## Medallia

<Steps>
  <Step title="Access Integration Settings">
    Log in to your Caplena account. Navigate to **Account Settings → Integrations → Medallia**.

    <Note>
      [Here](/settings-administration/general-settings/general-settings-overview) you can find more info on the Settings page
    </Note>
  </Step>

  <Step title="Fill in Connection Details">
    Click **Add Integration** and complete:

    <Frame>
      <img alt="Screenshot 2026 05 26 At 08 50 54" />
    </Frame>

    * **Connection Name** – e.g. `Medallia_NPS_Q4_2025`
    * **Client ID** – Provided by your Medallia administrator
    * **Client Secret** – A secure key that works with your Client ID
    * **Token URL** – e.g. `https://login.medallia.com/oauth/token`
    * **Query** – The specific API endpoint to retrieve your feedback data

    If unsure about any values, contact your Medallia administrator.
  </Step>

  <Step title="Connect and Import">
    Click **Add Integration**. Then go to **Projects → Import Data → Medallia** and select the account.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 09 34 22" />
    </Frame>
  </Step>
</Steps>

## QuestionPro

<Steps>
  <Step title="Get your API Key and User ID">
    Generate your API key using [QuestionPro's instructions](https://www.questionpro.com/help/customer-experience/generate-api-key-in-cx.html). Find your User/Customer ID under **My Account → Partner License**.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 09 36 09" />
    </Frame>
  </Step>

  <Step title="Connect in Caplena">
    Go to **Settings → Integrations → Add Integration → QuestionPro**. Fill in:

    <Frame>
      <img alt="Screenshot 2026 05 26 At 16 49 50" />
    </Frame>

    * **Connection name** – Any name to help you recognize the integration
    * **API key** – Paste the API key you generated
    * **User ID** – Paste your QuestionPro Customer ID
    * **Environment** – Choose Production unless using a sandbox

    Click **Add Integration**.
  </Step>
</Steps>

## SurveyMonkey

<Steps>
  <Step title="Create an App in SurveyMonkey">
    Go to the [SurveyMonkey Developer Portal](https://developer.surveymonkey.com/apps/). Click **Create App**, give it a name (e.g. "Caplena Integration"), and choose **Private App**.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 16 55 24" />
    </Frame>
  </Step>

  <Step title="Configure Scopes">
    Open the app settings and under **Scopes**, enable at minimum the required read scopes.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 16 56 47" />
    </Frame>
  </Step>

  <Step title="Generate and Copy Your Access Token">
    In the app menu, go to **Credentials → Generate Access Token**. Copy the token — you'll need it in Caplena.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 16 57 56" />
    </Frame>
  </Step>

  <Step title="Connect in Caplena">
    Go to **Integrations → SurveyMonkey**, paste the Access Token, and save.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 16 59 39" />
    </Frame>
  </Step>
</Steps>

## Google Cloud Storage (GCS)

Connect a file stored in GCS so your project refreshes automatically overnight.

<Steps>
  <Step title="Set Up Google Cloud Storage">
    Complete the following in Google Cloud:

    * [Create a bucket](https://cloud.google.com/storage/docs/creating-buckets)
    * [Create a Service Account and JSON Key](https://cloud.google.com/iam/docs/service-accounts-create)
    * [Grant the Service Account access to your bucket](https://cloud.google.com/storage/docs/access-control/using-iam-permissions)
    * Copy your file's GCS URI (e.g. `gs://your-bucket-name/path/to/file.csv`)

    Supported formats: `.csv` and `.parquet`. Your file must include an identifier column and a date column.
  </Step>

  <Step title="Set Up Google Cloud Storage">
    Complete the following in Google Cloud:

    * [Create a bucket](https://cloud.google.com/storage/docs/creating-buckets)
    * [Create a Service Account and JSON Key](https://cloud.google.com/iam/docs/service-accounts-create)
    * [Grant the Service Account access to your bucket](https://cloud.google.com/storage/docs/access-control/using-iam-permissions)
    * Copy your file's GCS URI (e.g. `gs://your-bucket-name/path/to/file.csv`)

    Supported formats: `.csv` and `.parquet`. Your file must include an identifier column. On each sync, Caplena scans the full file and imports any new rows.
  </Step>

  <Step title="Connect in Caplena">
    Go to **Integrations → Add Integration → Google Storage File (GStorageFile)**. Fill in:

    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 00 35" />
    </Frame>

    * **Connection name** – Any name to help you recognize this connection
    * **Credentials** – Paste the entire JSON content of your service account key (do not upload a file — paste the JSON text)

    Click **Add Integration**.
  </Step>

  <Step title="Configure Data Import">
    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 02 32" />
    </Frame>

    * **Account** – Select the integration you just created
    * **File URL** – Paste your `gs://` file URI
    * **Identifier column name** – The column that uniquely identifies each row (e.g. `id`, `response_id`)
    * **Date column name** – The date/timestamp column used to detect new data (e.g. `created_at`)
    * **Source name** (optional) – A label that will appear in your project
  </Step>

  <Step title="Configure Data Import">
    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 02 32" />
    </Frame>

    * **Account** – Select the integration you just created
    * **File URL** – Paste your `gs://` file URI
    * **Identifier column names** – One or more columns that together uniquely identify each row (e.g. `id`, `response_id`). Caplena uses these to detect new rows on each sync. To use multiple columns, enter them as a comma-separated list (e.g. `respondent_id, submitted_at`).
    * **Source name** (optional) – A label that will appear in your project
  </Step>
</Steps>

## Azure Blob Storage

Connect a file stored in Azure Blob Storage so your project refreshes automatically overnight.

<Steps>
  <Step title="Generate a Connection String in Azure">
    In the [Azure Portal](https://portal.azure.com), open your **Storage account → Containers** and select the container that holds your file. Open **Shared access tokens** and configure:

    * **Permissions** – Enable **Read**
    * **Allowed protocols** – Select **HTTPS only**
    * **Expiry** – Set an expiration date that fits your sync schedule
    * Click **Generate SAS token and URL**

    From the result, build a connection string in the form:

    ```text theme={null}
    BlobEndpoint=https://<your-account>.blob.core.windows.net/;SharedAccessSignature=<sas-token>
    ```

    Use the **Blob service SAS URL** for the `BlobEndpoint` value (without the SAS query string) and the **SAS token** (without the leading `?`) for `SharedAccessSignature`.

    Supported formats: `.csv` and `.parquet`. Your file must include an identifier column. On each sync, Caplena scans the full file and imports any new rows.
  </Step>

  <Step title="Connect in Caplena">
    Go to **Integrations → Add Integration → Azure Blob**. Fill in:

    * **Connection name** – Any name to help you recognize this connection
    * **Connection string** – Paste the `BlobEndpoint=...;SharedAccessSignature=...` string built in the previous step

    Click **Add Integration**.
  </Step>

  <Step title="Configure Data Import">
    Go to **Projects → Import Data → Azure Blob** and fill in:

    * **Account** – Select the integration you just created
    * **Blob URL** – The full URL to your blob (e.g. `https://<your-account>.blob.core.windows.net/<container>/path/to/file.csv`)
    * **Identifier column names** – One or more columns that together uniquely identify each row (e.g. `id`, `response_id`). Caplena uses these to detect new rows on each sync. To use multiple columns, enter them as a comma-separated list (e.g. `respondent_id, submitted_at`).
    * **Source name** (optional) – A label that will appear in your project
  </Step>
</Steps>

## Decipher

<Steps>
  <Step title="Generate Your Decipher API Key">
    In your Decipher account, open the user menu (top right) → **API Access → Create API key**.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 05 07" />
    </Frame>

    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 06 16" />
    </Frame>
  </Step>

  <Step title="Connect in Caplena">
    Navigate to **Account Settings → Integrations → Decipher**. Click **Add Account** and fill in:

    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 07 26" />
    </Frame>

    * **Connection name** – e.g. "Decipher – US Surveys"
    * **Decipher API key** – Paste the key generated above
    * **Query URL** – Your Decipher instance URL

    Click **Add Integration**.
  </Step>

  <Step title="Import Data">
    Go to **Projects → Import Data → Decipher** and choose the survey to import.
  </Step>
</Steps>

## Intercom

<Steps>
  <Step title="Add Your Intercom Account">
    Navigate to **Account Settings → Integrations → Intercom**. Click **Add Account** and fill in:

    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 15 19" />
    </Frame>

    * **Connection name** – e.g. "Intercom Production"
    * **Access token** – From your [Intercom Developer Hub](https://developers.intercom.com/)
    * **Region** – US (`api.intercom.io`), EU (`api.eu.intercom.io`), or AU (`api.au.intercom.io`)

    Click **Add Integration**.
  </Step>

  <Step title="Import Data">
    Go to **Projects → Import Data → Intercom**. Choose your Account and Survey type.

    <Frame>
      <img alt="Screenshot 2026 05 26 At 17 17 26" />
    </Frame>

    Configure optional settings:

    * Initial import limit, start/end date
    * Conversation state (open, closed, snoozed)
    * Source type (Conversation, Email, WhatsApp, etc.)
    * Tag IDs

    Enable **Synchronize data sources** for automatic daily sync. Click **Continue**.
  </Step>
</Steps>

## Salesforce

Connect Salesforce to import survey responses into Caplena for analysis. Caplena authenticates through the OAuth **Client Credentials Flow**, which runs as a dedicated API-only user. Setting this up requires a few steps inside Salesforce before you add the connection in Caplena.

<Note>
  The Salesforce setup UI is dense and changes between editions. We recommend having a Salesforce administrator complete the steps below, as they require permission to create users, permission sets, and connected apps.
</Note>

<Steps>
  <Step title="Create a Permission Set">
    In Salesforce, go to **Setup → Users → Permission Sets** and create a new permission set.\\

    <Frame>
      <img alt="Screenshot 2026 06 08 At 11 08 18" />
    </Frame>

    * Under **System Permissions**, enable **API Only User** and **API Enabled**.
    * Under **Apps → Object Settings**, open **Surveys** and **Survey Responses** and enable **Read**, **View All Records**, and **View All Fields** for each.
  </Step>

  <Step title="Create an API-only User">
    Go to **Setup → Users → Users** and create a new user.\\

    <Frame>
      <img alt="H1oq W" />
    </Frame>

    * **User License:** Salesforce
    * **Profile:** Minimum Access - Salesforce
    * **Permission Set Assignments:** assign the permission set created in the previous step.
  </Step>

  <Step title="Create an External Client App">
    Go to **Setup → Apps → App Manager → New External Client App**.

    <Frame>
      <img alt="Salesforce Create New External Client App 2048x1064" />
    </Frame>

    * Under **API (Enable OAuth Settings)**, check **Enable OAuth**.
    * **Callback URL:** any value works and is not used by this flow (e.g. `https://localhost`).
    * **OAuth Scopes:** add **Manage user data via APIs (api)**.
    * Under **Flow Enablement**, check **Enable Client Credentials Flow**, then click **Create**.
    * Open the app's **Policies → OAuth Flows and External Client App Enhancements**, check **Enable Client Credentials Flow**, and set the **Run As** user to the API-only user created in the previous step.
    * Open **Settings → OAuth Settings** and copy the **Consumer Key** and **Consumer Secret** — you'll need these in Caplena.
  </Step>

  <Step title="Open Integration Settings in Caplena">
    Log in to your Caplena account. Navigate to **Account Settings → Integrations** and select **Salesforce**.

    <Note>
      [Here](/settings-administration/general-settings/general-settings-overview) you can find more info on the Settings page.
    </Note>
  </Step>

  <Step title="Add Your Salesforce Account">
    Click **Add Account** and fill in:\
    \\

    <Frame>
      <img alt="Screenshot 2026 06 08 At 14 18 52" title="Screenshot 2026 06 08 At 14 18 52" />
    </Frame>

    * **Connection name** – e.g. "Salesforce Production"
    * **Client ID** – The Consumer Key from your External Client App
    * **Client Secret** – The Consumer Secret from your External Client App
    * **Instance URL** – Your Salesforce instance URL (e.g. `https://yourorg.salesforce.com`)

    Click **Add Integration**. Once connected, Salesforce appears in your list of integrations.
  </Step>

  <Step title="Import Salesforce Data">
    Go to **Projects → Import Data → Salesforce**. Choose your connected **Account** and optionally filter responses by **Status**:

    <Frame>
      <img alt="Screenshot 2026 06 08 At 14 20 23" />
    </Frame>

    * Completed
    * In Progress
    * Started
    * Partially Completed

    Leave the filter empty to import all responses. Enable **Synchronize data sources** for automatic daily sync.
  </Step>
</Steps>

## Zendesk

Import and analyze Zendesk ticket data and CSAT responses directly in Caplena.

<Steps>
  <Step title="Set up OAuth in Zendesk">
    Before connecting to Caplena, create an OAuth client in your Zendesk account. Follow the [official Zendesk documentation](https://developer.zendesk.com/documentation/live-chat/getting-started/auth/) and use these settings:

    * **Redirect URL** – `https://api.caplena.com/api/ui/integrations/zendesk/oauth/callback`
    * **Client kind** – Confidential
      <Frame>
        <img alt="Screenshot 2026 05 26 At 18 19 49 1" />
      </Frame>

    <Warning>
      Copy your **Client Secret** during setup — Zendesk will not display it again once you leave the page.
    </Warning>
  </Step>

  <Step title="Open Integration Settings in Caplena">
    Log in to your Caplena account. Navigate to **Account Settings → Integrations**. In the top-right section, select **Zendesk**.

    <Note>
      [Here](/settings-administration/general-settings/general-settings-overview) you can find more info on the Settings page.
    </Note>
  </Step>

  <Step title="Add Your Zendesk Account">
    Click **Add Account** and fill in:

    <Frame>
      <img alt="Screenshot 2026 05 27 At 15 34 11" title="Screenshot 2026 05 27 At 15 34 11" />
    </Frame>

    * **Connection name** – e.g. "Zendesk Production"
    * **Client ID** – The "Identifier" from your OAuth setup in Zendesk
    * **Client secret** – The secret copied during OAuth setup
    * **Company subdomain** – e.g. `yourcompany` for `yourcompany.zendesk.com`
  </Step>

  <Step title="Connect the Account">
    Click **Add Integration**. You'll be redirected to Zendesk — approve the read-only permissions. Once done, Zendesk appears in your connected integrations list.
  </Step>

  <Step title="Import Zendesk Data">
    Go to **Projects → Import Data → Zendesk**. Choose your connected **Account** and the **data type** to import (tickets or CSAT responses).

    <Frame>
      <img alt="Screenshot 2026 05 27 At 15 36 41" />
    </Frame>
  </Step>
</Steps>

## Frequently asked questions

**What happens if I delete columns in Caplena?** The data from Medallia or Qualtrics that corresponded to those columns will no longer sync. Synchronization continues, but without updating the removed columns.

**What happens if I add new columns manually in Caplena?** New columns added manually will not be filled by Medallia or Qualtrics syncs. They will remain empty unless populated manually.

**What happens if I add new columns in Medallia or Qualtrics?** New columns added in your source platform will not be included automatically. They won't appear in Caplena unless the query used in the integration is updated accordingly.


# How Integrations Work
Source: https://docs.caplena.com/integrations/integrations-in-caplena-overview

How data sources, integration items, syncing, and credits work

Another way to import data into Caplena is by using **direct integrations** with external platforms such as Google Maps, Trustpilot, Tripadvisor, Qualtrics, and more.

<Frame>
  <img alt="Screenshot 2026 05 25 At 17 23 12" />
</Frame>

To make integrations easier to understand and manage, it helps to distinguish between **review platforms** and **survey & CX platforms**, as well as how data is structured and synchronized.

## How integrations work in Caplena

Each integration in Caplena consists of one or more **integration items**. You can think of integration items as the **specific resources you want to analyze**, such as:

* Reviews for a specific location on Google Maps
* Reviews for an app in Trustpilot
* Survey responses from a connected survey project

**Example:**

<Frame>
  <img alt="Screenshot 2026 05 25 At 17 24 59" />
</Frame>

If you want to compare three retail locations:

1. You create a **Google Maps integration**
2. Within that integration, you add 3 integration items as shown above
3. Caplena combines the data from these integration items into a **single project**, allowing you to analyze them together

One integration can contain **many integration items**.

## Syncing data automatically

A key benefit of using integrations is **automatic synchronization**. Caplena supports two types of sync cycles depending on the integration used:

**Review Platforms (public review sources)** → Synced every 3 days

This applies to platforms where Caplena collects publicly available ratings and written reviews (e.g. Google Places, Trustpilot, App Store, etc.). If a sync runs today, the next one happens in three days, at which point all reviews posted within that period are imported in one batch.

**Survey & CX Platforms (authenticated data connections)** → Synced daily

Includes sources where you connect your account directly via login/API (e.g. Qualtrics, Medallia, SurveyMonkey). These sync once per day at 2 am UTC and pull in new responses continuously.

You can turn synchronization off anytime from the **Data Sources** page by toggling it off in the integration item settings. If you have a lot of items, you can also do this in bulk.

<Frame>
  <img alt="Screenshot 2026 05 25 At 17 27 29" />
</Frame>

## Billing & credits

* Integrations themselves do **not** incur extra fees
* Imported texts cost **1 credit per text**, just like any other upload
* Credits are only deducted **when the project is saved**
* With synchronization enabled, credits are deducted automatically as new data is imported
* Caplena provides an **estimate of the number of reviews** per integration item before the initial upload

<Tip>
  **Example:** 3 Google Maps locations with \~1,000 reviews each → **3,000 credits** (initial import). If daily sync adds 10 new reviews per location → **30 credits per day**.
</Tip>

## What to read next

<CardGroup>
  <Card title="Review Platforms" icon="star" href="/integrations/review-platforms">
    Learn which public review sources are supported and what data is imported.
  </Card>

  <Card title="Survey & CX Platforms" icon="arrow-down-to-bracket" href="/integrations/connected-accounts">
    Connect Qualtrics, Medallia, SurveyMonkey, and more for automatic daily sync.
  </Card>
</CardGroup>


# MCP (Model Context Protocol)
Source: https://docs.caplena.com/integrations/mcp

Connect Caplena to any MCP-compatible client and query your feedback data in natural language.

Caplena supports the **Model Context Protocol (MCP)**, an open standard that lets you connect your Caplena projects directly to any MCP-compatible client. Once connected, you can ask questions about your feedback data in plain language, without opening Caplena at all.

MCP works with a growing range of clients — **Claude Desktop**, Cursor, and others. The walkthrough below uses **Claude Desktop** as an example, but the same Caplena MCP URL works in any client that supports custom connectors.

## What This Lets You Do

Instead of opening Caplena, building filters, and reading through charts, you just ask a question and get an answer. For example:

* "What are the top complaints in my NPS project this week?"
* "How has sentiment changed over the past month in my support feedback project?"
* "Summarize the most common themes across my Q1 and Q2 projects."

The real power lies in combining Caplena data with other tools and files in the same conversation:

* "Get the top 3 issues in Germany, France and the US and create a 4-slide PowerPoint deck from this with our corporate template."
* "Find app issues mentioned in the past 2 days and create a Jira ticket for every one of them."
* "For each of the three strategic priorities outlined in the Strategy.docx file, create an executive summary of the voice of the customer related to the initiative, both qualitative and quantitative."

<Tip>
  The real power comes from combining the Caplena MCP with other connectors in your AI app, such as Atlassian, Microsoft 365, or Jira, so you can pull customer insights directly into documents, tickets, and emails without switching tools.
</Tip>

This is especially useful for:

* **Stakeholders and non-analysts** who use an MCP client but don't work in Caplena day-to-day — they can get answers without needing to know how to navigate the platform.
* **Combining Caplena data with other context** — the client can look at your feedback data alongside a document, spreadsheet, or email in the same conversation.

## Before You Start

* You have a Caplena account with at least one project set to **Live**.
* You have an **MCP-compatible client** installed — this guide uses **Claude Desktop** as the example.

<Tip>
  Only projects set to "Live" are accessible via the MCP connection. You can check this on the project overview page, if a project shows as "not discoverable", just enable Live mode. [Learn how →](/get-started/project-settings/setting-a-project-to-live)
</Tip>

## Step 1: Enable MCP in Caplena

1. In Caplena, go to **Settings → Integrations**.
2. Under **Connected Outbound Accounts**, find the MCP tile and click **Enable**.
3. A modal appears. Click **Enable** again to confirm.
4. Copy the **MCP URL** shown in the modal. This is the URL you'll add to your MCP client.

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 45 47" />
</Frame>

## Step 2: Add Caplena as a Custom Connector

These steps use **Claude Desktop** as the example client. In another MCP client, add a custom connector or server using the same Caplena MCP URL.

1. Open **Claude Desktop** and go to **Settings → Connectors**.
2. Click **Add custom connector**.

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 47 01" />
</Frame>

3. In the modal that appears, fill in:
   * **Name:** Caplena
   * **URL:** the MCP URL you copied in Step 1
4. Click **Add**.

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 48 45" />
</Frame>

## Step 3: Authorize the Connection

1. Caplena appears in your connectors list. Click **Connect**.
2. You'll be redirected to Caplena. If you're not already logged in, you'll be asked to sign in.
3. An authorization screen appears asking you to grant the client access to your Caplena data. In Claude Desktop this reads **Authorize Claude?** — click **Authorize**.
4. You'll be sent back to your client and should see a **"Connected to Caplena"** confirmation message.

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 49 51" />
</Frame>

## Step 4: Start Querying Your Data

In your MCP client, try: *"List the projects that you can access on Caplena."*

The client will ask for your permission to use its Caplena tools. Grant access when prompted — in Claude Desktop, click **Always allow** (you may be asked twice: once to query Caplena, once to use the Retrieve tool).

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 52 16" />
</Frame>

After a moment, you'll see all your Live projects listed with their names and row counts.

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 55 07" />
</Frame>

<Note>
  By default, your MCP client may ask for your approval each time it queries Caplena. You can change this to **Always allow** to skip the confirmation on every request.
</Note>

## Video Walkthrough

<iframe title="Loom video player" />


# Microsoft 365 Copilot
Source: https://docs.caplena.com/integrations/microsoft-copilot-studio

Connect Caplena Insight Agent to Microsoft 365 Copilot using MCP.

Query your Caplena feedback data directly from Microsoft 365 Copilot using the Model Context Protocol (MCP).

<Note>
  Connecting custom MCP servers requires a **Microsoft 365 Copilot** license.

  The free version of Microsoft Copilot does not support connecting custom MCP servers.
</Note>

## Before You Start

* You have a Caplena account.
* At least one project is set to **Live**.
* You have a Microsoft 365 Copilot license.

<Tip>
  Only projects set to **Live** are accessible through the Insight Agent.
</Tip>

## Step 1: Enable the Insight Agent in Caplena\\

<Frame>
  <img alt="Screenshot 2026 06 28 At 18 06 19 2" />
</Frame>

1. Go to **Settings → Integrations**.
2. Enable **Insight Agent (MCP)**.
3. Copy the generated **MCP URL**\
   (e.g., `https://api.caplena.com/v2/outbound-connectors/mcp`).

## Step 2: Open Microsoft 365 Copilot

<Frame>
  <img alt="Screenshot 2026 06 29 At 07 16 56" />
</Frame>

1. Go to [**https://copilot.microsoft.com**](https://copilot.microsoft.com).
2. Open **Settings** from your profile menu.
3. Go to **Apps** (or **Connected apps**, depending on your organization).
4. Select **Add app** or **Add MCP server**.

> The exact label varies by tenant, but both options open the MCP configurat

## Step 3: Connect Caplena

1. Paste the **MCP URL** copied from Caplena.
2. Microsoft Copilot will automatically discover:
   * OAuth issuer
   * Authorization endpoint
   * Token endpoint
   * Registration endpoint
   * Supported scopes
3. You will be redirected to Caplena.
4. Sign in and **Authorize** access.
5. You will return to Copilot with the connection active.

## Step 4: Start Asking Questions

You can now ask Microsoft 365 Copilot:

* List the Caplena projects I can access.
* Summarize the latest customer feedback.
* What are the most common themes in our survey?
* Compare the latest wave with the previous quarter.

Copilot will use Caplena’s MCP tools behind the scenes to fetch and analyze your data.


# Slack & Teams
Source: https://docs.caplena.com/integrations/outbound-accounts-microsoft-teams-slack-and-more

Bring Caplena's AI insights into Slack and Microsoft Teams — set up the bot, choose an access mode, and follow best practices.

With the Slack and Microsoft Teams integrations, your team can query your customer feedback data and get instant answers — right where they collaborate every day. No switching tabs, no manual searches — just ask questions and get instant summaries, trends, and answers.

<Note>
  The bot can only query projects that have been set to **Live**. [Learn how to set a project to Live →](/get-started/project-settings/setting-a-project-to-live)
</Note>

## Microsoft Teams

<Steps>
  <Step title="Enable the Integration">
    Before the bot can answer questions in Teams, set the project to **Live**. [Learn how →](/get-started/project-settings/setting-a-project-to-live)

    Go to your [global **Integrations** page](https://app.caplena.com/settings/integrations) and click **Connect** under the Microsoft Teams section.

    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 09 46" title="Screenshot 2026 05 27 At 16 09 46" />
    </Frame>

    Download the provided **Manifest file (ZIP)**.

    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 13 44" />
    </Frame>

    <Tip>
      If you don't see the Teams integration option, your role may not include permissions for integrations. Reach out to your Caplena admin — they can enable it with one click.
    </Tip>
  </Step>

  <Step title="Install the Caplena App in Microsoft Teams">
    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 22 12" title="Screenshot 2026 05 27 At 16 22 12" />
    </Frame>

    Open Teams → **Apps → Manage your Apps → Upload an App**.

    Depending on your permissions, click either **"Upload an app to your org's app catalog"** or **"Submit an app to your org"**, then follow the on-screen instructions to upload the ZIP file.

    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 26 24" />
    </Frame>
  </Step>

  <Step title="Link Your Teams Account to Caplena">
    Once the app is approved, go to **Apps** in Microsoft Teams and search for **Caplena**.

    * If you see **Add** → click it.
    * If you see **Open** → you're already good to go.
      <Frame>
        <img alt="Screenshot 2026 05 27 At 16 30 49" />
      </Frame>

    Navigate to **Chat → Caplena bot**. You should automatically receive a "Welcome" message with a link to connect your Teams installation to your Caplena user.

    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 33 36" />
    </Frame>

    If no message appears, simply type **"Hi"** — this triggers the connection flow.
  </Step>
</Steps>

## Slack

<Steps>
  <Step title="Connect Your Slack Workspace">
    Open Caplena and navigate to **Settings → Integrations**. Find the **Slack** integration and click **Connect**.

    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 35 45" />
    </Frame>

    Slack will open a permissions window where you can select your workspace and submit the installation request.

    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 37 11" />
    </Frame>

    <Note>
      If you see a "Request to install" button, it means your Slack admin must approve Caplena before you can use it. You can optionally leave a message explaining why you want to install the app.
    </Note>
  </Step>

  <Step title="Wait for Admin Approval (if required)">
    If your Slack workspace restricts app installations, your admin will need to review your request. Once approved, the Caplena app will appear in Slack under **Apps**. If apps are not restricted, Slack will install the app automatically after permission confirmation.
  </Step>

  <Step title="Link Your Slack User to Your Caplena Account">
    After the app is installed, open **Slack → Apps → Caplena**. You should automatically receive a welcome message prompting you to connect your account.

    <Frame>
      <img alt="Screenshot 2026 05 27 At 16 39 14" />
    </Frame>

    You're now ready to use the Insight Agent directly from Slack.
  </Step>

  <Step title="Enable Project Access in Caplena">
    Slack can only query insights from projects that have been explicitly approved. [Learn how to set a project to Live →](/get-started/project-settings/setting-a-project-to-live)
  </Step>
</Steps>

## Configuring Access Mode (Slack & Teams)

After connecting your workspace, you'll be guided to the Access Mode setting automatically. You can also return to it at any time from **Settings → Integrations** by clicking on the integration.

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 41 18" title="Screenshot 2026 05 27 At 16 41 18" />
</Frame>

**Global Access** *(default)* — All Slack or Teams users can query any project marked as `Live`. No individual Caplena account authentication is required.

**Per-user Access** — Users must sign in with their Caplena account the first time they interact with the Caplena bot. From then on, they can only query projects, reports, and views they have permission to access.

## Best Practices for Microsoft Teams & Slack

**Create a public #insights channel**

Set up a shared "Insights" channel where team members can query Caplena for findings. This helps everyone discover what the bot can do, learn from each other's use cases, discuss insights together, and keep knowledge accessible across the team.

<Frame>
  <img alt="Screenshot 2026 05 27 At 16 43 27" />
</Frame>

**How Caplena works in public channels**

In public channels, the bot will always reply **in a thread**. Each thread automatically links to **one specific project** on Caplena. Make sure to **@Caplena** in every new reply to trigger a response.

**How Caplena works in private channels**

In private channels, Caplena doesn't use threads. Click **"New Conversation"** whenever you want to ask about a different project, start fresh without previous context, or the conversation thread has become too long. A new conversation will also be created automatically every few days.


# Review platforms (Google Maps, App Stores, Tripadvisor, and more)
Source: https://docs.caplena.com/integrations/review-platforms

Import public reviews from major platforms to keep your feedback up to date automatically

Review platforms let you import **public customer reviews** into Caplena for analysis. You add reviews by providing **URLs or platform-specific IDs** (e.g., Google Place ID, Trustpilot domain, or app store link). Below is a list of platforms currently supported by Caplena's integration feature, including the required **input format** and **example links** for each.

<Tip>
  If you need to add several review sites or locations at once, you don't have to enter them individually. Prepare a list (e.g., in Excel, Google Sheets, or any text editor) and **copy & paste** the entire list directly into the **first input box**. Caplena will automatically detect each line as a separate entry. This greatly speeds up setup and reduces manual errors.
</Tip>

<iframe title="Loom video player" />

## Google Maps

Caplena accepts **two valid ways** to identify a Google Maps location:

### Option A: Google Place ID

You can find the Place ID using Google's official tool: [https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder](https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder)

Search for your location, click on it, and copy the Place ID shown below the name.

<iframe title="Loom video player" />

<Tip>
  Option A is the recommended approach. Place IDs are stable, unambiguous, and work reliably even when multiple businesses share a similar address.
</Tip>

### Option B: Fully Qualified Address

If you don't use a Place ID, you must enter a **complete, exact address**, including company/venue name, street and house number, postal code, city, and country.

**Example:** `Caplena AG, Stampfenbachstrasse 63, 8006 Zürich, Switzerland`

<Note>
  When you enter this exact address into Google Search, it **must show a full Google business profile** including pictures, phone number, opening hours, etc. If Google shows multiple results (like entrances or platforms), use the Place ID instead.
</Note>

If you need to scrape **many locations at once** (e.g., *"all McDonald's locations in the UK"*), reach out to us and we'll help set up the workflow.

<Note>
  **Row limit:** The limit you set applies **per location**, not across the entire import. If you set a limit of 100 and have 50 locations, you can import up to 5,000 reviews total.

  **Reviews without text:** Yes, Caplena imports star-rating-only reviews too, not just those with written text.
</Note>

## Trustpilot

Use this for **brand-level product or service reviews**.

<Warning>
  Due to provider restrictions, we can only scrape max **200 reviews** during the initial setup. If sync is enabled, new reviews will be added automatically over time.
</Warning>

**Input format:** `https://www.trustpilot.com/review/<domain>`

**Examples:**

* `https://www.trustpilot.com/review/cyberghostvpn.com`
* `https://www.trustpilot.com/review/www.smtp2go.com`

## Apple App Store

Use this for **iOS/iPadOS app reviews**.

<Warning>
  Due to provider restrictions, we can only scrape the **500 most recent reviews** during the initial setup. If sync is enabled, new reviews will be added automatically over time.
</Warning>

**Input format:**

* Default (US): `https://apps.apple.com/app/<name>/<identifier>`
* Other regions: `https://apps.apple.com/<region>/app/<name>/<identifier>`

<Note>
  **Supported regions:** ca, at, it, us, au, fr, ch, mx, es, de
</Note>

**Examples:**

* `https://apps.apple.com/app/bear/id1091189122`
* `https://apps.apple.com/de/app/fifa-soccer/id1094930513`

## Google Play Store

Supports reviews for **apps**, **movies**, and **books**.

**Input format:**

* Apps: `https://play.google.com/store/apps/details?id=<app-bundle>&hl=<lang>`
* Movies: `https://play.google.com/store/movies/details/<name>?id=<identifier>`
* Books: `https://play.google.com/store/books/details/<name>/?id=<identifier>`

**Languages supported:** `hl=de`, `hl=fr`, `hl=en`, `hl=it`, `hl=es`, etc.

**Examples:**

* `https://play.google.com/store/apps/details?id=org.coursera.android&hl=de`
* `https://play.google.com/store/apps/details?id=com.pluralsight`

## Amazon

<Warning>
  The **Amazon integration is temporarily unavailable** due to provider-side limitations. [Contact support](mailto:support@caplena.com) if you need Amazon reviews imported.
</Warning>

**Input formats (both accepted):**

* With product name: `https://www.amazon.<country>/<name>/dp/<ASIN>`
* Without name: `https://www.amazon.<country>/dp/<ASIN>`

**Supported Amazon stores:** US, UK, DE, FR, IT, ES, CA, JP, IN, AU, MX, BR, TR, AE, SA, NL, SG, PL, SE, EG, BE

**Examples:**

* `https://www.amazon.de/Colgate-Charcoal-Whitening-Zahnpasta-Zahnbürste/dp/B088VCM63D`
* `https://www.amazon.com/dp/B00WBJGUA2`

## G2

Use G2 to import **B2B software reviews**.

**Input format:** `https://www.g2.com/products/<product-name>/reviews`

**Example:** `https://www.g2.com/products/clickup/reviews`

## Capterra

Use Capterra for **software and SaaS product reviews**.

**Input format:** `https://www.capterra.com/p/<identifier>/<name>/`

**Example:** `https://www.capterra.com/p/177841/NetSuite/`

## Yelp

Use Yelp for **local business reviews** (restaurants, cafés, shops, services).

**Input format:** `https://www.yelp.com/biz/<business-name>`

**Examples:**

* `https://www.yelp.com/biz/tibits-basel`
* `https://www.yelp.com/biz/franchia-vegan-cafe-new-york`

## Tripadvisor

Use Tripadvisor for **tourism, attractions, and travel-related reviews**.

**Input format:** `https://www.tripadvisor.com/Attraction_Review-<location>/<place-id>-Reviews-<place-name>.html`

**Examples:**

* `https://www.tripadvisor.com/Attraction_Review-g294265-d324542-Reviews-Gardens_by_the_Bay-Singapore.html`
* `https://www.tripadvisor.com/Attraction_Review-g187497-d190146-Reviews-Basílica_de_la_Sagrada_Família-Barcelona_Catalonia.html`

## Trusted Shops

Use Trusted Shops for **product and service reviews**.

**Examples:**

* `https://www.trustedshops.com/buyerrating/info_X380804938575B96E13BA358219DC7DDC.html`
* `https://www.trustedshops.de/bewertung/mio-olio-de/extra`
* `https://www.trstd.com/de-ch/reviews/exlibris-ch`

<Note>
  Some reviews do not include a reviewer name.
</Note>

## Glassdoor

Use Glassdoor for **employee reviews**.

**Examples:**

* `https://www.glassdoor.com/Reviews/Award-Staffing-Reviews-E830922.htm`
* `https://www.glassdoor.com/Reviews/Roche-Basel-Reviews-EI_IE3480.0,5_IL.6,11_IM1691.htm`

## Indeed

Use Indeed for **employee reviews**.

**Examples:**

* `https://www.indeed.com/cmp/Award-Staffing/reviews`
* General pattern: `https://www.indeed.com/cmp/<business-name>`

<Note>
  Only **indeed.com (US)** is currently supported, not other locales.
</Note>

## Kununu

Use Kununu for **employee, applicant, and trainee reviews** of companies in the DACH region.

**Input format:** `https://www.kununu.com/<country>/<company>`

**Supported countries:** `de`, `at`, `ch`

**Examples:**

* `https://www.kununu.com/de/deutsche-post`
* `https://www.kununu.com/at/oebb`
* `https://www.kununu.com/ch/swisscom`

In addition to the overall rating and review text, Caplena imports Kununu's category ratings (work atmosphere, work–life balance, career development, salary, leadership, communication, and more), the reviewer's department, the review type (employee, applicant, or trainee), and any employer response.

<Note>
  Kununu is a Datashake-backed source, so it follows the standard **3-day sync cycle** for review platforms. New reviews posted between syncs are imported in the next batch.
</Note>


# Credits
Source: https://docs.caplena.com/settings-administration/credits

Understand how Caplena Credits work

Credits are Caplena's internal currency. You use them to pay for AI-powered analyses and features within the platform.

## How credits are used

All compute-heavy, AI-powered actions consume credits. The main actions are:

**Analyzing open-ends** - Each text entry (one cell in your uploaded file) costs 1 credit per selected text-to-analyze (TTA) column. You're only charged for the columns you selected to analyze.

**What's free?**

* Columns you don't select for analysis (ratings, demographics, segments)
* Empty cells
* Cells with defined dummy values (like "N/A" or "-")

**When are credits charged?** Credits are charged immediately upon upload, based on your selected TTA columns. You'll always see a preview of how many credits will be used before confirming.

## Free re-analysis runs

Every project includes a number of free AI topic re-assignments depending on your plan. You can:

* Re-run the entire analysis (full run), or
* Make smaller updates like adjusting or reassigning individual topics (partial run)

Partial runs only count proportionally toward your free quota.

**What happens after the free runs?** If you exceed your included AI Topic LLM runs, additional usage is charged at **0.2 Credits per processed row**:

> Example: If a topic run processes 1,000 rows, the overage cost is **200 credits** (1,000 × 0.2).

## LLM Smart Columns

Most plans come with a free quota of Smart Column runs. Once your free quota is used up, each computed row costs **0.1 credits**.

## What if I make a mistake?

* Every account includes built-in **demo projects** that don't consume credits
* For accidental uploads, Caplena is happy to reimburse credits (translation fees may be excluded)
* For testing, upload small sample datasets first

## Tracking your credit usage

Monitor your credit balance anytime on your [Account Page](https://app.caplena.com). Need help? Contact support.

### Purchasing more credits

* **Agency & Enterprise plans**: Go to **Settings → Billing** to purchase additional credits directly.

<Frame>
  <img alt="Screenshot 2026 07 08 At 13 44 50" />
</Frame>

* **Team plan**: Reach out to [sales@caplena.com](mailto:sales@caplena.com) to add credits to your plan.


# General Settings
Source: https://docs.caplena.com/settings-administration/general-settings/general-settings-overview

Manage your account, organization, and platform preferences

The **Settings** page lets you manage your account, personalize the platform experience, and control preferences. Here’s a breakdown of what you can configure:

<Check>
  To access settings, click your profile icon in the top-right corner of the screen.
</Check>

<Frame>
  <img alt="" />
</Frame>

### 1. **Account Settings**

Manage your personal profile and application preferences.

<Frame>
  <img alt="" />
</Frame>

**Basic Settings:**

* **First & Last Name**: Edit how your name appears in Caplena.
* **Email Address**: Used for notifications, password resets, and communication.

**General Information:**

* **Profile Created**: See when your account was created.
* **Last Login**: Monitor your recent login activity.

**Application Preferences:**

* **Language**: Choose between English and German.
* **Theme**: Switch between Light and Dark mode.
* **Timezone**: Control which timezone Caplena uses to display dates and times across the app (for example, in filters, exports, and report timelines).
  * Leave **Auto-update timezone** enabled to follow your browser's current timezone automatically. This is the default and works well if you travel or change locations.
  * Turn **Auto-update timezone** off to pick a specific IANA timezone (such as `Europe/Zurich` or `America/New_York`) from the searchable list. Use this when you want all dates to stay in a fixed timezone regardless of where you sign in from. Hover the toggle to see your currently active timezone.

### 2. Organization Settings

Configure company-wide preferences and billing details.

<Frame>
  <img alt="" />
</Frame>

**Billing Information:**

* Add or update your **Company Name**, **Address**, **City**, **ZIP**, and **Country**.
* This info appears on all invoices.
* Don’t forget to click **Save** after making changes.

**Organization Preferences:**

* **Dummy Values**: Define up to 3 placeholders (e.g., -99, NULL) to exclude from billing.
* **Tracking**: Opt out of usage tracking for support/debugging.

<Note>
   **Note:**

  > Dummy values only apply to newly uploaded data.
</Note>

<Warning>
  > Only Admins can define dummy values, and these settings apply across the entire organization.
</Warning>

You can also view your **Credit Usage** on this page, and export it if needed.

<Frame>
  <img alt="" />
</Frame>

### 3. **Theme Settings** 

Customize your Caplena branding.

<Frame>
  <img alt="" />
</Frame>

**Visual Identity:**

* **Default Logo**: Upload your company logo (.JPG, .PNG, or .WEBP).
* **Global Color**: Set your primary platform color.
* **Gradient Colors**: Choose styling for reports
* **Sentiment Colors**: Customize colors for sentiment views.

### 4. API Settings

Generate and manage API keys for external integrations.

<Frame>
  <img alt="" />
</Frame>

**To create an API key:**

<Steps>
  <Step>
    Go to **Settings → API** tab
  </Step>

  <Step>
    Click **Generate New API Key**
  </Step>

  <Step>
    Copy & store it securely — you won’t see it again
  </Step>
</Steps>

### 5. Security Settings

Keep your account secure with password management and 2FA.

<Frame>
  <img alt="" />
</Frame>

**Change Password:**

* Enter your current and new password → click **Save**

**Two-Factor Authentication (2FA):**

* Add protection via:
  * Authenticator App
  * Phone Number
  * Backup Codes
* You can set up to **3 active methods**

### 6. Integrations

Connect external platforms for smoother data import.

<Frame>
  <img alt="" />
</Frame>

View and manage all connected platforms under the **Integrations** tab.


# Limits & Warnings
Source: https://docs.caplena.com/settings-administration/limits-warnings

Platform limits for projects, topics, and users

We enforce some reasonable limits on the data to ensure smooth processing. Most limits can be relaxed if necessary — contact support if you hit a limit that prevents you from completing your analysis.

## Project limits

* 20,000 characters maximum per text value (fixed limit)
* 25 "Text to Analyze" columns allowed per project — [contact support](https://caplena.com/en/contact) if you need more
* 200 columns total for file uploads
* 50 MB maximum file size for uploads (no strict size limit for CSV files)
* 500 links maximum when importing via integrations

## Topic limits

* With the **new AI (LLM)**, up to **800 topics** are supported, including with sentiment enabled
* With the **legacy AI**, the maximum is **266 sentiment-enabled topics** (up to 800 without sentiment). Switching a project with more than 266 sentiment-enabled topics from the new AI back to the legacy model is not supported
* For semi-open columns this limit can be increased upon request
* Maximum **100 characters** for the topic label
* Maximum **100 characters** for the category label

## User limits

Your plan may limit the number of users your organization can have. Upgrade your subscription to increase the number of possible users.


# Object-Level Permissions
Source: https://docs.caplena.com/settings-administration/permissions-deep-dive/object-level-permissions

Give people access only to the projects or reports they need.

Sometimes you don't want a user to see everything — just one project, one report, or the ability to upload responses without touching anything else. Object-level permissions let you grant access **per project** or **per report**, without changing anyone's role.

<Frame>
  <img alt="Screenshot 2026 05 30 At 09 31 45" />
</Frame>

## Why object permissions exist

Real scenarios where they help:

* You hire a freelancer to code one survey — you don't want them inside the whole workspace
* A colleague is responsible for uploading new files — but shouldn't edit your topics
* Your manager needs visibility on one project — not all projects

Roles alone can't handle these cases. Object-level permissions fill that gap.

## Project permissions

<iframe title="Loom video player" />

| Permission               | Description                                                           |
| ------------------------ | --------------------------------------------------------------------- |
| `Projects View`          | View project details and data                                         |
| `Projects Edit`          | Modify project settings, TTA columns, and answers                     |
| `Projects Create`        | Create new projects                                                   |
| `Projects Download`      | Download project data (answers, codes)                                |
| `Projects Append`        | Add new rows/data to existing projects                                |
| `Projects Inherit`       | Use project codebooks as templates for new projects                   |
| `Projects Permissions`   | Manage who has access to projects                                     |
| `View sensitive columns` | See and edit columns marked as sensitive, and include them in exports |

<Tip>
  Use **View sensitive columns** to hide PII or confidential fields from most collaborators. Auxiliary columns flagged as sensitive in the [Data Tab](/data-project-management/data-tab-sources/data-tab-overview) only appear for users with this permission — everyone else keeps `Projects View` access without seeing the protected fields.
</Tip>

## Report permissions

| Permission       | Description                        |
| ---------------- | ---------------------------------- |
| `Reports View`   | View reports                       |
| `Reports Edit`   | Modify report settings and content |
| `Reports Create` | Create new reports                 |

## Integration permissions

| Permission            | Description                              |
| --------------------- | ---------------------------------------- |
| `Integrations Use`    | Use existing integrations to import data |
| `Integrations Manage` | Create, modify, and delete integrations  |

## Administrative permissions

| Permission                | Description                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `Team Management`         | Manage team members (invite, remove, change roles)                                     |
| `Subscription Management` | Manage billing and subscription settings                                               |
| `Credit Usage`            | Perform operations that consume credits (uploading data, AI coding, LLM smart columns) |

## Permission inheritance

Caplena's sharing logic follows a simple hierarchy.

**Project access → Report access** - If a user can access a project, they automatically gain access to all reports in that project, all views in those reports, and any related exports.

**Report access → Report views -** If a user can view a report, they automatically see all its views. However, report access does not grant project access or expose raw data — report users cannot inspect answers unless explicitly granted project permissions.

This lets you safely share reports without exposing sensitive underlying data.

## Ownership rules

**Object owner** — the person who created the project or report always has full control and cannot have permissions removed (only ownership transferred).

**Root organization user** — the master account of your company always sees everything and cannot be restricted or removed.


# Understanding Role-Based Permissions
Source: https://docs.caplena.com/settings-administration/permissions-deep-dive/understanding-role-based-permissions

This guide walks you through how to assign and update roles, and what each role allows.

## Managing User Roles in Caplena

Assigning the right role is key to giving team members the access they need. In Caplena, roles define what a user can do across all projects and reports.

## How to Change a User’s Role

Changing roles is simple and takes less than a minute:

<Steps>
  <Step>
    Go to your **Account page**
  </Step>

  <Step>
    Open the **Team** section
  </Step>

  <Step>
    Find the user whose role you want to change
  </Step>

  <Step>
    Use the dropdown menu to select a new role
  </Step>
</Steps>

<iframe title="Loom video player" />

## Role Overview

Here’s a breakdown of the six user roles available:

### External Topic Assignment

<Tip>
  *Best for external partners or freelancers who should only work on their own content.*
</Tip>

No upload capability; No access to projects or dashboards of others by default.

### Administrator

<Tip>
  *Best for power users who manage subscriptions, teams, and integrations across the platform.*
</Tip>

Access to the projects, questions and reports of all users; Team and subscription management permissions.

### Full Data Access

<Tip>
  *Best for senior team members who need access to all projects and reports without admin responsibilities.*
</Tip>

Upload capability; Access to projects & dashboards of all team members.

### Project Manager

<Tip>
  *Best for team leads who manage their own projects but don’t require access to others’ work.*
</Tip>

Upload capability; Only full access to projects created by oneself, but access to all topic collections and fine-tuned AIs from all team members.

### Internal Analyst

<Tip>
  *Best for team members working across projects, without needing downloads or reports.*
</Tip>

No upload capability; Permission to edit and access projects of all team members, but no permission to download projects and no access to reports of others.

### Analyst

<Tip>
  *Best for stakeholders or junior team members who only need to view and explore results.*
</Tip>

Permission to view and visualize projects of all team members, but no permission to edit or download any projects.

## Credit Usage Permission

The **Credit Usage** permission determines whether a user can perform operations that consume credits in Caplena.

### Operations requiring credits

* AI-assisted coding
* Topic generation
* AI topic assignment
* Other machine learning operations

### Roles with Credit Usage permission

| Role                      | Credit Usage |
| :------------------------ | :----------- |
| Administrator             | ✓            |
| Full Data Access          | ✓            |
| Project Manager           | ✓            |
| Internal Analyst          | ✗            |
| External Topic Assignment | ✗            |
| Analyst                   | ✗            |

### What happens without Credit Usage permission

If a user without **Credit Usage** permission attempts an operation that consumes credits, they will see an error message indicating that they need to contact their organization administrator to enable the permission.


# Third-Party Services
Source: https://docs.caplena.com/settings-administration/third-party-services

An overview of the third-party services Caplena uses

Caplena uses selected third-party services to deliver a smooth and secure experience — from translation and analytics to infrastructure and support.

We take privacy and compliance seriously. As part of our GDPR commitment, and to meet the standards of privacy-conscious clients such as Swiss banks and global telcos, we carefully vet each integration and minimize the data shared.

Some services are essential for running our platform (e.g., cloud infrastructure), while others are optional, like analytics or translation services.

<Note>
  The only subprocessor that potentially has full access to the data you upload is **Google Cloud**. With most other services, we only share usage information, which may include your name and email.
</Note>

## Full List of Subprocessors

For the most accurate and up-to-date details, including data access levels, processing locations, and legal addresses, please visit our official subprocessor list:

[View Subprocessors on the Caplena Trust Center →](https://trust.caplena.com/subprocessors)


# Introduction: Permission Types
Source: https://docs.caplena.com/settings-administration/understanding-access/introduction-permission-types

Learn how Caplena’s role-based and project-specific permissions work.

When many people collaborate in Caplena, it’s important that everyone has exactly the access they need. Caplena makes this easy through **roles** and **object-level permissions**. Below is the simplest possible explanation of how everything works.

## The Two Things That Control Access:

### 1) **Roles** → Your default access everywhere

A role defines what someone can do across the whole Caplena workspace.

Think of a *role* as your “driving license type”, it gives broad permissions. 

<Frame>
  <img alt="Screenshot 2026 05 30 At 09 17 13" />
</Frame>

**What roles decide:**

* Can the user upload projects?
* Edit topics and answers?
* Create reports?
* Spend credits on AI operations?
* Manage the team or subscription?

**Examples:**

* Someone with **Admin** can access everything.
* Someone with **Reporting Only** can access *only* reports that are explicitly shared.

Roles = your baseline abilities across the whole organization.

<Note>
  You can find more information on roles [here](/settings-administration/permissions-deep-dive/understanding-role-based-permissions).
</Note>

### 2) **Object-Level Permissions** → Extra access to a specific project or report

These permissions are added individually to:

* one project
* one report

<Frame>
  <img alt="Screenshot 2026 05 30 At 09 18 09" />
</Frame>

**Example:**

A freelancer has a very restricted role (External Coder), but you give them access to **1 specific project**. They will see **only that project**, nothing else.

Object permissions can only ADD access they never remove what a role already provides.

<Note>
  You can find more information on project permissions [here.](/settings-administration/permissions-deep-dive/object-level-permissions)
</Note>

## **How the Two Types Work Together**

Caplena evaluates access in this order:

1. **Role** → global abilities
2. **Object-Level Permissions** → extra access
3. Permissions cannot restrict the role
4. Access to a project automatically includes access to the reports inside it

This combined model gives you:

* simplicity for admins
* flexibility for collaboration
* safety when sharing reports externally


# User Types in Caplena: Core vs. Reporting-Only
Source: https://docs.caplena.com/settings-administration/understanding-access/user-types-in-caplena-core-vs.-reporting-only

Understand the difference between Core and Reporting-Only users.

Caplena supports two user types to suit different collaboration needs.

## Core Users

Core users have full platform access depending on their assigned **role**. Use this for team members who are actively working on data, projects, and analysis.

Core users can:

* View, create, and edit projects and reports
* Tag, filter, and analyze data
* Use and manage integrations (e.g., Qualtrics)
* Set up alerts, manage teams, and configure permissions

<Tip>
  Assign Core roles (e.g., Analyst, Project Manager, Administrator) to anyone who needs hands-on access in Caplena.
</Tip>

## Reporting-Only Users

Reporting-only users have **view-only access** to reports shared with them. Ideal for external stakeholders or internal teams who just need visibility into results.

Reporting-only users cannot:

* Access or edit any projects
* Create or modify reports
* Interact with alerts, integrations, or reports beyond view access

<Tip>
  Best for clients, executives, or non-technical users who only need to monitor live reports.
</Tip>

## How to add users

<iframe title="Loom video player" />

<Steps>
  <Step title="Go to Team">
    Go to **Account → Team**.
  </Step>

  <Step title="Click Invite">
    Click the **Invite** button in the top-right corner.
  </Step>

  <Step title="Choose invite type">
    Choose between **Single user** or **Multiple Reporting-Only users**.
  </Step>

  <Step title="Enter details">
    Enter the user's email address and assign a role (for Core users).
  </Step>

  <Step title="Confirm">
    Click **Invite** or **Bulk Invite** to confirm.
  </Step>
</Steps>


# How to Use Bulk Assign
Source: https://docs.caplena.com/topic-assignment/advanced-functionality/how-to-use-bulk-assign

Easily assign topics and update review statuses across multiple rows at once

When working on a project in Caplena, you may need to assign or adjust topics across multiple rows at once. Instead of handling each response individually, you can use the **Bulk Assign** feature to speed up your workflow.

## What is Bulk Assign?

Bulk Assign allows you to select several rows of responses and apply the same topic(s) to them in one action. You can also control whether existing topics are kept or replaced, and whether rows should be marked as reviewed.

This feature is especially useful when you notice a group of similar responses and want to categorize them consistently without repeating the same steps multiple times.

## How to Bulk Assign Topics

<iframe title="Loom video player" />

1. **Select the rows** you want to modify (tick the boxes on the left side of the response list).
2. Click on **Bulk Assign** in the action bar.
3. In the Bulk Assign panel:
   * **Add topics:** Choose one or more topics from your topic list.
   * **Topic assign mode:**
     * *Add* → Keeps existing topics and adds the new ones.
     * *Replace* → Replaces all current topics with the ones you've selected.
   * **Row review status:**
     * *Keep current* → Leaves review status unchanged.
     * *Reviewed* → Marks all selected rows as reviewed.
     * *Unreviewed* → Marks all selected rows as unreviewed.
4. Click **Apply** to confirm your changes.

## Best Practices

* **Use "Add" mode** when responses already have relevant topics you don't want to overwrite.
* **Use "Replace" mode** if you want to completely recategorize rows.
* **Mark as reviewed** only when you're confident the assignment is final — this helps keep your workflow tidy and your AI score accurate.
* **Filter first:** Applying filters (e.g. by Wave, Source, or existing Topic) before using Bulk Assign ensures you're only updating the right set of rows.

## Sentiment and Reviewed/Unreviewed Rows

<Warning>
  **Note:** Sentiment cannot be disabled when rows containing a topic have *mixed review statuses*.
</Warning>

* All rows with that topic must be either **reviewed** or **unreviewed**.
* Use **Bulk Assign → Row review status** to align them (e.g. set all to unreviewed) and then try disabling sentiment again.

This ensures sentiment is applied consistently across your dataset.

<iframe title="Loom video player" />


# Topic Assignment History
Source: https://docs.caplena.com/topic-assignment/advanced-functionality/topic-assignment-history

Easily revert topic assignments or structure to any point from the past 60 days

Caplena now gives you the ability to jump back to any previous state of your topic assignment and topic collection, perfect for undoing changes or comparing versions after running a new AI analysis.

## What is Topic Assignment History?

It's a feature that lets you restore your project to any point in time from the past **60 days**. You can:

* Revert accidental changes
* Compare results before/after an AI run
* Restore a specific version of your topic collection

## Where to Find It

Go to your project's **Topic Assignment** page → click on **History** (top-right corner).

<Frame>
  <img alt="Clean Shot 2025 08 31 At 13 04 23 (1)" />
</Frame>

You'll see a timeline of all major changes:

* Topics created, renamed, or deleted
* AI reassignments
* Manual edits
* Edits made by the [Topic Critique Agent](/insight-and-reports/insight-agent/topic-critique-agent)

<Note>
  Topics that were edited by the Topic Critique Agent are marked with a **sparkles badge** in the version history view, so you can tell agent-driven changes apart from your own manual edits and standard AI reassignments. Topics changed by any other source use the standard "changed" badge.
</Note>

## Jump to a Version

You have two ways to go back in time:

**From the Event Log**: Select any listed event and choose:

* *Just before* the event, or
* *Just after* the event

<Frame>
  <img alt="Screenshot 2026 05 30 At 10 37 28" />
</Frame>

**By Manual Time Entry**: Enter a custom date & time, down to the second, and restore that exact version.

<Frame>
  <img alt="Screenshot 2026 05 30 At 10 38 41" />
</Frame>

## Preview Before You Restore

Before confirming, you'll see a preview:

* What topics existed then vs. now
* How assignments looked at that point
* Any renames or deletions highlighted

<Frame>
  <img alt="Screenshot 2026 05 30 At 10 40 48" />
</Frame>

## Things to Keep in Mind

<Tip>
  * The history log is kept for **60 days**.
  * Restoring a previous version does **not** delete any current data — it just rolls back the topic structure.
  * You can use this feature as "version control" for your topic collection.
</Tip>


# AI Score & Quality Measures (Legacy AI)
Source: https://docs.caplena.com/topic-assignment/legacy-ai/ai-score-and-quality-measures

When to stop AI training and ensure high-quality results.

Training your AI model improves the accuracy of topic assignments, but at some point, it's time to move forward. This article explains how to know when your model is ready, how to interpret the **AI Score**, and what steps to take if your results still need improvement.

## When Should I Stop AI Training?

You can stop training your model when you're confident in the quality of the results. We recommend using a combination of:

* **Manual Review** — Check a sample of your responses. If the topic assignments make sense and align with human judgment, that's a strong sign the model is ready.
* **AI Score** — This score reflects how confidently the AI assigns topics. Use it as a benchmark for overall performance.

<Tip>
  Review each topic 2–3 times to get a solid understanding of the model's performance.
</Tip>

## What Is the AI Score?

<Frame>
  <img alt="AI Score" />
</Frame>

The **AI Score** shows how confident the model is in its own topic assignments. While the theoretical maximum is 100, this is never achieved in practice.

Here's how to interpret it:

| Scenario                               | Typical AI Score |
| :------------------------------------- | :--------------- |
| A single person assigning topics twice | \~90             |
| Two different people assigning topics  | 70–80            |
| Human-like AI performance              | \~70             |

## How to Improve the AI Score

If your score is lower than expected, or if the topic assignments seem off, try the following strategies:

### 1. Simplify Your Topics

Large, overlapping topic sets can confuse the AI. Consider combining similar topics or removing less relevant ones.

<Note>
  **Example:** Combine "Late Delivery" and "Shipping Delays" into **"Delivery Issues".**
</Note>

### 2. Use Clear, Descriptive Labels

The AI learns from your topic names. Labels should be specific and easily understandable.

<Note>
  **Avoid:** "Misc.", "Other", "X1"

  **Use:** "Website Usability", "Suggestions for Improvement"
</Note>

### 3. Review More Data

The more examples the AI has to learn from, the better it performs. If you have historical data with topics already assigned but not yet uploaded to Caplena, contact [support](mailto:support@caplena.com) to help you ingest it into your account.

### 4. Review Low-Confidence Topics

In the chart and table below, you'll find topics where the AI has lower confidence in its assignments — these appear below the red line. These are the best candidates for additional review and refinement.

<Frame>
  <img alt="Low-confidence topics chart" />
</Frame>

## Why Are Some Topics Missing a Score?

If a topic is only assigned to a few responses, the AI might not have enough data to calculate a score. In rare cases, the AI may also struggle with topics that have unclear or overly abstract labels.

<Frame>
  <img alt="Topics missing a score" />
</Frame>


# AI Training (Legacy AI)
Source: https://docs.caplena.com/topic-assignment/legacy-ai/ai-training

Teach your AI to think like you.

When you first upload your data to Caplena, the AI takes a smart first stab at organizing it. It identifies common themes, assigns topics, and gives structure to your open-ended feedback.

**AI training** is where you come in — it's your chance to teach the AI to think like your team, understand your brand's voice, and reflect what actually matters to your business. Think of it as a collaboration: the AI does the heavy lifting, and you guide it with your unique context.

## Where Does AI Training Happen?

You'll train the AI directly inside your active project. Here's how to get started:

<Steps>
  <Step title="Open your project">
    Navigate to your project in Caplena.
  </Step>

  <Step title="Click Topics">
    Select **Topics** in the left-hand menu.
  </Step>

  <Step title="Review responses">
    Go through individual responses and confirm or correct the AI's topic assignments.
  </Step>
</Steps>

<Frame>
  <img alt="AI training view" />
</Frame>

## Reviewing a Row

Reviewing means clicking into a specific row and either confirming or adjusting the topics the AI applied.

### How to Review

You can either:

* Click on a row to open the detailed view
* Or turn on **Focus Mode** (more on this below)

Once in the row, you can:

* Add or remove topics
* Adjust sentiment (if needed)
* Mark the row as reviewed ✅

<Note>
  Reviewed rows become learning examples for the AI — the more you review, the better it gets.
</Note>

<Frame>
  <iframe />
</Frame>

## Focus Mode: Smart Reviewing

Focus Mode brings the most uncertain rows to the front — the ones where the AI is unsure and your input matters most.

<Frame>
  <img alt="Focus Mode in action" />
</Frame>

### What Focus Mode Does

* Sorts rows by lowest confidence
* Hides already-reviewed data
* Removes visual clutter so you can concentrate

To activate: click the **Focus Mode** icon in the top right corner of the fine-tuning view.

<Note>
  **Example:** If you're training your AI on a telecom survey, Focus Mode might prioritize ambiguous responses like "Reception could be better" — prompting you to clarify whether this refers to network coverage or device quality.
</Note>

## Finalize and Refine Your Topic Collection

As part of the review process, it's a good time to put the finishing touches on your topic structure. You can:

* **Rename** topics to be clearer or more consistent (e.g., "App Usability" → "Mobile Experience")
* **Merge** redundant topics like "Delivery" and "Shipping"
* **Add** entirely new categories if needed

<Frame>
  <iframe />
</Frame>

<Note>
  Every change in the Topic Editor prompts the AI to retrain — your topic structure directly influences how well the model performs.
</Note>


# How AI Assigns Topics (Legacy AI)
Source: https://docs.caplena.com/topic-assignment/legacy-ai/how-ai-assigns-topics

Understand how AI labeling works, how it's trained, and how your data is handled.

Open-ended responses often contain the richest insights, but analyzing them at scale is rarely straightforward. To help with this, Caplena's AI automatically tags each response with the most relevant topics, turning free text into structured data you can actually work with.

Below, we'll walk through how the AI works, how it's trained, and how your data is handled.

## How the AI Works

Caplena's AI doesn't rely on basic keyword matching. It understands the meaning behind the words, including synonyms, sentiment, and even negations.

<Frame>
  <img alt="How the AI assigns topics" />
</Frame>

For example:

* It knows that **"overpriced"** and **"too expensive"** mean the same thing — no need to manually define synonyms.
* It detects sentiment automatically. For sentiment-enabled topics, only one sentiment (positive, negative, or neutral) will be applied per response. So a comment won't be tagged as both "Service (Positive)" and "Service (Negative)."

<Note>
  Want to go deeper? Download our whitepaper [here](https://storage.googleapis.com/caplena-public/Whitepaper_Unveiling_the_tech_behind_the_worlds_most_accurate_customer_feedback_analysis_ai.pdf).
</Note>

## AI Training Process

Caplena's AI gets smarter in three stages:

### Pretraining

The AI is first trained on a massive set of unstructured text — essentially a large portion of the internet. This gives it broad language understanding, including synonyms, antonyms, negations, and more.

### Training on Caplena's Data

Next, we train it on millions of real, hand-reviewed responses across many industries. This helps the AI develop a deep understanding of how real people express themselves in feedback.

### Fine-Tuning (Optional)

Finally, you can fine-tune the AI on your own data by reviewing and correcting a small sample of responses. This step personalizes the AI to your company's tone, terminology, and unique context.

<Tip>
  Use [Focus Mode](/topic-assignment/legacy-ai/ai-training) to review the rows where the AI is least confident. That's where your feedback has the biggest impact.
</Tip>

## Model Architecture

This is part of our secret sauce and can't be shared in detail, but here's what we can say:

* We use a **heavily modified Transformer architecture**, similar to the models behind tools like ChatGPT.
* Technically, the AI performs **multi-label classification** — meaning each comment can get zero, one, or many topics assigned.

<Note>
  Want to dig into the tech? [Here](https://jalammar.github.io/illustrated-transformer/) you can find a great intro to Transformers.
</Note>

## Is My Data Shared?

No. Your data is never shared with other users. Here's how it works:

* The AI learns general patterns from tagged data — e.g., that "The package arrived late" maps to "Slow delivery."
* These learnings are stored as mathematical weights, not as readable text.
* No identifiable or original text is ever exposed, not even internally.

Only the **results** of topic assignments are visible to you, and the model is **never public.**


# Managing AI Updates (Legacy AI)
Source: https://docs.caplena.com/topic-assignment/legacy-ai/managing-ai-updates

Control your model's behavior to balance consistency with continuous learning.

Caplena gives you control over how your AI model evolves. You can now **pause AI learning** while still allowing automatic topic assignment when new data is uploaded, ensuring consistent results without unexpected changes.

## What Are AI Updates?

**AI Updates** refer to Caplena's ability to continuously improve your model based on manual reviews and topic corrections.

By turning AI Updates **off**, you can **freeze the model**, keeping topic assignments stable as new data is analyzed.

## How to Enable or Disable AI Updates

To control AI learning in your project:

* Go to the **Topics** view in your project
* Click the **three-dot menu** (⋮) in the top-right corner
* In the **Settings** pop-up, find the **"AI Updates"** toggle
* **Turn OFF** to pause AI learning
* **Turn ON** to allow the AI to learn from manual reviews again

<Frame>
  <img alt="CleanShot 2025-07-28 at 13.31.24" />
</Frame>

## What Happens When AI Updates Are Disabled?

| Feature                          | Behavior                                                    |
| :------------------------------- | :---------------------------------------------------------- |
| **Learning from manual edits**   | ❌ Disabled — no new training based on your edits            |
| **Topic assignment on new data** | ✔️ Still active — existing model continues assigning topics |
| **AI Scores**                    | ✔️ Frozen — scores remain stable and unchanged              |

## When Should You Disable AI Updates?

Disabling AI Updates is ideal when:

* You want **consistent scoring** across reports or time periods
* You've finished training your model and don't want further changes
* You're preparing deliverables where score stability is important


# How the LLM Topic Assignment Works
Source: https://docs.caplena.com/topic-assignment/new-ai/how-the-new-llm-topic-assignment-works

Understand how AI assigns topics and refine results by improving topic descriptions.

Caplena’s new AI brings major improvements in speed, accuracy, and flexibility. This guide explains how it works, how to prepare before running your first analysis, best practices to get the most out of it, and when to re-run updates.

<iframe title="Loom video player" />

## Key Improvements

* **State-of-the-art AI model:** Leverages project context (titles, descriptions, columns, question info) plus review content for highly accurate assignments.
* **Less manual input required:** High-quality results often after the first run.
* **Topic descriptions matter:** AI relies heavily on them, giving you more control.
* **Longer texts supported:** Now handles texts up to 20,000 characters (previous limit: 1,000).
* **Multilingual support:** Works across 100+ languages natively.

## Best Practices (Before Running the Analysis)

Apply these steps **before your first AI run** to achieve the best results:

### Project & Question Context

In addition to **text + reviewed texts**, the AI now uses the following fields during training:

* **Project Title**
* **Project Description**

<Frame>
  <img alt="Screenshot 2026 05 20 At 18 18 45" />
</Frame>

* **Question Name**
* **Question Description**

<Frame>
  <img alt="Screenshot 2026 05 20 At 18 20 05" />
</Frame>

### Best Practices

* **Use descriptive titles instead of generic ones if available**\
  Example: Use *“Feedback on Delivery Process”* instead of *“Q3”*.
* **Add contextual info to descriptions:**
  * Lesser-known companies or terms\
    Example: *“XXX is a subsidiary of YYY that focuses on manufacturing.”*
  * Technical or company-specific terms
    * Define acronyms or jargon that might not be widely known.
    * Generally, the AI will be able to understand technical terms even if they are only known to specialists in the field. However, if the terms are uncommon acronyms or are company-specific, it may be useful to define them.
* **Sentiment guidance**\
  Example: If responses are from complaints, say so, this helps the AI interpret tone or sarcasm better.

<Tip>
  Doing this upfront ensures that the AI will generate clearer and more accurate **topic descriptions** when you start the analysis.
</Tip>

## Best Practices (When Starting Analysis)

Once you click **Start Analysis,**  the system generates the first set of topic descriptions:

Topic descriptions are now a major input for the AI.

* **Review auto-generated descriptions** → check if they make sense.
* **Refine unclear or ambiguous topics**:
* **Reorganize or merge topics** before confirming the first run.
* If you want a fresh AI-written description: delete the old one → it will regenerate on the next run.

<img alt="Screenshot 2026 05 20 At 18 22 27" title="Screenshot 2026 05 20 At 18 22 27" />

### Notes on Behavior

* Descriptions apply to the next training round (not instantly)
* Changing a topic label does not auto-update the description. Usually, this is not an issue if it is still referring to the same topic, but if you change it to something very different, you will have an outdated and irrelevant description.

#### **How the AI prioritises topic assignment**

When assigning topics, the AI uses the following information in order of priority:

1. **Topic label + category** - this has the highest influence. The AI reads both together, so the category name shapes how strictly the topic is applied.
2. **Topic description** - use this to clarify edge cases, broaden or narrow scope, or add examples. It can partially compensate for a restrictive category name.
3. **Reviewed rows**  - confirmed examples help the AI learn, but have the lowest priority of the three.

**Practical implications**

* Choose category names carefully. A category like "COMPETITOR" signals competitive context and will filter assignments accordingly. If you want broader coverage, rename it to something neutral like "BRAND".
* Descriptions are powerful but work within the frame set by the label and category, they can't fully override it.
* If topics are being missed or over-filtered, check the category name first before adjusting the description.

<Tip>
  **Example:** A topic "Nike" under category "COMPETITOR" will be assigned for *"Nike is so much better than Adidas"* but not for *"I love my Nike shoes",* because the category signals the AI to look for competitive framing, not general brand mentions.
</Tip>

## Workflow Overview

### 1. Enable and Start Analysis

* Click **Enable AI**.
* Review the generated topic descriptions immediately.

<Frame>
  <img alt="Enable AI and start" />
</Frame>

### 2. Refine Topics & Descriptions

* Merge or reorganize topics.
* Adjust descriptions to better match your intent.

### 3. Run the AI

* Hit **Done** → triggers the first run.
* Duration: seconds to minutes depending on dataset size.
* Expect **human-level accuracy** even without manual reviews.

### 4. Review Results

* Check the overall **score** and the % of rows without topics.
* Make adjustments: merge similar topics, refine descriptions, add missing ones.

<iframe title="Loom video player" />

### 5. Trigger Updates: Full vs. Partial Runs

Caplena gives you full control over when and how AI updates are triggered, they are no longer automatic.

<Frame>
  <img alt="Screenshot 2026 05 20 At 18 30 35" />
</Frame>

You can choose between two types of updates. Caplena automatically detects whether a **partial** or **full AI update** is needed based on your changes, and suggests the best option. In **95% of cases**, the suggested type is the correct one. You’ll still have full control and can **override the suggestion** if needed.

#### Partial AI Update (New!)

Caplena now supports **partial updates**, saving time and AI usage when only small changes are made.

**Use this when you:**

* Add a new topic
* Edit the description of an existing topic

**What happens:**

* Only the affected rows are reprocessed
* Faster and more efficient than full re-runs

<img alt="Screenshot 2026 05 20 At 19 02 09" title="Screenshot 2026 05 20 At 19 02 09" />

<Note>
  In the screenshot above, only 2 topics were changed. We recommend a **partial update** of just those topics, costing only a fraction of a full update.
</Note>

#### Full AI Update

A full update is recommended when you’ve made **multiple or broader changes**, such as:

* Adding or editing many topics at once
* Significantly reworking the topic structure or descriptions

**Why run a full update?**

* Ensures consistency across the entire dataset
* Often more cost-efficient than running many partial updates separately

<img alt="Screenshot 2026 05 20 At 19 07 58" />

<Note>
  * The number of included AI runs may vary depending on your Caplena plan.
  * The extra AI run cost is 50% of the original import. For example, if the first import of a column used 1,000 credits, then each additional run would cost 500 credits.
</Note>

## Manual Reviewing Tips

It is still possible and useful to manually review rows! However, we expect that the new AI should have a solid enough baseline to reduce the amount of manual reviewing required.

### Where to Focus Your Time:

* Update the descriptions and make topics clearer instead of reviewing many individual examples
* If reviewing is necessary or you prefer it over editing descriptions: 
  * Skip easy/obvious rows, the AI got it right
  * Focus on borderline or complex examples

> Label fewer rows, but make them count.\
> (The AI now benefits more from quality over quantity.)

## Supported languages:

The new AI supports more languages natively

* Afrikaans (af)
* Albanian (sq)
* Amharic (am)
* Arabic (ar)
* Armenian (hy)
* Assamese (as)
* Azerbaijani (az)
* Basque (eu)
* Belarusian (be)
* Bengali (bn)
* Bosnian (bs)
* Bulgarian (bg)
* Catalan (ca)
* Cebuano (ceb)
* Chinese (Simplified and Traditional) (zh)
* Corsican (co)
* Croatian (hr)
* Czech (cs)
* Danish (da)
* Dhivehi (dv)
* Dutch (nl)
* English (en)
* Esperanto (eo)
* Estonian (et)
* Filipino (Tagalog) (fil)
* Finnish (fi)
* French (fr)
* Frisian (fy)
* Galician (gl)
* Georgian (ka)
* German (de)
* Greek (el)
* Gujarati (gu)
* Haitian Creole (ht)
* Hausa (ha)
* Hawaiian (haw)
* Hebrew (iw)
* Hindi (hi)
* Hmong (hmn)
* Hungarian (hu)
* Icelandic (is)
* Igbo (ig)
* Indonesian (id)
* Irish (ga)
* Italian (it)
* Japanese (ja)
* Javanese (jv)
* Kannada (kn)
* Kazakh (kk)
* Khmer (km)
* Korean (ko)
* Krio (kri)
* Kurdish (ku)
* Kyrgyz (ky)
* Lao (lo)
* Latin (la)
* Latvian (lv)
* Lithuanian (lt)
* Luxembourgish (lb)
* Macedonian (mk)
* Malagasy (mg)
* Malay (ms)
* Malayalam (ml)
* Maltese (mt)
* Maori (mi)
* Marathi (mr)
* Meiteilon (Manipuri) (mni-Mtei)
* Mongolian (mn)
* Myanmar (Burmese) (my)
* Nepali (ne)
* Norwegian (no)
* Nyanja (Chichewa) (ny)
* Odia (Oriya) (or)
* Pashto (ps)
* Persian (fa)
* Polish (pl)
* Portuguese (pt)
* Punjabi (pa)
* Romanian (ro)
* Russian (ru)
* Samoan (sm)
* Scots Gaelic (gd)
* Serbian (sr)
* Sesotho (st)
* Shona (sn)
* Sindhi (sd)
* Sinhala (Sinhalese) (si)
* Slovak (sk)
* Slovenian (sl)
* Somali (so)
* Spanish (es)
* Sundanese (su)
* Swahili (sw)
* Swedish (sv)
* Tajik (tg)
* Tamil (ta)
* Telugu (te)
* Thai (th)
* Turkish (tr)
* Ukrainian (uk)
* Urdu (ur)
* Uyghur (ug)
* Uzbek (uz)
* Vietnamese (vi)
* Welsh (cy)
* Xhosa (xh)
* Yiddish (yi)
* Yoruba (yo)
* Zulu (zu)


# How to Ensure High-Quality Results with the LLM
Source: https://docs.caplena.com/topic-assignment/new-ai/how-to-ensure-high-quality-results-with-the-new-llm

Learn how to guide Caplena's LLM-based AI for precise topic assignments in just a few runs.

Caplena's **LLM-based AI** assigns topics faster, smarter, and with human-level accuracy. You no longer need endless manual reviews — what matters most now is how you **set up and refine your topics and descriptions**.

Here are our best tips to make sure your AI delivers excellent, trustworthy results.

## Tip 1: Understand how the LLM-based AI works

* The AI uses all available **project context** — project name, description, column titles, and of course, your text data.
* When you click **Done** in the Topic Assistant, the AI automatically:
  1. Generates **topic descriptions** for each topic.
  2. Assigns topics to your data using those descriptions.
  3. Calculates an **AI Score** to indicate overall quality.

<img alt="AI Score overview" />

<Frame />

### Understanding Topic Assignment Consistency

The AI score reflects both the **quality** and **stability** of topic assignments. To produce reliable results, the model draws on your project background, examples, and topic descriptions, and runs the assignment multiple times — comparing results to arrive at the most consistent answer.

A **high score** means topics are well-differentiated, resulting in clear and stable decisions. A **lower score** suggests the boundaries between some topics may not be entirely clear-cut and could benefit from more distinct descriptions.

## Tip 2: Focus on Topics and their Descriptions

### Review & Adjust Your Topics

* Check for **duplicates or overlaps** — merge similar topics like *"Late Delivery"* and *"Shipping Delays"* into *"Delivery Issues".*
* Remove irrelevant or overly specific topics that don't add value.
* Add **missing topics** if you notice recurring ideas not yet covered.

<Frame>
  <img alt="Review and adjust topics in the editor" />
</Frame>

<Tip>
  Do all your topic cleanup **before** finalizing the topic collection. You'll save a rerun and improve the AI's learning context dramatically.
</Tip>

### Perfect Your Topic Descriptions

Topic descriptions are the **core input for the LLM-based AI**. The model reads these to understand what each topic means and uses them to decide how to assign responses.

Here's how to handle them effectively:

* Review all generated descriptions after the first run.
* Edit vague or generic ones, or delete confusing descriptions — the AI will automatically regenerate better ones during the next run.
* Avoid overlaps — make sure descriptions clearly distinguish similar topics.

<Frame>
  <img alt="Edit topic descriptions" />
</Frame>

## Tip 3: Do Smart Quality Checks

You no longer need to review hundreds of rows. Instead, use **targeted checks**:

1. **Check coverage** — if \~90% of rows have topics, you're in great shape.
2. **Spot-check 10–15 responses** — make sure assignments make sense.
3. **Use AI certainty** (optional) — rows with low confidence might reveal topics needing better descriptions.
4. **Focus on weak spots** — review topics with low coverage or unclear descriptions.

<Frame />

## Tip 4: Understand the AI Score

<Frame>
  <img alt="Screenshot 2026 05 20 At 18 30 35" />
</Frame>

After each run you see an **AI Score**: how confidently the model assigned topics overall.

| Scenario                      | Typical score |
| :---------------------------- | :------------ |
| Same person codes twice       | \~90          |
| Two people code independently | 70–80         |
| Human-level AI performance    | 70–85         |

## Tip 5: Refine Before Rerunning

Before running again, ask yourself:

* Are my topic descriptions clear and specific?
* Have I merged similar or overlapping topics?
* Have I removed or rewritten any confusing descriptions?

**Caplena supports both partial and full AI updates**:

* For small changes (e.g., updating 1–2 topics), a **partial update** is more efficient.
* For broader changes, a **full update** ensures consistency across your dataset.

<Tip>
  Once you trigger a rerun, the AI will regenerate missing or deleted descriptions and reassign topics based on your updated setup.
</Tip>

## Tip 6: Know When to Stop

Your project is ready when:

* The **AI Score** is 70+
* Each topic has a clear, correct description
* Most responses have a topic
* Spot checks look accurate


# Prompt-Based Topic Generation
Source: https://docs.caplena.com/topic-assignment/new-ai/prompt-based-topic-generation

Use natural language prompts to generate tailored topics or rebuild your topic collection from scratch.

Uploaded your survey responses, NPS data, or customer reviews? Great, now it's time to turn them into clear, actionable themes. That's where **Prompt-Based Topic Generation** comes in.

Whether you're adding new topics or rebuilding your collection entirely, this feature lets you steer the AI using plain language, with you firmly in control.

## How Topic Generation Works (Without Prompts)

When no custom prompt is provided, Caplena passes a default prompt to the LLM that looks like this:

*Generate **topics** from recurring themes in the provided rows. Group them into **categories**.*

The model also uses your project context automatically:

* Project name
* Project description
* Column description
* Topic language
  A solid starting point, but for more control, that's where prompt-based generation comes in.

## Enabling Prompt-Based Topic Generation

You'll find the **Prompt-Based Topic Generation toggle** at the top of the Topic Editor. Switch it on to reveal the prompt input and choose your mode.

<Frame>
  <img alt="Screenshot 2026 05 21 At 08 42 11" />
</Frame>

## Two Modes to Choose From

Once the toggle is on, you'll see two tabs:

### New topic suggestions

Generates new topic suggestions matching your prompt, computed on a sample of up to 20,000 rows. The existing topic collection stays untouched, you review the suggestions and decide what to add.

**Use this when you want to:**

* Explore specific themes without disrupting your current structure
* Add topics incrementally as new patterns emerge

<Frame>
  <img alt="Screenshot 2026 05 21 At 08 21 59" />
</Frame>

<Tip>
  Example prompts: *"Return all topics related to contracts"* or *"Find all brand names mentioned"*
</Tip>

### Redo topic collection

Rebuilds your entire topic collection based on your prompt. This prompt also becomes the **default for future topic suggestions in alerts**.

**Use this when you want to:**

* Start fresh with a new topic framework
* Apply a specific structure across your full dataset

<Frame>
  <img alt="Screenshot 2026 05 21 At 08 22 06" />
</Frame>

<Tip>
  Example prompts: *"Group feedback under: Pricing, Usability, Performance, Design"* or *"Give me only topics related to smart TV features"*
</Tip>

<Note>
  The **Redo topic collection** prompt will be reused automatically for future alert-based topic suggestions. Make sure it reflects the structure you want to maintain long-term.
</Note>

##


# Tracker Setup: Best Practices
Source: https://docs.caplena.com/topic-assignment/new-ai/tracker-setup

How to manage large-scale trackers efficiently using a development and production project setup.

Large-scale trackers, whether CX, VoC, Employee Experience (EX), brand trackers, or recurring wave studies, come with unique challenges around topic management. You're often dealing with tens of thousands, hundreds of thousands, or even millions of rows per year, and you need to:

* Develop and refine your topic collection quickly and iteratively
* Detect new trends that emerge over time
* Maintain an audit trail so any changes are deliberate, not accidental

Caplena recommends a **DEV + PROD project setup** to handle all three.

<iframe title="Loom video player" />

## The setup

You maintain two projects:

<Frame>
  <img alt="Screenshot 2026 06 15 At 08 17 41 1" />
</Frame>

* **DEV project** — a representative sample of your full dataset (typically 1,000–20,000 rows). This is your test ground for developing and iterating on your topic collection. AI runs here are fast and cheap.
* **PROD project** — your full dataset. Topics are only applied here once you've validated them in DEV.

Your CSM team can set up the DEV project for you and ensure it's always a representative sample of your production data.

## Initial setup

<Steps>
  <Step title="Build your topic collection in DEV">
    Use the DEV project to develop your initial topic collection with LLM support. Explore rare topics, refine descriptions, and customize until you're happy with the structure.
  </Step>

  <Step title="Run a quality check">
    Apply the topics to the DEV project and scroll through a sample of responses to verify the assignments look right. Add or adjust topics as needed — this is the time to experiment.
  </Step>

  <Step title="Copy topics to PROD">
    Once satisfied, copy the topic collection from DEV to your PROD project. In the DEV project, open the **Topics** tab, select **Copy to another project**, and choose your PROD project. This transfers the full topic collection and triggers the initial AI assignment.

    <Frame>
      <img alt="Screenshot 2026 06 17 At 16 47 28" />
    </Frame>

    For large datasets, the initial assignment may take anywhere from a few minutes to a few hours. From this point on, new rows coming into PROD will automatically be assigned using the same topic collection.
  </Step>
</Steps>

## Ongoing maintenance: updating topics over time

Over time, new themes emerge in your data. Here's the recommended workflow for adding or refining topics without disrupting your production data:

<Steps>
  <Step title="Spot new trends in PROD">
    Use the Topic Assistant in your PROD project to review AI-suggested new topics. When you find topics worth adding, add them directly to PROD — but don't run a full AI update yet.

    <Frame>
      <img alt="Screenshot 2026 06 15 At 10 54 55 1" />
    </Frame>
  </Step>

  <Step title="Sync the new topics to DEV">
    Head back to your DEV project and connect it to your PROD project via a learning relationship. This creates a circular relationship: PROD was originally built from DEV, and now DEV points back to PROD to pick up the newly added topics.

    To set this up: open your DEV project → **Settings → Learning Relationships** → add your PROD project as the source.

    <Frame>
      <img alt="Screenshot 2026 06 17 At 09 00 17" />
    </Frame>

    Once linked, click **Resync topics from source**. The new topics you added to PROD will now appear in DEV as well.

    <Frame>
      <img alt="Screenshot 2026 06 17 At 08 49 51" />
    </Frame>

    <Tip>
      Setting a learning relationship by itself doesn't trigger any changes — you need to explicitly click **Resync topics from source** to pull in the latest topics. See [Learning Relationships Between Projects](/topic-assignment/understanding-the-basics/learning-relationships-between-projects-legacy-ai-vs-new-ai) for a full explanation.
    </Tip>
  </Step>

  <Step title="Iterate in DEV">
    Run AI updates in DEV to see how the new topics are assigned on your sample. You can experiment freely here — merge topics, split them, adjust descriptions, run another update. Since DEV is a small sample (typically 1,000–20,000 rows), each AI run is fast and inexpensive, giving you quick feedback on every change.

    <Tip>
      Don't worry about being careful in DEV — that's the whole point. Save the careful, deliberate updates for PROD.
    </Tip>
  </Step>

  <Step title="Sync back to PROD and run one consolidated update">
    Once you're happy with how topics are assigned in DEV, sync the finalized topics back to PROD using **Resync topics from source** — this time in your PROD project, pulling from DEV.

    Then run a single consolidated AI update on PROD. This applies all your changes at once — keeping your assignment history clean and making it easy to see exactly what changed and when.

    <Info>
      If you had iterated directly on PROD and run an AI update after each small change, you'd be paying for a full update on potentially millions of rows every single time. The DEV/PROD workflow means you only ever run one update on PROD per iteration cycle.
    </Info>
  </Step>
</Steps>

## Why this approach

* **Efficiency** — iterating on a sample of 5,000 rows instead of 1,000,000 means faster feedback and dramatically lower AI run costs. You only pay for a full production update once you're confident in your changes.
* **Quality** — you validate topic assignments on real data before pushing anything to production. No surprises.
* **Audit trail** — all changes to the production project happen in one deliberate batch. Your topic assignment history stays clean and meaningful, making it easy to track what changed and when.

<Info>
  This workflow is especially powerful for recurring programs — wave studies, CX trackers, VoC programs, and EX surveys — where consistency across periods is critical.
</Info>

## Related

<Card title="Learning Relationships Between Projects" icon="link" href="/topic-assignment/understanding-the-basics/learning-relationships-between-projects-legacy-ai-vs-new-ai">
  Learn how topic inheritance and resyncing works across projects — and when to use it with the New AI.
</Card>


# Group Identical Rows
Source: https://docs.caplena.com/topic-assignment/understanding-the-basics/group-identical-rows

Simplify your workspace by collapsing duplicate responses into a single row — without affecting your data or analysis.

This setting simplifies your view by collapsing duplicate responses into a single row, keeping your workspace clean without affecting any analysis or exports.

## How to turn it on

<Steps>
  <Step title="Open Settings">
    Click the three dots (⋯) in the top right of the Data Tab and select **Settings**.
  </Step>

  <Step title="Enable grouping">
    Toggle on **Group identical rows**.

    <Frame>
      <img alt="Clean Shot 2026 04 07 At 18 14 02" />
    </Frame>
  </Step>
</Steps>

## What it does

When enabled, responses with identical text (ignoring capitalization) are shown only once in the list. Topics are still applied to every occurrence behind the scenes, you just see a tidier view. This setting only affects what you see on screen; it has no impact on your data or results.\
\\

<Frame>
  <img alt="Screenshot 2026 05 20 At 15 50 42" />
</Frame>

<Note>
  **Example:** If 20 respondents all wrote "Great", you'll see it appear once in the list. All 20 responses are still counted in statistics and included in exports.
</Note>

## What changed in duplicate grouping

The grouping behaviour was recently updated to be more consistent. As a result, responses that previously appeared grouped may now show separately if their topic assignments differ.

<Frame>
  <img alt="Screenshot 2026 05 20 At 15 52 54" />
</Frame>

### How to regroup duplicates

If responses that used to be grouped are now showing separately, it's because they have different topic assignments. Here's how to fix it:

<Steps>
  <Step title="Select the duplicate rows">
    Select all rows with the same response text.
  </Step>

  <Step title="Align topic assignments">
    Use **Bulk Assign** to give them the same topics.
  </Step>

  <Step title="Match review status">
    Make sure their review status also matches (all reviewed or all unreviewed).
  </Step>

  <Step title="Wait for regrouping">
    Regrouping isn't instant — it may take a couple of minutes to apply.
  </Step>
</Steps>


# Learning Relationships Between Projects
Source: https://docs.caplena.com/topic-assignment/understanding-the-basics/learning-relationships-between-projects-legacy-ai-vs-new-ai

How topic inheritance works in the Legacy AI and the New AI

Learning relationships allow you to reuse topics from one project in another — saving time and maintaining consistency across similar datasets.

If you're looking for instructions on **how to set up** learning relationships, refer to [the following article](/topic-assignment/understanding-the-basics/starting-the-analysis#step-1-choose-how-to-start).

Below is a clear explanation of how learning relationships behave in both the **Legacy AI** and the **New AI**, and when you should (or shouldn't) use them.

## Learning Relationships in the Legacy AI

In the Legacy AI, learning relationships play an important role in ensuring consistency across multiple related projects or waves.

A learning relationship allows Project B to inherit both:

* The **topic structure** (topics, categories, sentiment), and
* The **training you performed** in Project A.

This means the AI will classify new comments in Project B using the patterns learned from Project A.

### Learning Cascades (Multiple Projects)

If you connect several projects — e.g. Project A → Project B → Project C — the AI forms a **learning cascade**:

* C learns from B
* B learns from A
* A indirectly influences C

However, as the chain grows longer, the influence of earlier projects becomes weaker:

* With 3–5 connected projects → still strong
* With 10–20 projects → the earliest projects have minimal impact

<Tip>
  Choose the **most recent, best-trained project** as the learning source whenever possible.
</Tip>

### What happens if you remove the learning relationship?

* **Immediately** — nothing changes. Your existing topics and assignments remain intact.
* **Over time** — once you start adjusting topics or making assignment changes, the AI will no longer reinforce the inherited learnings and may gradually lose what it inherited.

### Ensuring new topics aren't missed

When using learning relationships across multiple waves, consider:

**Generating additional topics** — after selecting the learning project, use the "Additional Topics" feature to detect emerging patterns specific to the new dataset.

**Manual review** — review a sample of comments without topics or use free-text search to catch new themes that may not exist in the inherited project.

## Learning Relationships in the New AI

The behavior of learning relationships changes significantly in the New AI.

<Warning>
  For the New AI, we generally do **not** recommend using learning relationships.
</Warning>

Here is why:

### Risk of confusing the New AI

Inheriting topics from another project can hurt performance if:

* That project wasn't trained well, or
* It was trained using the **Legacy AI**, which works differently.

In these cases, inherited topics may not match your new dataset and can confuse the New AI, leading to lower-quality assignments.

### Inherited topic descriptions often don't fit the new dataset

Internal testing shows that if the new project contains even slight variations of the same question or a different data column context, inherited descriptions may no longer match well. This often results in:

* Lower topic assignment confidence
* More unassigned rows
* Inconsistent labeling behavior

### Adding new topics can increase unassigned rows

When you inherit topics and then add new ones, the AI tries to interpret old descriptions written for the previous dataset alongside new ones written for your current dataset. This mismatch can further reduce assignment quality.


# Key concepts: Categories, topics & sentiment
Source: https://docs.caplena.com/topic-assignment/understanding-the-basics/main-concepts-categories-topics-sentiment

Understand the building blocks of analysis in Caplena before you start.

Caplena analyzes open-ended feedback by organizing it into categories, topics, and (optionally) sentiment. Getting familiar with these three concepts will make everything else click faster.

### Category

A **category** is a high-level theme that groups related topics together, for example `Customer Service`, `Product Quality`, or `Pricing`.

<Frame>
  <img alt="Categories" />
</Frame>

<Note>
  Categories are taken into account by the AI when assigning topics.
</Note>

### Topic

A **topic** is a specific idea or theme within a categorym what someone is actually talking about in their response. Topics are also referred to as codes, themes, or labels.

Examples within a Customer Service category:

* `Support Responsiveness`
* `Refund Process`
* `Property Communication`

#### Topic label

The **topic label** is the short name you give a topic. It appears on topic chips throughout Caplena and is what the AI uses to recognize and assign the topic.

<Note>
  The label directly affects AI accuracy, keep it clear and specific.
</Note>

#### Topic description

A longer explanation of what the topic covers and when it should apply. Descriptions give the AI more context and are especially important for topics that might otherwise overlap.

<img alt="Topic description" />

<Note>
  Topic descriptions are used by the AI when assigning topics, the more precise, the better the results.
</Note>

#### Code

A **code** is a unique numerical ID assigned to each topic. Caplena assigns one automatically, but you can set it manually if you need to match an existing coding scheme.

<img alt="Screenshot 2026 05 19 At 20 36 25" title="Screenshot 2026 05 19 At 20 36 25" />

### Sentiment

**Sentiment** adds emotional context to topics, classifying each response as **positive**, **neutral**, or **negative**. Instead of just knowing what someone talked about, you also know how they felt about it.

<img alt="Sentiment" />

For example:

* `Support / Helpfulness – Positive` → "The team was incredibly helpful"
* `Support / Helpfulness – Negative` → "No one responded to my request"

You only need to create one topic (e.g. `Support`), the AI assigns the sentiment automatically.

**Sentiment is optional.** Turn it on for opinion-based data like NPS or CSAT. Skip it for factual data like feature requests or open suggestions.

#### Disabling sentiment

You can disable sentiment on a per-topic basis or across multiple topics at once.

**Single topic:** Open the topic's settings in the codebook editor and toggle sentiment off.

<Frame>
  <img alt="Screenshot 2026 06 27 At 14 38 35" title="Screenshot 2026 06 27 At 14 38 35" />
</Frame>

**Multiple topics at once:** Use the Topic Assistant's bulk actions menu, select **Disable sentiment** to remove it from all selected topics in one step. See [Enable or disable sentiment in bulk](/topic-assignment/understanding-the-basics/using-the-topic-assistant#enable-or-disable-sentiment-in-bulk) for details.


# Starting the analysis
Source: https://docs.caplena.com/topic-assignment/understanding-the-basics/starting-the-analysis

Generate your first topic structure and start making sense of your data.

Once your data is in Caplena, uploaded manually or via integration (Google, Amazon, Qualtrics, API, etc.), you're ready to start your analysis.

### Overview panel

When you open your project, you'll land on the **Overview panel**, where you can see the question designated for analysis and an AI-generated summary of key themes.

Click **"Start analysis now"** to begin.

<Frame>
  <img alt="Overview panel" />
</Frame>

***

### Step 1: Choose how to start

<Frame>
  <img alt="Topic generation options" />
</Frame>

**Start from scratch**

The AI automatically generates a topic structure based on your data. Best if you're analyzing this type of feedback for the first time.

**Import existing topics**

<Frame>
  <img alt="Clean Shot 2026 05 19 At 19 08 43" />
</Frame>

Reuse a topic collection you already have, either from a previous Caplena project or an Excel file.

* **Other project** - Choose a previous project, select the relevant text column, and click **"Inherit topic collection"**. Ideal for recurring surveys (e.g. quarterly NPS, monthly product feedback) where consistency across waves matters. For large-scale recurring projects, see [Tracker Setup: Best Practices →](/topic-assignment/new-ai/tracker-setup).
* **Upload File** - Import your own topic collection from a CSV or Excel file. Supported columns:
  * `topic` (required) - The topic name.
  * `category` (optional) - The category the topic belongs to.
  * `code` (optional) - A unique numerical ID for the topic.
  * `sentiment` (optional) - The sentiment setting for the topic.
  * `description` (optional) - A longer explanation of when the topic applies. Used by the AI as a primary input when assigning topics, so clear descriptions noticeably improve assignment quality.
  * `keywords` (optional) - Comma-separated keywords for the topic. Used in Semi-Open mode to match responses. Each keyword must be **30 characters or fewer** (including spaces) — imports with longer keywords are rejected with an error, so shorten or split them before uploading. Your file must match one of these formats. With sentiment:
  <Frame>
    <img alt="Excel format with sentiment" />
  </Frame>
  Without sentiment:
  <Frame>
    <img alt="Excel format without sentiment" />
  </Frame>
  <Tip>
    **Include topic descriptions when uploading.** Descriptions tell the AI *when* a topic should apply, not just what it's called. A topic like `Pricing` becomes much more reliable when paired with a description such as *"Mentions of cost, price, fees, or value for money — including comments about discounts and subscription tiers."* If you leave the column empty, Caplena auto-generates descriptions on the first run, but uploading your own keeps assignments aligned with how your team defines each topic.
  </Tip>
  Example with descriptions:

<Frame>
  <img alt="Screenshot 2026 06 29 At 08 33 41" />
</Frame>

### Step 2: Enable sentiment (optional)

Sentiment detection classifies the emotional tone of each response as **positive**, **neutral**, or **negative**. When enabled, a topic like *Customer service* splits into *Customer service – positive* and *Customer service – negative*, so you can see not just what people mention but how they feel about it.

<Frame>
  <img alt="Sentiment configuration" />
</Frame>

**Turn it on** if your data contains opinions or emotional responses — NPS comments, CSAT surveys, employee feedback:

> "The support team was incredibly helpful." → *Customer Service – Positive*
>
> "Waiting times were terrible." → *Customer Service – Negative*

**Skip it** if your data is factual — feature requests, improvement suggestions, etc.:

> "Add a dark mode option." → No sentiment needed
>
> "Please include PDF export in the next update." → No sentiment needed

***

### Step 3: Generate topics

Caplena generates a **MECE** topic collection, mutually exclusive and collectively exhaustive, so topics cover all relevant feedback without overlap.

<iframe title="Loom video player" />

**Initial topic collection**

The AI generates a draft collection of **20–60 topics** grouped into categories, based on up to 20,000 rows of your data plus your project name, description, and question context. Each topic includes an auto-generated description you can edit.

<Frame>
  <img alt="Initial topic collection" />
</Frame>

You'll also see:

* **Rare topics** - not included by default, but available to browse and add manually
* **Similar topics** - flagged for potential merging or removal

<Tip>
  The AI tends to generate more topics than you need. Remove what's irrelevant early, a leaner topic structure leads to cleaner results.
</Tip>

**Prompt-based generation**

You can guide how topics are created using a custom prompt, useful when you want to focus on a specific theme or apply your own framework.

<Frame>
  <img alt="Prompt-based topic generation" />
</Frame>

| Mode                           | What it does                                                                 |
| ------------------------------ | ---------------------------------------------------------------------------- |
| **Regenerate full collection** | Rewrites the entire topic collection from scratch based on your prompt.      |
| **Generate new suggestions**   | Adds new suggestions on top of your existing collection without changing it. |

Once you set a prompt it becomes your default, used when editing topics and when new rows are uploaded. You can override it anytime for a one-off run.

When you're happy with the topic collection, click **Done**. The AI will begin assigning topics within 1–2 minutes.

[Learn more about prompt-based generation →](/topic-assignment/new-ai/prompt-based-topic-generation)

***

### Step 4: Review and refine

How much manual tweaking you'll need depends on which AI model you're using:

**New AI** — typically delivers human-level quality after the first run; only light adjustments needed. [Learn more →](/topic-assignment/new-ai/how-the-new-llm-topic-assignment-works#workflow-overview)

**Legacy AI** — may require more hands-on review: merging overlaps, clarifying vague topics, adding missing ones. [Learn more →](/topic-assignment/legacy-ai/ai-training)


# Using the Topic Assistant
Source: https://docs.caplena.com/topic-assignment/understanding-the-basics/using-the-topic-assistant

AI-powered suggestions to refine your topic structure — add missing topics, merge overlaps, and surface rare themes.

The Topic Assistant supports you in creating and refining a robust topic structure. It provides AI-driven suggestions to add missing topics, highlight overlaps, and identify items that may not be relevant. This helps you maintain a consistent and meaningful categorization of your data.

<iframe title="Loom video player" />

## Where to find it

In the Topics editor, the Topic Assistant is located on the right-hand side with the following options:

<Frame>
  <img alt="CleanShot 2026-05-20 at 10.58.57" />
</Frame>

* **New topics** – Suggestions for potential topics detected in your data.
* **Similar topics** – Topics that may overlap in meaning and could benefit from merging or clarification.
* **Discarded topics** – A list of suggestions you have chosen not to include.
* **Show rare topics** – An optional toggle to surface low-frequency topics. These can reveal niche insights but may also add noise, so use them selectively.

## How it works

The AI reviews your responses in relation to the topics you have defined. It proposes new topics where gaps exist, flags similar topics to reduce redundancy, and shows rare topics for deeper exploration. All actions remain under your control — you decide what to add, merge, or discard.

## Using the Topic Assistant in Tracking & Wave Studies

In tracking projects where you add new data waves regularly, the Topic Assistant is especially valuable for keeping your topic structure up to date without disrupting consistency across waves.

The core challenge in tracking studies is that new waves often bring new themes that weren't in your original codebook. The Topic Assistant helps you spot these without having to manually read through hundreds of new responses.

### How to review new topic suggestions

When new data is added, the AI scans responses against your existing codebook and surfaces themes that aren't covered yet. For each suggestion, you can:

<Frame>
  <img alt="Screenshot 2026 06 17 At 10 22 56" />
</Frame>

* **Add to codebook** — the topic is added to your structure and will be assigned going forward. Existing responses in the new wave will be reassigned if relevant once you run the AI update.
* **Discard** — the suggestion is moved to the Discarded tab. The AI will stop surfacing it, but you can always retrieve it later if you change your mind.

<Tip>
  **Best practice for tracking studies:** Review new topic suggestions after each wave is uploaded, before sharing results with stakeholders. This ensures your codebook reflects the current wave's themes and that nothing significant is missed.
</Tip>

### What happens when you discard a topic

Discarding a suggestion tells the AI you don't want it in your codebook. It moves to the **Discarded topics** tab and won't be suggested again. Nothing changes in your existing data — no assignments are affected. If you later decide the topic is relevant, you can retrieve it from the Discarded tab and add it.

### Rare topics

Enable the **Show rare topics** toggle to surface themes that appear in only a small number of responses. These are hidden by default because they can add noise, but in tracking studies they're worth reviewing — a topic with very few mentions in one wave might grow significantly in the next.

<Tip>
  Use rare topics to catch early signals. Something mentioned by 3–4 respondents this wave could be a leading indicator of a bigger trend next wave.
</Tip>

## Collapse topic suggestions

Hide the right-hand panel with AI-generated topic suggestions (New, Similar, Discarded) to focus on your current topic structure. You can reopen it anytime to continue reviewing AI insights.

<Frame>
  <img alt="Collapse or expand the Topic Assistant panel" />
</Frame>

## Mention counts at a glance

You can now see how often each suggested topic appears in your data, right from the Assistant table view. This makes it much easier to:

* Spot topics with just a handful of mentions
* Decide what to clean up, merge, or discard — without opening charts

<Frame>
  <img alt="Screenshot 2026 06 17 At 10 24 55" />
</Frame>

## Renumber topic codes

Want your topic codes neat and in order? You can easily renumber them right inside the Topics editor.

<Frame>
  <img alt="Renumber topic codes with # Renumber" />
</Frame>

<Steps>
  <Step title="Click Renumber">
    At the bottom of the topic list, click **# Renumber**.
  </Step>

  <Step title="Set your starting number">
    Choose your **starting number** (e.g., `1`) and click **Apply**.
  </Step>
</Steps>

Your topics will automatically get sequential codes based on the order they appear.

## Enable or disable sentiment in bulk

The Topic Assistant lets you turn sentiment **on or off for multiple topics at once**, instead of opening each topic one by one. This is the recommended way to update sentiment across an entire codebook.

**How to do it**

<Frame>
  <img alt="Screenshot 2026 06 26 At 16 48 15" />
</Frame>

1. Open the Topic Assistant from the Topics editor.
2. In the bulk actions menu, click either:
   * **Enable sentiment** — to start classifying responses as positive, neutral, or negative for the selected topics.
   * **Disable sentiment** — to remove sentiment from the topics.

> 💡 If you only need to change sentiment on a single topic, you can also do it directly from that topic's settings. See [Disabling sentiment](/topic-assignment/understanding-the-basics/main-concepts-categories-topics-sentiment#disabling-sentiment) in *Key concepts* for the individual flow.