# Cases

## What is a case?

Case Management is a form of Business Process Automation. A 'Case' is created after an event, often a need from a person, organisation or external system. A case has the goal to fulfil this need, for example to answer the question, to ship the product or handle the complaint. After the result is achieved, the case is closed.

An example is the need for a permit to organize an event. After an application for a permit has been submitted (the trigger is always something that has happened - an event that took place), a case is created. If everything goes well from the applicant's perspective, this results in 'something': in this case, a permit.

A case is per definition short-lived, whereby the definition of 'short' can be discussed. However: a patient, car or tree are not 'short-lived' and so not a case within the definition of Case Management. To summarize: the case in Valtimo is a business process, with a clearly defined start and end.

### Cases and case definitions

To 'teach' Valtimo what it needs to do when it gets a request to execute a business process, models and definitions are used.

The definition of a business process is laid down in a _case definition_. Each _case_ is an instance of a _case definition_. A case definition contains everything the system needs to know to execute the business process from start to end. This entails the proces models, definitions of forms for user tasks, decision tables, the definition of the data to be stored, the definition of access rights and so forth.

{% hint style="info" %}
In the Valtimo admin-menu, and in the day-to-day talk between developers the term 'case' is used for 'case definition'. This can be confusing, since end users use the same term 'case' for the instance of the case.
{% endhint %}

{% hint style="info" %}
When you have a hammer, everything looks like a nail. Make sure to stick to a form of 'short lived'. While the length of 'short' can be debatable, creating everlasting cases is a risk. Bug fixing and fast improvement cycles can become complex when having to deal with long running cases. Since changes to the case definition do not change existing, running cases, case migration can be needed - which is complex, time consuming and error-prone.
{% endhint %}

### Data in a Case

Information provided by the event leading to the creation of the case is often the first data in the case. For example, a name, address and the complaint in case of a complaint process. During the proces of handeling the case, this data is enriched.

A definition of the data is made as part of a case definition. In the standard setup, this is a [document definition in JSON](case/document-definition).

The location of the data can be in- and outside Valtimo. The document is stored in the Valtimo database and forms the basis of a case. Data can also be stored in external systems - and referenced to. The case is conceptual: it is a reference to information - information can but does not have to be stored in the case.

{% hint style="info" %}
The design of the datamodel and JSON document definition(s) are an often underestimated aspect of the quality of the case definition. Be aware that changes to a data model can require migrations from running case instances and can have impact in other parts of the case definition.
{% endhint %}

{% hint style="info" %}
The document definition is non-relational. Do not try to convert a relational model into a document definition. Design and build a relational model and connect it via a plugin.
{% endhint %}

## Creating a case definition

{% tabs %}
{% tab title="Via UI" %}
* Go to the `Admin` menu
* Go to the `Cases` menu
* Click on **Create**
* Follow the steps of the wizard to create a new case definition

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2F6YLOJeL2l3HiCTvrAwg1%2FScreenshot%202025-06-19%20at%2021.18.36.png?alt=media&#x26;token=fe1ffe1d-b8d4-43bb-ae26-e8b89008d427" alt=""><figcaption><p>Creating a new case definition</p></figcaption></figure>

After saving the case definition configuration, the case management page is opened. This page provides an overview of all the different elements that can and need to be configured for the case.
{% endtab %}

{% tab title="Via IDE" %}
Case definitions can be created automatically by reading a configuration file. **This file will only be used when creating a case definition to avoid overriding user configuration.**

A file should be created on the classpath in the `*/resources/config/case/{case-definition-key}/{version-tag}/case/definition/` folder. The filename should be the name of the case definition and use the `.case-definition.json` file extension.

{% code title=".../resources/config/case/example/1-0-0/case/definition/example.case-definition.json" %}
```json
{
    "key": "example",
    "name": "Example Case Definition",
    "versionTag": "1.0.0-beta"
    "final": false,
    "canHaveAssignee": true
    "autoAssignTasks": true
}
```
{% endcode %}
{% endtab %}
{% endtabs %}

## Case definition versioning

{% hint style="success" %}
Available since Valtimo `13.0.0`
{% endhint %}

Each case can have multiple versions of the case definition.

{% tabs %}
{% tab title="Via UI" %}
The **version selector** on the case management page allows users to switch between the available versions of a case definition. It provides contextual access to view or modify case configurations, depending on the state of the selected version (_draft_ or _final_), while also clearly indicating which version is globally active.

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2FpgVjgZXNFSXIGwNP6HzC%2FScreenshot%202025-06-18%20at%2014.11.08.png?alt=media&#x26;token=37c71ee1-33fc-41e5-851b-5e47af75d50c" alt="" width="375"><figcaption><p>Case version selector</p></figcaption></figure>

Every version of a case definition can be categorized as either _draft_ or _final_**.**

* A _**draft**_ version represents a case definition configuration in progress. It allows users to modify all case-related configurations before finalization.&#x20;
* A _**final**_ version represents a deployed configuration of a case definition. All data associated with a final version is accessible in view mode only. No modifications are allowed.

{% hint style="info" %}
**Visual indicators**

* **Draft Versions** are labeled with a red tag and explicitly include the word _draft_**.**
* **Final versions** are marked with a green tag in the version selector.
{% endhint %}

#### _Globally active_ tag

The _Globally active_ tag indicates which version of the case definition is set as the default configuration that is used throughout the system. A version can be set as _Globally active_ on the case management page:

* Click on **More**
* Click on **Set as active version**

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2FT1woMHSrS8pYiIDdwGOH%2Fimage.png?alt=media&#x26;token=1dec9eb8-130c-48b4-a6ff-2e88e6c8aaff" alt=""><figcaption><p>Set as active version</p></figcaption></figure>

{% hint style="info" %}
**Note**

* Only one version can be globally active per case definition.
* This setting does **NOT** affect historical cases that were started from a previous version. It only applies to new cases after the change.
{% endhint %}

#### _See all versions_ modal

The version selector will show a maximum of five recent versions in the dropdown menu, and a sixth option, labeled **See all versions**, is provided at the end of the list.

Selecting **See all versions** opens a modal window containing:

* A full list of all available case definition versions.
* Metadata such as:
  * Version
  * Release date
  * Description
* The ability to select any version from this list.

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2FOmtmtHj4hV9oc8rSC3dj%2FScreenshot%202025-06-18%20at%2013.29.04.png?alt=media&#x26;token=5985fecd-9761-4220-bc61-e4c723b769fd" alt=""><figcaption><p><em>See all versions</em> modal</p></figcaption></figure>

#### Deployment

Before a case definition version can actually be used, it needs to be deployed first. This can be done on the case management page, by clicking on the **deployment** button.

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2FTw3nczJZ5CGmJDxrPqcM%2FScreenshot%202025-06-18%20at%2016.33.37.png?alt=media&#x26;token=08ab88ef-0ea0-4230-8a1c-f2ab168baadf" alt=""><figcaption><p>Case Details page</p></figcaption></figure>

When a draft version is selected, the **deployment** button enables direct actions to either finalize or discard the in-progress configuration.&#x20;

* Users can finalize a draft, promoting it to a final version. This locks the contents and makes it available for operational use.
* Draft versions can be removed permanently if no longer relevant or needed.&#x20;

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2FI8LJsCWimoRK8u97HnEf%2Fimage.png?alt=media&#x26;token=84010b46-4651-4927-891d-0ec08d45a0dd" alt=""><figcaption><p>Draft versison Deployment page</p></figcaption></figure>

{% hint style="danger" %}
**Warning**

Deleting a draft version is irreversible and will discard all changes made within that draft version.
{% endhint %}

When a _**final**_ version is selected, the **deployment** button serves as a reference point for stable configurations.&#x20;

* Users can create a new draft version based on any final version. This enables iteration or future changes without affecting the active version.

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2FlfTFfQLzGdkcuYo5612Z%2Fimage.png?alt=media&#x26;token=18fe3489-7b97-470a-9651-d0b6de871a37" alt=""><figcaption><p>Final version Deployment page</p></figcaption></figure>

&#x20;To create a new case definition version from an existing one:

* Click on **Deployment**&#x20;
* Click on **Create draft version** and configure a new draft version:

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2FCd4WACl0mOXnMHGOAbRA%2Fcreating-draft-form.png?alt=media&#x26;token=132a0721-f3cf-49dc-a2da-264004bca39c" alt=""><figcaption><p>Create a new version</p></figcaption></figure>

{% hint style="info" %}
**Note**

Final versions are immutable and cannot be modified directly. All changes must be performed through a new draft.
{% endhint %}
{% endtab %}

{% tab title="Via IDE" %}
A new version for a case definition can be created automatically by reading a configuration file. **This file will only be used when creating a case definition to avoid overriding user configuration.**

A file should be created on the classpath in the `*/resources/config/case/{case-definition-key}/{version-tag}/case/definition/` folder. The filename should be the name of the case definition and use the `.case-definition.json` file extension.

{% code title=".../resources/config/case/example/1-0-1/case/definition/example.case-definition.json" %}
```json
{
    "key": "example",
    "name": "Example Case Definition",
    "versionTag": "1.0.1-beta"
    "final": false,
    "canHaveAssignee": true
    "autoAssignTasks": true
}
```
{% endcode %}
{% endtab %}
{% endtabs %}

## Import and export

The **Import/Export** functionality enables users to seamlessly transfer complete case definition configurations between different environments (e.g., from a test/staging environment to acceptance or production). This ensures consistent deployment practices and reduces configuration errors across environments.

### Export <a href="#export" id="export"></a>

* Go to the `Admin` menu
* Go to the `Cases` menu, select the case you want to export
* Click on **More**
* Click on **Export**

<figure><img src="https://content.gitbook.com/content/q5dx9HWFJGshztp4binE/blobs/wp39yHeGlAl0OnJwMA1w/image%20(14)%20(1).png" alt=""><figcaption><p>Exporting a case definition</p></figcaption></figure>

A `.zip` file will be automatically downloaded. This file includes all configuration elements related to the currently selected version of the case definition, such as:

* Forms
* Processes
* Business rules
* UI configurations
* Permissions and metadata

The exported configuration serves as a portable package that can be used for version migration or replication across environments.

### Import <a href="#import" id="import"></a>

* Go to the `Admin` menu
* Go to the `Cases` menu, select the case to do an import in
* Click on **More**
* Click on **Import**
* Upload the exported `.zip` file.
* Follow the steps of the wizard to select the file and start the import
* The system will process the package and register it as a new draft version.

<figure><img src="https://content.gitbook.com/content/q5dx9HWFJGshztp4binE/blobs/VWGK0ovXFujh3gnOvTp7/image%20(15)%20(1).png" alt=""><figcaption><p>Importing a case definition</p></figcaption></figure>

{% hint style="warning" %}
**Please note**

* Importing a case definition always results in a _draft_ version, allowing final review and manual finalization before the configuration is used actively.
* All existing configurations will be overwritten by the configurations in the import.&#x20;
* Access control and plugin configurations are not part of a case definition import/export and most likely need to be configured first for the newly imported case and process definitions. A full list of configurations and definitions that are included and excluded from imports and exports can be found [here](#included-excluded-in-imports-exports).
{% endhint %}

### Recommended Workflow

{% stepper %}
{% step %}
### Develop and finalize in Test

Configure, iterate, and finalize the case definition in the test environment.
{% endstep %}

{% step %}
### Export

Once the version is finalized and validated, export it as a `.zip` file.
{% endstep %}

{% step %}
### Import to ACC

Import the package into the acceptance environment for QA or stakeholder review.
{% endstep %}

{% step %}
### Import to PROD

After approval, import the same package into production to make it available for live use.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Environment permissions and constraints**

To ensure consistency and quality across environments, the following restrictions apply:

* **Acceptance (ACC) and Production (PROD)** environments are in **read-only mode** by default.
  * Users cannot create, edit, or finalize versions manually.
  * Only **Import** and **Export** actions are permitted.
* This enforces a strict lifecycle where:
  * All case definitions must be **configured and finalized** in the **Test** environment first.
  * Only validated and exported configurations can be imported into ACC or PROD.
  * This minimizes the risk of untested or inconsistent configurations being promoted to live environments.
{% endhint %}

### Included/excluded in imports/exports

Most configurations and definitions are included in exports and imports. Some related configurations are not imported and exported, as they are not case definition specific.

| Included in the import/export             | Excluded from the import/export |
| ----------------------------------------- | ------------------------------- |
| Case definition settings                  | Access control                  |
| Decision definitions                      | Dashboards                      |
| Document definition                       | Plugin configurations           |
| Form flows                                |                                 |
| Forms (including case summary if present) |                                 |
| List columns                              |                                 |
| Process definitions                       |                                 |
| Process document associations             |                                 |
| Process links                             |                                 |
| Search fields                             |                                 |
| Tabs                                      |                                 |
| Task list columns                         |                                 |
| ZGW Document columns                      |                                 |
