# Building blocks ## What are building blocks? Building blocks let you package a reusable subprocess with its own data model and version it separately from cases. This allows them to use their own data and configuration. You can use the same building block in multiple case definitions and across environments, while keeping a clear input and output contract. Building blocks are isolated by design. They should not directly read or write case data. Instead, you define the inputs and outputs when you link them to a case. This isolation ensures that building blocks remain reusable and maintainable across different contexts. The building block lifecycle follows these steps: 1. Create a building block definition (name, version, description). 2. Define the data it needs and the data it produces. 3. Add the processes and choose the main process. 4. Link the building block to a **Call activity** in a case process. 5. Map inputs and outputs, and choose when outputs are synced. ### When to use building blocks Building blocks are useful when: * The same subprocess is needed in multiple cases. * You want one place to update a shared step. * You want a consistent way to pass data in and get results back. **Example:** A "Household verification" building block can be used in both subsidy and permit cases. Each case passes in the citizen data, the building block runs the checks, and the outcome is synced back to the case. {% hint style="info" %} This feature is different from the Process Exchange building blocks that you download and copy into projects. For those, see [Process Exchange building blocks](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/fundamentals/process-exchange/building-blocks.md). {% endhint %} ## Creating a building block ### 1. Create the definition * Go to **Admin** in the left sidebar. * Select **Building blocks**. * Click **Create**. * Enter a **Name**, **Version**, and (optional) **Description**. * Click **Save**.

### 2. Add general information * Open the **General** tab. * Optionally upload **Artwork**. * Review the list of **Plugins used** so you know which plugin types must be configured later. Initially, the list will be empty. This will be updated as you add plugins or other building blocks to the processes of your building block.

### 3. Define the data fields * Open the **Document** tab. * Add the fields the building block needs (inputs) and may return (outputs) and any other data the building block will need to use internally. * Mark fields as required if the case must provide them when using the building block. Required fields must be mapped in the input mapping when linking the building block to a case. * Click **Save**.

Define data fields for the building block

### 4. Add processes * Open the **Processes** tab. * Either **Upload** a BPMN file or **Create** a new process. * Select which process should be the **Main process** for the building block, or use the process that has been created with the building block. * You can use plugins in these processes just like in case processes, but you select the plugin type instead of a specific configuration.

* When a building block has multiple processes, you can create call activities from one process to another. Set the process definition key (the **Key** value shown in the processes list) and include a reference to the current building block in the **Version tag** field. The version tag has the format `BB::`.

Link to a different process in the building block

{% hint style="warning" %} User tasks are not yet supported in building blocks. This means form, form flow, and custom UI component process links cannot be used. Only plugin and building block process links are available. {% endhint %} ### 5. Finalize the version Building blocks use **draft** and **final** versions, similar to case definitions. Before you finalize, **test the building block thoroughly**. Final versions cannot be changed. * In the **More** menu, choose **Make version final** to lock the version. * To make changes later, create a **new draft** from a final version. Only **final** building blocks can be used when finalizing a case definition.

## Using a building block in a case ### 1. Add a Call activity * Open the case process where you want to use the building block. * Add a **Call activity** to the process model.

### 2. Link the building block * Open the **Process link** for the Call activity. * Choose **Building block** as the link type. * Choose the **Building block** you want to use.

### 3. Configure plugin mappings * Select the building block **Version** you want to use. If this version uses plugins, you must map each **plugin type** to a **plugin configuration** that already exists in your environment. * Select the saved plugin configuration for each plugin type.

### 4. Map inputs and sync outputs * Map **Inputs** from the case data to the building block fields. * All required fields (marked as required in the building block document definition) are listed by default and must be mapped. * Any optional inputs can be added manually by clicking **Add input**. * Map **Outputs** from the building block back to the case. * Fields can be added for syncing by clicking **Add sync**. * When the building block completes, the specified fields are written from the building block back to the case document. * This is one way. Any changes to the case document will not be automatically synced to the building block instance.

### 5. Save and deploy * Click **Complete** to save the process link. * Save and deploy the updated case process. ## Import and export building blocks Building blocks are automatically included in case definition exports. You can also export or import a building block separately when you want to move or reuse it on its own. ### Import {% hint style="info" %} Before importing, make sure any required process definitions or plugin configurations already exist in your environment. {% endhint %} * Go to **Admin** → **Building blocks**. * Click **Upload**. * Select a `.zip` export file. * Confirm the overwrite warning. This will replace all existing resources (document definition, processes, and settings) for this building block version if it already exists in your environment. * Follow the steps in the wizard.

### Export * Open a building block. * Click **More** → **Export**.

## Related * [Cases](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/configuration-guides/cases/README.md) - Building blocks are used within case processes * [Plugins](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/configuration-guides/plugins/README.md) - Building blocks can use plugin types * [Processes](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/configuration-guides/cases/processes.md) - Understanding process links and call activities * [Process Exchange building blocks](https://github.com/valtimo-platform/valtimo-docs-v3/blob/main/fundamentals/process-exchange/building-blocks.md) - Different type of building blocks