Add Case Custom Fields documentation

[Sengthay]

https://storage.gra.cloud.ovh.net/v1/AUTH_741841e1c7da4c50a76152cbc2609bd1/sekoiaio-documentation-previews/2766/xdr/features/investigate/case_custom_fields/

[github-actions]

Newest code from Sengthay has been published to preview environment

🚀 Latest deployment was built on 2026-01-27 09:29:53 (5b7c30995f39bc9aaf4edbdf650d2a38492e7e82).

[alexane-bougeardbebin-sekoia]

Hello @Sengthay,

I think we rather should respect diataxis standard and create 4 differente articles:

• 1 concept: explaining context, logic, use case...
• 2 tasks: Manage custom field definitions / Manage custom field values in cases
• 1 reference: technical spec.

---

Article 1 : Concept

# Case custom fields

Case custom fields enable security analysts to classify cases with structured data for improved tracking and reporting. By defining specific fields, your organization can capture essential metadata that supports automation and data-driven decision-making.

## Context and logic

Standard case properties often require additional context specific to an organization's internal processes. Custom fields extend these properties, providing a consistent way to query information across the platform.

In multi-tenant environments, custom field definitions are managed at the parent workspace level. Child tenants use the fields defined by the parent but cannot modify the definitions, ensuring global consistency for MSSPs and large enterprises.

## Benefits

* **Standardization**: Force consistent data entry across all analyst teams.
* **Granular Filtering**: Use the Sekoia Operating Language (SOL) to filter cases based on internal metadata.
* **Custom Reporting**: Build dashboards that reflect your specific KPIs, such as department-level impact or custom risk scores.

## Use cases

* **Impact Assessment**: Track the number of affected users or specific business units.
* **Compliance**: Tag cases with specific regulatory frameworks (e.g., GDPR, HIPAA).
* **Team Routing**: Identify which internal team is responsible for remediation.

---

Article 2 : Task (Configuration)

# Manage custom field definitions

This article explains how to define and modify the custom fields available for your cases.

## Prerequisites

* You must have an **Admin** or **Analyst** role to manage field definitions.

## Create a custom field

1. Navigate to **Settings > Custom Fields**.
2. Click **+ Add**.
3. Enter a name in the **Name** field.
4. Enter a description in the **Description** field.
5. Select a data type from the **Type** dropdown menu.
6. Select a **Color** for visual identification in the UI.
7. To show this field on all new cases automatically, toggle **Auto-add to new cases**.
8. Define the available options if you selected a **Single select** or **Multi select** type.
9. Click **Save**.

> 📸 [SCREENSHOT SUGGESTION: The "Add Custom Field" modal with a Single Select type selected and some options filled. | ALT TEXT: Creation modal for a new custom field.]

## Edit a custom field

!!! note "Type restriction"
    You cannot change the **Type** of a field after you create it. To use a different data type, you must delete the field and create a new one.

1. Navigate to **Settings > Custom Fields**.
2. Click the field you want to modify.
3. Update the properties.
4. Click **Save**.

## Delete a custom field

!!! warning "Permanent data loss"
    Deleting a field definition permanently removes that field and all its associated values from every case in the workspace.

1. Navigate to **Settings > Custom Fields**.
2. Click the field you want to remove.
3. Click **Delete**.
4. Click **Confirm** in the confirmation dialog.

---

Article 3 : Task (Utilisation)

# Manage custom field values in cases

This article describes how to interact with custom fields within an individual case.

## Add a field to a case

If a field is not set to auto-add, you can add it manually to any case.

1. Open a case and locate the **Custom Fields** section.
2. Click **+ Add**.
3. Select the desired field from the list.
4. Enter or select the value.
5. Click **Save**.

> 📸 [SCREENSHOT SUGGESTION: The Custom Fields section within the Case details view. | ALT TEXT: Custom fields section in a case.]

## Edit a field value

1. Open the case details page.
2. In the **Custom Fields** section, click the value of the field you want to change.
3. Update the value.
4. Click **Save**.

!!! note "Audit trail"
    The system tracks all changes to custom field values in the **Updates** tab of the case.

---

Article 4 : Reference

# Custom fields reference

This page provides the technical specifications for custom fields, including data types, naming conventions for queries, and system limits.

## Supported data types

| Type | Description |
| :--- | :--- |
| **Text** | Free-form alphanumeric values. |
| **Single select** | A dropdown where you choose exactly one predefined option. |
| **Multi select** | A list where you choose one or more predefined options. |
| **Integer** | Whole numeric values. |
| **Boolean** | A toggle for True or False values. |

## Querying with SOL

You can query custom fields using the `custom_fields` prefix. The system converts field names to `snake_case`.

### Naming convention examples

| Field Name | SOL Column Name |
| :--- | :--- |
| Number of impacted users | `custom_fields.number_of_impacted_users` |
| Impacted teams | `custom_fields.impacted_teams` |

### Common query patterns

??? example "Filter by numeric value"
    To find cases where more than 2 users are impacted:
    ```
    cases | where custom_fields.number_of_impacted_users > 2
    ```

??? example "Filter by selection"
    To find cases involving specific teams:
    ```
    cases | where custom_fields.impacted_teams in ["HR", "Finance"]
    ```

## System limits

| Resource | Limit |
| :--- | :--- |
| Field definitions per workspace | 100 |
| Options per select field | 50 |
| Field name length | 50 characters |
| Field description length | 100 characters |
| Value length | 50 characters |
| Fields per case | 25 |

---

At the end of the day we should also revamp cases article and have something like this:

nav:
- Investigate:
    - Cases:
        - Understanding Cases: 
            - What are Cases?: cases.md
            - How Custom Fields work: case_custom_fields.md
            - How AI assists investigations: ai_cases_concept.md
        - Using Cases:
            - Create and manage cases: manage_cases.md
            - Set up custom field definitions: manage_custom_field_definitions.md
            - Add custom data to cases: manage_custom_field_values.md
            - Run an AI investigation: ai_cases_investigation.md
        - Resources & Syntax:
            - Status and Verdict definitions: case_properties_reference.md
            - SOL Query naming and limits: custom_fields_reference.md

What do you think?