Valtimo documentation
  • Welcome to Valtimo
  • Fundamentals
    • â„šī¸What is Valtimo
    • đŸ™ī¸Architectural overview
      • Choosing the right setup
      • âš™ī¸Available modules
    • Process Exchange
      • Process blueprints
      • Building blocks
    • 📖How to use this documentation
    • đŸ–ąī¸Getting started
      • Configuring the database
      • Modules
        • Core modules
          • Audit
          • Authorization
          • Camunda
          • Case
          • Connector
          • Contract
          • Core
          • Dashboard
          • Document
          • Document generation
          • Exporter
          • Form
          • Form flow
          • Form flow Valtimo
          • Importer
          • Localization
          • Local document generation
          • Local mail
          • Mail
          • Mandrill
          • Milestones
          • Plugins
          • Outbox
            • Outbox RabbitMQ
          • Process document
          • Resource
          • Temporary resource storage
          • Test utils common
          • Value resolvers
          • Valtimo dependencies
          • Valtimo dependency versions
          • Web
            • CORS
        • GZAC modules
          • Besluit
          • Besluiten API
          • Catalogi API
          • Contactmoment
          • Documenten API
          • Haalcentraal BRP
          • Klant
          • Notificaties API
          • Notificaties API Authentication
          • Objecten API
          • Objecten API Authentication
          • Object management
          • Objects API
          • Objecttypen API
          • OpenZaak
          • OpenZaak Plugin Authentication
          • OpenZaak resource
          • Portaaltaak
          • SmartDocuments
          • Valtimo GZAC dependencies
          • Verzoek
          • Wordpress mail
          • Zaken API
      • Compatibility matrix
  • Features
    • 🔏Access control
      • Configurable elements
      • Configuring roles
      • Configuring permissions
      • Configuring conditions
      • Configuring context conditions
      • For developers
        • Front-end access control
        • Creating a resource
        • Creating a relation to another resource
        • Running custom code without access control
    • đŸ—ƒī¸Case
      • Configuration
      • Document definition
      • List
      • Notes
      • Processes
      • Search fields
      • Statuses
      • Tabs
      • Tags
      • Widgets
        • Fields widget
        • Custom component widget
        • Form.io widget
        • Table widget
        • Collection widget
      • For developers
        • Search fields API
        • Case list tab order
        • Custom case list columns
        • Custom case tabs
        • Case migration
        • Custom case headers
        • Register Angular component
    • 📊Dashboard
      • Widget data sources
      • Widget display types
      • For developers
        • Custom dashboards
        • Custom data sources
        • Custom display types
        • Widget translations
    • 📋Forms
      • Creating FormIO forms in Valtimo
      • Interpolating data in Form.io
      • Configuring an Objecten API object form
      • For developers
        • Form field data resolver
    • 🔀Form flow
      • Creating a form flow definition
      • For developers
        • Custom form flow component
        • Whitelisting Spring beans for Form flow
    • 🌍Localization
      • For developers
    • Logging
      • For developers
    • âœ‰ī¸Outbox
      • For developers
    • 🔌Plugins
      • Configuring plugins
      • SmartDocuments plugin
      • Exact Plugin
      • For developers
        • Custom plugin definitions
    • ⭕Process
      • System processes
      • Correlating messages
      • Job service
      • For developers
        • Integrating spring beans in a process
        • Whitelisting Spring beans for Camunda
    • 🔗Process links
      • Creating a process link
      • Editing a process link
      • Unlinking a process link
    • ✅Tasks
      • Task list columns
    • đŸ”ĸValue resolvers
      • For developers
    • 📃ZGW
      • Documents
        • Access control
        • Uploading to Documenten API with metadata
      • Creating extra case tabs for Zaakobjects
      • ZGW plugins
        • Besluiten Plugin
        • Catalogi API plugin
        • Documenten API plugin
        • Object Token Auhentication Plugin
        • Objecten API Plugin
        • Objecttypen API Plugin
        • Open Zaak plugin
        • Portaaltaak Plugin
        • Verzoek Plugin
        • Zaken API plugin
  • Release notes
    • Release notes
    • 12.x.x
      • 12.13.0 (backend only)
      • 12.12.0
      • 12.11.0
      • 12.10.0
        • 12.10.1
        • 12.10.2
      • 12.9.0
      • 12.8.0
      • 12.7.0
        • 12.7.1
        • 12.7.2
      • 12.6.0
        • 12.6.1
      • 12.5.0
      • 12.4.0
        • 12.4.1
      • 12.3.0
        • 12.3.1
      • 12.2.0
      • 12.1.0
      • 12.0.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
        • Migration
          • Spring Boot 3
    • 11.x.x
      • 11.3.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 11.2.0 (RC)
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 11.1.5
        • Valtimo frontend libraries
      • 11.1.4
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 11.1.1
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 11.1.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 11.0.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
        • Migration
    • 10.x.x
      • 10.8.3
        • Valtimo backend libraries
      • 10.8.2
        • Valtimo frontend libraries
      • 10.8.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 10.7.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 10.6.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
        • Migration
      • 10.5.3
        • Valtimo backend libraries
      • 10.5.2
        • Valtimo backend libraries
      • 10.5.1
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 10.5.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
        • Migration
      • 10.4.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 10.3.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 10.2.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
      • 10.1.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
        • Migration
      • 10.0.1
        • Valtimo frontend libraries
      • 10.0.0
        • Valtimo backend libraries
        • Valtimo frontend libraries
        • Migration
    • 9.x.x
      • 9.26.2/5.15.1
        • Valtimo backend libraries (9.26.2)
        • Migration
      • 9.26.1/5.15.1
        • Valtimo backend libraries (9.26.1)
        • Valtimo frontend libraries (5.15.1)
      • 9.26.0/5.15.0
        • Valtimo backend libraries (9.26.0)
        • Valtimo frontend libraries (5.15.0)
        • Migration
      • 9.25.0/5.14.0
        • Valtimo backend libraries (9.25.0)
        • Valtimo frontend libraries (5.14.0)
      • 9.24.0/5.13.0
        • Valtimo backend libraries (9.24.0)
        • Valtimo frontend libraries (5.13.0)
      • 9.23.0/5.12.0
        • Valtimo backend libraries (9.23.0)
        • Valtimo frontend libraries (5.12.0)
      • 9.22.0/5.11.0
        • Valtimo backend libraries (9.22.0)
        • Valtimo frontend libraries (5.11.0)
        • Migration
      • 9.21.0/5.10.0
        • Valtimo backend libraries (9.21.0)
        • Valtimo frontend libraries (5.10.0)
        • Migration
      • 9.20.0/5.9.1
        • Valtimo backend libraries (9.20.0)
        • Valtimo frontend libraries (5.9.1)
        • Migration
      • 9.19.0/5.8.0
        • Valtimo backend libraries (9.19.0)
        • Valtimo frontend libraries (5.8.0)
        • Migration
      • 9.18.0/5.6.0
        • Valtimo backend libraries (9.18.0)
        • Valtimo frontend libraries (5.6.0)
        • Migration
      • 9.17.0/5.5.0
        • Valtimo backend libraries (9.17.0)
        • Valtimo frontend libraries (5.5.0)
      • 9.16.0/5.4.0
        • Valtimo backend libraries (9.16.0)
        • Valtimo frontend libraries (5.4.0)
  • Running Valtimo
    • Application configuration
      • Temporary file-storage
      • Configuring CORS
      • REST API endpoint security test
      • Content Security Policy (CSP)
      • Configuring Keycloak
      • Temporary file storage
      • Feature toggles
  • Customizing Valtimo
    • Front-end customization
      • Customizing Carbon theme
      • Custom logo
      • Custom components
        • Custom case management tab
  • Contributing to Valtimo
    • Contributing to Valtimo
    • Docs style guide for contributing
    • Branching and release strategy
    • Extend the core or build a plugin
Powered by GitBook
On this page
  • Creating a document definition
  • Editing a document definition
  • Access control
  • Resources and actions
  • Examples

Was this helpful?

  1. Features
  2. Case

Document definition

PreviousConfigurationNextList

Last updated 4 months ago

Was this helpful?

A document definition is the blueprint for the JSON documents that are created when creating new cases in Valtimo. It defines the structure of the case and contains validation rules for the data that is stored by the actual JSON documents that are created when executing processes for that case in Valtimo. This page shows how to create a document definition, and how to add validation to properties.

This page requires:

  • Knowledge of

Creating a document definition

There are three ways of creating new document definitions in Valtimo.

  • Upload a valid JSON schema via the UI

  • Create an empty case via the UI

  • Place a valid JSON schema in the codebase via an IDE

Best practices:

  • Always create a JSON schema. A JSON schema enforces a certain quality for each document. Experience shows that a JSON schema is necessary for production-grade systems.

  • Ensure a stable design and minimize changes to the model. Discuss the impact of changes thoroughly before implementing them. For example, if in a version 2 of the schema an attribute is made mandatory that wasn't required in version 1, the forms that provide this data must be duplicated and adapted to the new Document Definition.

  • The case detail object must be usable for Formio forms. Complexities such as arrays within arrays can complicate the form-building process. Tip: do not blindly adopt a JSON schema from a source.

  • Do not store technical or control information in the JSON document. Process variables are available for this.

  • Do store information that is needed in case search and case list pages. Though information from external sources can be displayed in a Case, it cannot be used to search or filter on.

Upload a valid JSON schema

  • Go to the Admin menu

  • Go to the Cases menu

  • Click on Upload case-definition

  • Upload the document definition

It's possible to upload valid JSON schemas to create new cases since Valtimo 5. During the upload the JSON schema structure is validated and the uniqueness of the case ID is checked. If no validation errors occur, the JSON schema is uploaded and the case definition is created.

In Valtimo 12 the case configuration upload has been improved by adding all the newly available case configurations to the upload functionality. More detailed information on this functionality can be found .

Create an empty case

Available since Valtimo 12

  • Go to the Admin menu

  • Go to the Cases menu

  • Click on Create

  • Enter the title, and optionally edit the name

  • Click on Save, this takes you to the document definition overview

The chosen title will be validated and based upon the title a read-only case definition name will be generated. This is to create a unique identifier for that case definition without spaces or special characters. Click the Save button to create the case with the chosen title. The case definition is created and the case details page is displayed upon completion. A valid empty JSON schema is created with the title and id based on the given title.

Please note

The properties section is empty. This section contains the data structure for the case. The case JSON schema validation has to be placed here.

The option additionalProperties is set to false by default. This disables the possibility to save other data than configured in the properties section of the document definition.

When uploading a JSON schema to create a new case, make sure that the $id and title fields both have the correct value. These fields are used when a case definition is uploaded and will be displayed in the case list view.

Place a valid JSON schema in the codebase

To create a document definition, the following steps are necessary:

  • Create a document definition file (ending with .schema.json) under the following path: /src/main/resources/config/document/definition. The name should correspond with the ID of the document ID. The ID itself should end with .schema.

    person.schema.json

    {
      "$id": "person.schema",
      "$schema": "http://json-schema.org/draft-07/schema#",
      "title": "Person",
      "type": "object",
      "properties": {
      }
    }

  • {
      "$id": "person.schema",
      "$schema": "http://json-schema.org/draft-07/schema#",
      "title": "Person",
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string",
          "description": "The person's first name.",
          "maxLength": 15
        },
        "age": {
          "description": "Age in years which must be equal to or greater than zero.",
          "type": "integer",
          "minimum": 0
        },
        "birthday": {
          "description": "Birthday",
          "type": "string",
          "format": "date"
        },
        "hasPet": {
          "description": "Has pet.",
          "type": "boolean"
        }
      }
    }

Editing a document definition

Same as for creating cases there are three ways of editing document definitions.

  • Upload a valid JSON schema with the same ID.

  • Edit the document definition directly via the UI.

  • Edit the document definition in the codebase via an IDE.

Upload a valid JSON schema with the same ID

  • Go to the Admin menu

  • Go to the Cases menu

Click on the Upload button to open the Import case definition . This modal contains a wizard that will guide users through the import process. The following steps are defined in this wizard.

  1. Informative step regarding plugins.

  2. Select the edited document definition from your system When the file is succesfully uploaded a warning is displayed that current configurations for that case can be overwritten by this upload.

  3. Start the upload The file will be validated and if it passes all checks the document definition is updated.

Edit the document definition

  • Go to the Admin menu

  • Go to the Cases menu

  • Select the case that you want to edit

  • Click on Edit

  • Edit the document definition as per the JSON schema standard

  • Click on Save

Visually nothing happens when switching to edit mode. Only the Download and Edit buttons are replaced by a Cancel and a Save button. The Save button is disabled by default until valid changes are made.

Constant validation

In edit mode, the UI editor will constantly validate the JSON file structure. The Save button is only available when the JSON structure is valid. Errors in the file structure will be indicated with a red curly line below or near the issue. In large files, errors can easily be found with the minimised tree view on the right side of the editor.

Edit the document definition in the codebase

Please note

Changes to document definitions have immediate effect on newly created cases based on this document definition. Changing this file means changing the blueprint that is used to validate each case that is created in Valtimo based on this blueprint. Changes will have impact, so create backups when unsure of the result.

Access control

Resources and actions

Resource type
Action
Effect

com.ritense.document.domain.impl.JsonSchemaDocument

assign

Allows assigning users to a case document.

assignable

Allows users to be assigned to a case document.

create

Allows creating of a case document.

claim

Allows claiming of a case document.

delete

Allows deleting of a case document.

modify

Allows modifying of a case document.

view

Allows viewing of a case document.

view_list

Allows viewing of case documents.

com.ritense.document.domain.impl.JsonSchemaDocumentDefinition

create

Allows creating of a case document definition.

delete

Allows deleting of a case document definition.

modify

Allows modifying of a case document definition.

view

Allows viewing of a case document definition.

view_list

Allows viewing of case document definitions.

Examples

Permission to view access to all case document definitions
{
    "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocumentDefinition",
    "action": "view",
    "conditions": []
}
Permission to view access to all documents of one case document definition
{
   "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocument",
   "action": "view",
   "conditions": [
      {
         "type": "field",
         "field": "documentDefinitionId.name",
         "operator": "==",
         "value": "evenementenvergunning"
      }
   ]
}
Permission to view access to one specific document definition
{ 
   "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocumentDefinition",
   "action": "view",
   "conditions": [
      {
         "type": "field",
         "field": "id.name",
         "operator": "==",
         "value": "evenementenvergunning"
      }
   ]
}

Properties as well as validation rules can be added to the definition as per the JSON schema standard as seen . Below is an example of what this definition could look like.

Open the document definition in the IDE and edit the definition as per the JSON schema standard. More information on JSON schema can be found . The location of the document definitions in the Valtimo Java/Kotlin backend: /src/main/resources/config/document/definition Changes will only be available in the application once the changes have been deployed via the CI/CD pipeline.

Access to document definitions can be configured through access control. More information about access control can be found .

đŸ—ƒī¸
here
here
here
JSON schema
here
Uploading a document definition
Creating a document definition
Newly created example case
JSON structure validation in edit mode