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.
This feature is different from the Process Exchange building blocks that you download and copy into projects. For those, see Process Exchange building blocks.
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.
How building blocks work
Create a building block definition (name, version, description).
Define the data it needs and the data it produces.
Add the processes and choose the main process.
Link the building block to a Call activity in a case process.
Map inputs and outputs, and choose when outputs are synced.
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.
Create 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.
Create a new building block
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.
General information and artwork
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 required fields so the case must provide them when using the building block.
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.
Processes inside the building block
When a building block has multiple processes, you can create call activities from one process to another. Set the process definition key and include a reference to the current building block in the Version tag field. The version tag has the format BB:<building-block-key>:<building-block-version>.
Link to a different process in the building block
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.
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.
Finalize a building block version
Use 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.
Call activity in a case process
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.
Select a building block and version
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.
If you are unsure, check the plugin documentation under Plugins.
Configure plugin mappings
4. Map inputs and sync outputs
Map Inputs from the case data to the building block fields.
The required inputs for the building block will be listed by default.
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
This is one way. Any changes to the case document will not be automatically synced to the building block instance.
Input and output mapping
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
Go to Admin → Building blocks.
Click Upload.
Select a .zip or .json export file and confirm the overwrite warning.
Follow the steps in the wizard.
Import a building block definition
Export
Open a building block.
Click More → Export.
Before importing, make sure any required process definitions or plugin configurations already exist in your environment.
