> For the complete documentation index, see [llms.txt](https://docs.valtimo.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valtimo.nl/configuration-guides/cases.md).

# Cases

The Cases configuration area lets you manage case definitions — the templates that define how different types of cases behave in your Valtimo implementation. Each case definition specifies its document structure, linked processes, forms, and how it appears to end users.

From here you can configure:

* [**General**](/configuration-guides/cases/general.md) — Case handler settings and external start form
* [**Processes**](/configuration-guides/cases/processes.md) — BPMN process definitions linked to the case
* [**Actions**](/configuration-guides/cases/actions.md) — Startable items (processes and building blocks) users can trigger from a case
* [**Decision tables**](/configuration-guides/cases/decision-tables.md) — DMN decision tables for automated decisions
* [**Document**](/configuration-guides/cases/document.md) — JSON schema defining the case's data structure
* [**Forms**](/configuration-guides/cases/forms.md) — Form definitions available for the case
* [**Form flows**](/configuration-guides/cases/form-flows.md) — Multi-step form sequences
* [**Tasks**](/configuration-guides/cases/tasks.md) — Task list column and search field configuration
* [**Case list**](/configuration-guides/cases/case-list.md) — End-user case list columns and search fields
* [**Case details**](/configuration-guides/cases/case-details.md) — Tabs, statuses, tags, and header configuration
* [**ZGW**](/configuration-guides/cases/zgw.md) — Dutch government standards integration

***

## Configuring cases

{% stepper %}
{% step %}
Expand **Admin** in the left sidebar
{% endstep %}

{% step %}
Click **Cases** under the Configuration section

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-4b7b26803140f191d90cbd91b1842423c6575bd5%2F01-admin-cases-navigation.png?alt=media" alt=""><figcaption><p>Admin sidebar with Cases navigation</p></figcaption></figure>
{% endstep %}

{% step %}
Click a case row to open its configuration
{% endstep %}

{% step %}
Use the tabs to navigate between configuration areas

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-fba611a43768f511315bf387aeadce2021928e6e%2F02-case-configuration-tabs.png?alt=media" alt=""><figcaption><p>Case configuration tabs</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The cases list shows all defined case types with their name, key, current version, and status. Cases marked "Needs configuration" have unresolved configuration issues that should be addressed.

### Creating a case

To create a new case definition from scratch:

{% stepper %}
{% step %}
Click the **Create** button in the toolbar
{% endstep %}

{% step %}
Fill in the case definition details:

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-9d9853f42eaf679e775f8655997f26cdd1f3cc33%2F03-create-modal-empty.png?alt=media" alt=""><figcaption><p>Create case definition modal</p></figcaption></figure>

* **Name** — Display name for the case definition
* **Key** — Unique identifier (auto-generated from name, can be edited)
* **Version** — Semantic version number (e.g., `1.0.0`)
* **Description** — Optional description of what this case type handles

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-7f6266fe027d5a37d4223d21c61ccd3140792c87%2F04-create-modal-filled.png?alt=media" alt=""><figcaption><p>Create case definition with filled fields</p></figcaption></figure>
{% endstep %}

{% step %}
Click **Save** to create the case definition
{% endstep %}
{% endstepper %}

The new case opens in draft mode, ready for configuration.

### Uploading a case

To import an existing case definition package:

{% stepper %}
{% step %}
Click the **Upload** button in the toolbar
{% endstep %}

{% step %}
Select a `.zip` file containing the case definition

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-bfa4e0843c8934ac0c5db366f746fa74ee4e9051%2F05-upload-modal-file-select.png?alt=media" alt=""><figcaption><p>Upload case definition file select</p></figcaption></figure>
{% endstep %}

{% step %}
Configure the import settings:

* Review or modify the case name and key
* Map plugin configurations if the package uses plugins
  {% endstep %}

{% step %}
Click **Next** to proceed through the wizard steps
{% endstep %}

{% step %}
Click **Start upload** to import the case definition
{% endstep %}
{% endstepper %}

***

## Version management

Case definitions support versioning. The version selector in the header shows the current version and allows switching between versions.

Click the **Version management** button to access version management options.The deployment page shows version information and provides actions depending on the version status:

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-6e2590d07747638beb4b523c919ee5a5654931cc%2F06-version-selector-dropdown.png?alt=media" alt=""><figcaption><p>Version selector dropdown</p></figcaption></figure>

#### For published versions

* **Create draft version** — Create a new draft version based on this published version

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-8accff520d6f6845d314cacffd4f581530051925%2F10-deployment-published.png?alt=media" alt=""><figcaption><p>Published version deployment</p></figcaption></figure>

#### For draft versions

* **Finalize draft** — Publish the draft version (makes it available for new cases)
* **Delete draft** — Remove the draft version

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-648d935a141a561b7f56493f786e3f8db1ecd78e%2F08-deployment-draft.png?alt=media" alt=""><figcaption><p>Draft version deployment</p></figcaption></figure>

### Viewing all versions

Click **Show all versions** in the version selector to see a complete list of all versions for the case definition. This opens a modal with a paginated table showing all versions and their status (draft or published).

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-5cc523e6766a504b6c3494b0203e1dfc7015f2d7%2F13-show-all-versions-modal.png?alt=media" alt=""><figcaption><p>Show all versions modal</p></figcaption></figure>

{% hint style="info" %}
Most configuration changes are version-specific. When you modify a setting, it applies to the selected version only.
{% endhint %}

### Creating a draft version

To create a new draft version from a published version:

{% stepper %}
{% step %}
Navigate to the deployment page of a published version
{% endstep %}

{% step %}
Click **Create draft version**
{% endstep %}

{% step %}
Fill in the new version details:

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-f9f8016e796d5582ccc1f0d27a2f317bdc879d50%2F11-create-draft-modal.png?alt=media" alt=""><figcaption><p>Create draft version modal</p></figcaption></figure>

* **Name** — Display name for the case definition
* **Key** — Unique identifier (cannot be changed)
* **Version** — New version number (e.g., `1.1.0`)
* **Description** — Optional description of what this version changes
  {% endstep %}

{% step %}
Click **Save** to create the draft
{% endstep %}
{% endstepper %}

The new draft version opens in edit mode, ready for configuration changes.

### Finalizing a draft version

To publish a draft version:

{% stepper %}
{% step %}
Navigate to the deployment page of the draft version
{% endstep %}

{% step %}
Click **Finalize draft**
{% endstep %}

{% step %}
Review the confirmation message

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-96f26cbd33039084921252d34a0a91b149618923%2F09-finalize-confirmation.png?alt=media" alt=""><figcaption><p>Finalize confirmation modal</p></figcaption></figure>
{% endstep %}

{% step %}
Click **Finalize** to publish
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
After finalization, the version becomes read-only. Create a new draft to make further changes.
{% endhint %}

### Deleting a draft version

To delete a draft version:

{% stepper %}
{% step %}
Navigate to the deployment page of the draft version
{% endstep %}

{% step %}
Click **Delete draft**
{% endstep %}

{% step %}
Confirm the deletion in the modal
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Deleting a draft cannot be undone. All configuration changes in the draft will be lost.
{% endhint %}

### Setting the globally active version

The globally active version determines which version is used when creating new cases. To change it:

{% stepper %}
{% step %}
Select the version you want to activate
{% endstep %}

{% step %}
Click the **More** menu
{% endstep %}

{% step %}
Select **Set as active version**

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-c04d57020117e649ea0a124406d53780da0d1f1f%2F12-more-menu.png?alt=media" alt=""><figcaption><p>More menu with Set as active version option</p></figcaption></figure>
{% endstep %}

{% step %}
Confirm the change in the modal
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Setting an older version as globally active may affect new case creation if the older version lacks features or fields present in newer versions.
{% endhint %}

***

## Access control

Case access is controlled through the access control system. See [Access control](/configuration-guides/access-control.md) for details on configuring permissions.

| Resource type                                        | Action      | Description                    |
| ---------------------------------------------------- | ----------- | ------------------------------ |
| `com.ritense.case_.domain.definition.CaseDefinition` | `view`      | View a case definition         |
|                                                      | `view_list` | View case definitions in lists |