# Cases

A case definition is the blueprint for a case in Valtimo. It contains everything needed to run cases of that type, including process models, form definitions, decision tables, and a data schema. This page describes how to create, configure, and manage case definitions.

{% hint style="info" %}
New to cases? Read [What is a case?](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/fundamentals/what-is-a-case.md) first for a conceptual overview.
{% endhint %}

## Overview

A case definition contains everything needed to run a case, such as process models, form definitions, decision tables, and a data schema. When a case is created, it is an instance of a case definition.

Each version of a case definition has two independent properties:

* **Status:** A version is either a draft or final. Draft versions are editable; final versions are read-only.
* **Globally active:** Any version — draft or final — can be set as globally active. Only one version can be globally active at a time. Only the globally active version is used when new cases are created. Existing cases are not affected when a new version becomes active.

The case definition management interface is accessible via **Admin → Cases** and requires the `ROLE_ADMIN` role.

## Creating a case definition

* Go to **Admin** in the left sidebar.
* Select **Cases**.
* Click **Create**.
* Fill in the required fields:

| Field       | Required | Description                                                                        |
| ----------- | -------- | ---------------------------------------------------------------------------------- |
| Name        | Yes      | Display name of the case definition.                                               |
| Key         | Yes      | Unique identifier. Auto-generated from the name, but can be changed before saving. |
| Version     | Yes      | Starting version in semantic versioning format, e.g. `1.0.0`.                      |
| Description | No       | Free-text description of the case definition.                                      |

* Click **Save**.

The case definition is saved as a **draft** version and you are navigated to its detail page.

{% hint style="warning" %}
The key cannot be changed after the case definition is created.
{% endhint %}

## Versioning and deployment

Case definitions use semantic versioning. Each version has a status (draft or final) and a globally active flag that are managed separately.

### Draft versions

A draft version is fully editable. All configuration is available for modification as long as the version has draft status. Draft versions are marked with a red tag.

### Finalizing a version

* Verify the version is ready to finalize.
* Open the **Deployment** tab of the case definition.
* Click **Finalize**.
* Confirm the action.

{% hint style="danger" %}
A finalized version cannot be edited. To make further changes, create a new draft version.
{% endhint %}

Final versions are marked with a green tag.

### Creating a new draft version

After a version is finalized, you can create a new draft to continue making changes:

* Open the **Deployment** tab.
* Click **Create draft version**.
* Enter a version number for the new draft.
* The new draft is based on the selected version.

### Setting a version as globally active

Any version — draft or final — can be set as globally active. Only one version can be globally active at a time, and only that version is used for newly created cases.

* Select the desired version from the version selector in the page header.
* Click the **...** menu and select **Set as active**.
* Confirm the action.

### Deleting a draft version

Draft versions can be deleted via the **Deployment** tab. Finalized versions cannot be deleted.

## Import and export

### Exporting a case definition

A case definition can be exported as a `.zip` file. The export includes the case configuration, such as the document definition, forms, processes, and business rules. Configuration that is not part of the case definition — such as access control and dashboards — is not included in the export.

* Open the case definition.
* Click **Export** in the action menu.

### Importing a case definition

* Go to **Admin → Cases**.
* Click **Import**.
* Select a `.zip` file.
* Follow the steps in the import wizard:
  1. Verify that all required plugins are configured in this environment.
  2. Select the file.
  3. Upload the file.

{% hint style="info" %}
The imported version retains the status it had at the time of export.
{% endhint %}

## Access control

Access to case definitions can be configured through access control. More information about access control can be found [here](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/access-control.md).

### Resources and actions

| Resource type                                        | Action      | Effect                                                  |
| ---------------------------------------------------- | ----------- | ------------------------------------------------------- |
| `com.ritense.case_.domain.definition.CaseDefinition` | `view`      | Allows viewing an individual case definition.           |
| `com.ritense.case_.domain.definition.CaseDefinition` | `view_list` | Allows browsing the list of available case definitions. |

### Examples

<details>

<summary>Permission to view all case definitions</summary>

```json
{
    "resourceType": "com.ritense.case_.domain.definition.CaseDefinition",
    "action": "view_list",
    "conditions": []
}
```

</details>

<details>

<summary>Permission to view a specific case definition</summary>

```json
{
    "resourceType": "com.ritense.case_.domain.definition.CaseDefinition",
    "action": "view",
    "conditions": [
        {
            "type": "field",
            "field": "id",
            "operator": "==",
            "value": "my-case-definition"
        }
    ]
}
```

</details>

## Related

* [Cases](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/configuration-guides/cases/cases.md) - Overview of the cases feature
* [Access control](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/access-control.md) - Configure role-based access
* [Building blocks](/valtimo-docs-v3/configuration-guides/building-blocks.md) - Reusable subprocesses that can be linked to case definitions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valtimo.nl/valtimo-docs-v3/configuration-guides/case-definition.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.