# 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](https://docs.valtimo.nl/valtimo-docs-v3/configuration-guides/building-blocks) - Reusable subprocesses that can be linked to case definitions